Source file 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  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
   224  

View as plain text