src/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 code.google.com/p/go.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 code.google.com/p/go.crypto/ripemd160
  33         SHA3_224                  // import code.google.com/p/go.crypto/sha3
  34         SHA3_256                  // import code.google.com/p/go.crypto/sha3
  35         SHA3_384                  // import code.google.com/p/go.crypto/sha3
  36         SHA3_512                  // import code.google.com/p/go.crypto/sha3
  37         maxHash
  38 )
  39
  40 var digestSizes = []uint8{
  41         MD4:       16,
  42         MD5:       16,
  43         SHA1:      20,
  44         SHA224:    28,
  45         SHA256:    32,
  46         SHA384:    48,
  47         SHA512:    64,
  48         SHA3_224:  28,
  49         SHA3_256:  32,
  50         SHA3_384:  48,
  51         SHA3_512:  64,
  52         MD5SHA1:   36,
  53         RIPEMD160: 20,
  54 }
  55
  56 // Size returns the length, in bytes, of a digest resulting from the given hash
  57 // function. It doesn't require that the hash function in question be linked
  58 // into the program.
  59 func (h Hash) Size() int {
  60         if h > 0 && h < maxHash {
  61                 return int(digestSizes[h])
  62         }
  63         panic("crypto: Size of unknown hash function")
  64 }
  65
  66 var hashes = make([]func() hash.Hash, maxHash)
  67
  68 // New returns a new hash.Hash calculating the given hash function. New panics
  69 // if the hash function is not linked into the binary.
  70 func (h Hash) New() hash.Hash {
  71         if h > 0 && h < maxHash {
  72                 f := hashes[h]
  73                 if f != nil {
  74                         return f()
  75                 }
  76         }
  77         panic("crypto: requested hash function #" + strconv.Itoa(int(h)) + " is unavailable")
  78 }
  79
  80 // Available reports whether the given hash function is linked into the binary.
  81 func (h Hash) Available() bool {
  82         return h < maxHash && hashes[h] != nil
  83 }
  84
  85 // RegisterHash registers a function that returns a new instance of the given
  86 // hash function. This is intended to be called from the init function in
  87 // packages that implement hash functions.
  88 func RegisterHash(h Hash, f func() hash.Hash) {
  89         if h >= maxHash {
  90                 panic("crypto: RegisterHash of unknown hash function")
  91         }
  92         hashes[h] = f
  93 }
  94
  95 // PublicKey represents a public key using an unspecified algorithm.
  96 type PublicKey interface{}
  97
  98 // PrivateKey represents a private key using an unspecified algorithm.
  99 type PrivateKey interface{}
 100
 101 // Signer is an interface for an opaque private key that can be used for
 102 // signing operations. For example, an RSA key kept in a hardware module.
 103 type Signer interface {
 104         // Public returns the public key corresponding to the opaque,
 105         // private key.
 106         Public() PublicKey
 107
 108         // Sign signs msg with the private key, possibly using entropy from
 109         // rand. For an RSA key, the resulting signature should be either a
 110         // PKCS#1 v1.5 or PSS signature (as indicated by opts). For an (EC)DSA
 111         // key, it should be a DER-serialised, ASN.1 signature structure.
 112         //
 113         // Hash implements the SignerOpts interface and, in most cases, one can
 114         // simply pass in the hash function used as opts. Sign may also attempt
 115         // to type assert opts to other types in order to obtain algorithm
 116         // specific values. See the documentation in each package for details.
 117         Sign(rand io.Reader, msg []byte, opts SignerOpts) (signature []byte, err error)
 118 }
 119
 120 // SignerOpts contains options for signing with a Signer.
 121 type SignerOpts interface {
 122         // HashFunc returns an identifier for the hash function used to produce
 123         // the message passed to Signer.Sign, or else zero to indicate that no
 124         // hashing was done.
 125         HashFunc() Hash
 126 }