libgo/go/crypto/crypto.go

   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 func (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
  68 const (
  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
  91 var 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.
 116 func (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
 123 var 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.
 127 func (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.
 138 func (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.
 145 func 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.
 162 type 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.
 176 type 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.
 180 type 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.
 202 type 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.
 212 type 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
 223 type DecrypterOpts any