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. 6 package crypto 7 8 import ( 9 "hash" 10 "io" 11 "strconv" 12 ) 13 14 // Hash identifies a cryptographic hash function that is implemented in another 15 // package. 16 type Hash uint 17 18 // HashFunc simply returns the value of h so that Hash implements SignerOpts. 19 func (h Hash) HashFunc() Hash { 20 return h 21 } 22 23 const ( 24 MD4 Hash = 1 + iota // import golang.org/x/crypto/md4 25 MD5 // import crypto/md5 26 SHA1 // import crypto/sha1 27 SHA224 // import crypto/sha256 28 SHA256 // import crypto/sha256 29 SHA384 // import crypto/sha512 30 SHA512 // import crypto/sha512 31 MD5SHA1 // no implementation; MD5+SHA1 used for TLS RSA 32 RIPEMD160 // import golang.org/x/crypto/ripemd160 33 SHA3_224 // import golang.org/x/crypto/sha3 34 SHA3_256 // import golang.org/x/crypto/sha3 35 SHA3_384 // import golang.org/x/crypto/sha3 36 SHA3_512 // import golang.org/x/crypto/sha3 37 SHA512_224 // import crypto/sha512 38 SHA512_256 // import crypto/sha512 39 BLAKE2s_256 // import golang.org/x/crypto/blake2s 40 BLAKE2b_256 // import golang.org/x/crypto/blake2b 41 BLAKE2b_384 // import golang.org/x/crypto/blake2b 42 BLAKE2b_512 // import golang.org/x/crypto/blake2b 43 maxHash 44 ) 45 46 var digestSizes = []uint8{ 47 MD4: 16, 48 MD5: 16, 49 SHA1: 20, 50 SHA224: 28, 51 SHA256: 32, 52 SHA384: 48, 53 SHA512: 64, 54 SHA512_224: 28, 55 SHA512_256: 32, 56 SHA3_224: 28, 57 SHA3_256: 32, 58 SHA3_384: 48, 59 SHA3_512: 64, 60 MD5SHA1: 36, 61 RIPEMD160: 20, 62 BLAKE2s_256: 32, 63 BLAKE2b_256: 32, 64 BLAKE2b_384: 48, 65 BLAKE2b_512: 64, 66 } 67 68 // Size returns the length, in bytes, of a digest resulting from the given hash 69 // function. It doesn't require that the hash function in question be linked 70 // into the program. 71 func (h Hash) Size() int { 72 if h > 0 && h < maxHash { 73 return int(digestSizes[h]) 74 } 75 panic("crypto: Size of unknown hash function") 76 } 77 78 var hashes = make([]func() hash.Hash, maxHash) 79 80 // New returns a new hash.Hash calculating the given hash function. New panics 81 // if the hash function is not linked into the binary. 82 func (h Hash) New() hash.Hash { 83 if h > 0 && h < maxHash { 84 f := hashes[h] 85 if f != nil { 86 return f() 87 } 88 } 89 panic("crypto: requested hash function #" + strconv.Itoa(int(h)) + " is unavailable") 90 } 91 92 // Available reports whether the given hash function is linked into the binary. 93 func (h Hash) Available() bool { 94 return h < maxHash && hashes[h] != nil 95 } 96 97 // RegisterHash registers a function that returns a new instance of the given 98 // hash function. This is intended to be called from the init function in 99 // packages that implement hash functions. 100 func RegisterHash(h Hash, f func() hash.Hash) { 101 if h >= maxHash { 102 panic("crypto: RegisterHash of unknown hash function") 103 } 104 hashes[h] = f 105 } 106 107 // PublicKey represents a public key using an unspecified algorithm. 108 type PublicKey interface{} 109 110 // PrivateKey represents a private key using an unspecified algorithm. 111 type PrivateKey interface{} 112 113 // Signer is an interface for an opaque private key that can be used for 114 // signing operations. For example, an RSA key kept in a hardware module. 115 type Signer interface { 116 // Public returns the public key corresponding to the opaque, 117 // private key. 118 Public() PublicKey 119 120 // Sign signs digest with the private key, possibly using entropy from 121 // rand. For an RSA key, the resulting signature should be either a 122 // PKCS#1 v1.5 or PSS signature (as indicated by opts). For an (EC)DSA 123 // key, it should be a DER-serialised, ASN.1 signature structure. 124 // 125 // Hash implements the SignerOpts interface and, in most cases, one can 126 // simply pass in the hash function used as opts. Sign may also attempt 127 // to type assert opts to other types in order to obtain algorithm 128 // specific values. See the documentation in each package for details. 129 // 130 // Note that when a signature of a hash of a larger message is needed, 131 // the caller is responsible for hashing the larger message and passing 132 // the hash (as digest) and the hash function (as opts) to Sign. 133 Sign(rand io.Reader, digest []byte, opts SignerOpts) (signature []byte, err error) 134 } 135 136 // SignerOpts contains options for signing with a Signer. 137 type SignerOpts interface { 138 // HashFunc returns an identifier for the hash function used to produce 139 // the message passed to Signer.Sign, or else zero to indicate that no 140 // hashing was done. 141 HashFunc() Hash 142 } 143 144 // Decrypter is an interface for an opaque private key that can be used for 145 // asymmetric decryption operations. An example would be an RSA key 146 // kept in a hardware module. 147 type Decrypter interface { 148 // Public returns the public key corresponding to the opaque, 149 // private key. 150 Public() PublicKey 151 152 // Decrypt decrypts msg. The opts argument should be appropriate for 153 // the primitive used. See the documentation in each implementation for 154 // details. 155 Decrypt(rand io.Reader, msg []byte, opts DecrypterOpts) (plaintext []byte, err error) 156 } 157 158 type DecrypterOpts interface{} 159