...

Source file src/crypto/crypto.go

Documentation: 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  	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  

View as plain text