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