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 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{}