1// Copyright 2011 The Go Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style
3// license that can be found in the LICENSE file.
4
5// Package crypto collects common cryptographic constants.
6package crypto
7
8import (
9	"hash"
10	"io"
11	"strconv"
12)
13
14// Hash identifies a cryptographic hash function that is implemented in another
15// package.
16type Hash uint
17
18// HashFunc simply returns the value of h so that Hash implements SignerOpts.
19func (h Hash) HashFunc() Hash {
20	return h
21}
22
23func (h Hash) String() string {
24	switch h {
25	case MD4:
26		return "MD4"
27	case MD5:
28		return "MD5"
29	case SHA1:
30		return "SHA-1"
31	case SHA224:
32		return "SHA-224"
33	case SHA256:
34		return "SHA-256"
35	case SHA384:
36		return "SHA-384"
37	case SHA512:
38		return "SHA-512"
39	case MD5SHA1:
40		return "MD5+SHA1"
41	case RIPEMD160:
42		return "RIPEMD-160"
43	case SHA3_224:
44		return "SHA3-224"
45	case SHA3_256:
46		return "SHA3-256"
47	case SHA3_384:
48		return "SHA3-384"
49	case SHA3_512:
50		return "SHA3-512"
51	case SHA512_224:
52		return "SHA-512/224"
53	case SHA512_256:
54		return "SHA-512/256"
55	case BLAKE2s_256:
56		return "BLAKE2s-256"
57	case BLAKE2b_256:
58		return "BLAKE2b-256"
59	case BLAKE2b_384:
60		return "BLAKE2b-384"
61	case BLAKE2b_512:
62		return "BLAKE2b-512"
63	default:
64		return "unknown hash value " + strconv.Itoa(int(h))
65	}
66}
67
68const (
69	MD4         Hash = 1 + iota // import golang.org/x/crypto/md4
70	MD5                         // import crypto/md5
71	SHA1                        // import crypto/sha1
72	SHA224                      // import crypto/sha256
73	SHA256                      // import crypto/sha256
74	SHA384                      // import crypto/sha512
75	SHA512                      // import crypto/sha512
76	MD5SHA1                     // no implementation; MD5+SHA1 used for TLS RSA
77	RIPEMD160                   // import golang.org/x/crypto/ripemd160
78	SHA3_224                    // import golang.org/x/crypto/sha3
79	SHA3_256                    // import golang.org/x/crypto/sha3
80	SHA3_384                    // import golang.org/x/crypto/sha3
81	SHA3_512                    // import golang.org/x/crypto/sha3
82	SHA512_224                  // import crypto/sha512
83	SHA512_256                  // import crypto/sha512
84	BLAKE2s_256                 // import golang.org/x/crypto/blake2s
85	BLAKE2b_256                 // import golang.org/x/crypto/blake2b
86	BLAKE2b_384                 // import golang.org/x/crypto/blake2b
87	BLAKE2b_512                 // import golang.org/x/crypto/blake2b
88	maxHash
89)
90
91var digestSizes = []uint8{
92	MD4:         16,
93	MD5:         16,
94	SHA1:        20,
95	SHA224:      28,
96	SHA256:      32,
97	SHA384:      48,
98	SHA512:      64,
99	SHA512_224:  28,
100	SHA512_256:  32,
101	SHA3_224:    28,
102	SHA3_256:    32,
103	SHA3_384:    48,
104	SHA3_512:    64,
105	MD5SHA1:     36,
106	RIPEMD160:   20,
107	BLAKE2s_256: 32,
108	BLAKE2b_256: 32,
109	BLAKE2b_384: 48,
110	BLAKE2b_512: 64,
111}
112
113// Size returns the length, in bytes, of a digest resulting from the given hash
114// function. It doesn't require that the hash function in question be linked
115// into the program.
116func (h Hash) Size() int {
117	if h > 0 && h < maxHash {
118		return int(digestSizes[h])
119	}
120	panic("crypto: Size of unknown hash function")
121}
122
123var hashes = make([]func() hash.Hash, maxHash)
124
125// New returns a new hash.Hash calculating the given hash function. New panics
126// if the hash function is not linked into the binary.
127func (h Hash) New() hash.Hash {
128	if h > 0 && h < maxHash {
129		f := hashes[h]
130		if f != nil {
131			return f()
132		}
133	}
134	panic("crypto: requested hash function #" + strconv.Itoa(int(h)) + " is unavailable")
135}
136
137// Available reports whether the given hash function is linked into the binary.
138func (h Hash) Available() bool {
139	return h < maxHash && hashes[h] != nil
140}
141
142// RegisterHash registers a function that returns a new instance of the given
143// hash function. This is intended to be called from the init function in
144// packages that implement hash functions.
145func RegisterHash(h Hash, f func() hash.Hash) {
146	if h >= maxHash {
147		panic("crypto: RegisterHash of unknown hash function")
148	}
149	hashes[h] = f
150}
151
152// PublicKey represents a public key using an unspecified algorithm.
153//
154// Although this type is an empty interface for backwards compatibility reasons,
155// all public key types in the standard library implement the following interface
156//
157//     interface{
158//         Equal(x crypto.PublicKey) bool
159//     }
160//
161// which can be used for increased type safety within applications.
162type PublicKey any
163
164// PrivateKey represents a private key using an unspecified algorithm.
165//
166// Although this type is an empty interface for backwards compatibility reasons,
167// all private key types in the standard library implement the following interface
168//
169//     interface{
170//         Public() crypto.PublicKey
171//         Equal(x crypto.PrivateKey) bool
172//     }
173//
174// as well as purpose-specific interfaces such as Signer and Decrypter, which
175// can be used for increased type safety within applications.
176type PrivateKey any
177
178// Signer is an interface for an opaque private key that can be used for
179// signing operations. For example, an RSA key kept in a hardware module.
180type Signer interface {
181	// Public returns the public key corresponding to the opaque,
182	// private key.
183	Public() PublicKey
184
185	// Sign signs digest with the private key, possibly using entropy from
186	// rand. For an RSA key, the resulting signature should be either a
187	// PKCS #1 v1.5 or PSS signature (as indicated by opts). For an (EC)DSA
188	// key, it should be a DER-serialised, ASN.1 signature structure.
189	//
190	// Hash implements the SignerOpts interface and, in most cases, one can
191	// simply pass in the hash function used as opts. Sign may also attempt
192	// to type assert opts to other types in order to obtain algorithm
193	// specific values. See the documentation in each package for details.
194	//
195	// Note that when a signature of a hash of a larger message is needed,
196	// the caller is responsible for hashing the larger message and passing
197	// the hash (as digest) and the hash function (as opts) to Sign.
198	Sign(rand io.Reader, digest []byte, opts SignerOpts) (signature []byte, err error)
199}
200
201// SignerOpts contains options for signing with a Signer.
202type SignerOpts interface {
203	// HashFunc returns an identifier for the hash function used to produce
204	// the message passed to Signer.Sign, or else zero to indicate that no
205	// hashing was done.
206	HashFunc() Hash
207}
208
209// Decrypter is an interface for an opaque private key that can be used for
210// asymmetric decryption operations. An example would be an RSA key
211// kept in a hardware module.
212type Decrypter interface {
213	// Public returns the public key corresponding to the opaque,
214	// private key.
215	Public() PublicKey
216
217	// Decrypt decrypts msg. The opts argument should be appropriate for
218	// the primitive used. See the documentation in each implementation for
219	// details.
220	Decrypt(rand io.Reader, msg []byte, opts DecrypterOpts) (plaintext []byte, err error)
221}
222
223type DecrypterOpts any
224