codekingpro/portable-devtools

1// Copyright 2011 The Go Authors. All rights reserved.2// Use of this source code is governed by a BSD-style3// license that can be found in the LICENSE file.4 5// Package crypto collects common cryptographic constants.6package crypto7 8import (9	"hash"10	"io"11	"strconv"12)13 14// Hash identifies a cryptographic hash function that is implemented in another15// package.16type Hash uint17 18// HashFunc simply returns the value of h so that [Hash] implements [SignerOpts].19func (h Hash) HashFunc() Hash {20	return h21}22 23func (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 68const (69	MD4         Hash = 1 + iota // import golang.org/x/crypto/md470	MD5                         // import crypto/md571	SHA1                        // import crypto/sha172	SHA224                      // import crypto/sha25673	SHA256                      // import crypto/sha25674	SHA384                      // import crypto/sha51275	SHA512                      // import crypto/sha51276	MD5SHA1                     // no implementation; MD5+SHA1 used for TLS RSA77	RIPEMD160                   // import golang.org/x/crypto/ripemd16078	SHA3_224                    // import crypto/sha379	SHA3_256                    // import crypto/sha380	SHA3_384                    // import crypto/sha381	SHA3_512                    // import crypto/sha382	SHA512_224                  // import crypto/sha51283	SHA512_256                  // import crypto/sha51284	BLAKE2s_256                 // import golang.org/x/crypto/blake2s85	BLAKE2b_256                 // import golang.org/x/crypto/blake2b86	BLAKE2b_384                 // import golang.org/x/crypto/blake2b87	BLAKE2b_512                 // import golang.org/x/crypto/blake2b88	maxHash89)90 91var 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 hash114// function. It doesn't require that the hash function in question be linked115// into the program.116func (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 123var hashes = make([]func() hash.Hash, maxHash)124 125// New returns a new hash.Hash calculating the given hash function. New panics126// if the hash function is not linked into the binary.127func (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.138func (h Hash) Available() bool {139	return h < maxHash && hashes[h] != nil140}141 142// RegisterHash registers a function that returns a new instance of the given143// hash function. This is intended to be called from the init function in144// packages that implement hash functions.145func RegisterHash(h Hash, f func() hash.Hash) {146	if h >= maxHash {147		panic("crypto: RegisterHash of unknown hash function")148	}149	hashes[h] = f150}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 interface156//157//	interface{158//	    Equal(x crypto.PublicKey) bool159//	}160//161// which can be used for increased type safety within applications.162type PublicKey any163 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 interface168//169//	interface{170//	    Public() crypto.PublicKey171//	    Equal(x crypto.PrivateKey) bool172//	}173//174// as well as purpose-specific interfaces such as [Signer] and [Decrypter], which175// can be used for increased type safety within applications.176type PrivateKey any177 178// Signer is an interface for an opaque private key that can be used for179// signing operations. For example, an RSA key kept in a hardware module.180type Signer interface {181	// Public returns the public key corresponding to the opaque,182	// private key.183	Public() PublicKey184 185	// Sign signs digest with the private key, possibly using entropy from186	// rand. For an RSA key, the resulting signature should be either a187	// PKCS #1 v1.5 or PSS signature (as indicated by opts). For an (EC)DSA188	// key, it should be a DER-serialised, ASN.1 signature structure.189	//190	// Hash implements the SignerOpts interface and, in most cases, one can191	// simply pass in the hash function used as opts. Sign may also attempt192	// to type assert opts to other types in order to obtain algorithm193	// 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 passing197	// 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// MessageSigner is an interface for an opaque private key that can be used for202// signing operations where the message is not pre-hashed by the caller.203// It is a superset of the Signer interface so that it can be passed to APIs204// which accept Signer, which may try to do an interface upgrade.205//206// MessageSigner.SignMessage and MessageSigner.Sign should produce the same207// result given the same opts. In particular, MessageSigner.SignMessage should208// only accept a zero opts.HashFunc if the Signer would also accept messages209// which are not pre-hashed.210//211// Implementations which do not provide the pre-hashed Sign API should implement212// Signer.Sign by always returning an error.213type MessageSigner interface {214	Signer215	SignMessage(rand io.Reader, msg []byte, opts SignerOpts) (signature []byte, err error)216}217 218// SignerOpts contains options for signing with a [Signer].219type SignerOpts interface {220	// HashFunc returns an identifier for the hash function used to produce221	// the message passed to Signer.Sign, or else zero to indicate that no222	// hashing was done.223	HashFunc() Hash224}225 226// Decrypter is an interface for an opaque private key that can be used for227// asymmetric decryption operations. An example would be an RSA key228// kept in a hardware module.229type Decrypter interface {230	// Public returns the public key corresponding to the opaque,231	// private key.232	Public() PublicKey233 234	// Decrypt decrypts msg. The opts argument should be appropriate for235	// the primitive used. See the documentation in each implementation for236	// details.237	Decrypt(rand io.Reader, msg []byte, opts DecrypterOpts) (plaintext []byte, err error)238}239 240type DecrypterOpts any241 242// SignMessage signs msg with signer. If signer implements [MessageSigner],243// [MessageSigner.SignMessage] is called directly. Otherwise, msg is hashed244// with opts.HashFunc() and signed with [Signer.Sign].245func SignMessage(signer Signer, rand io.Reader, msg []byte, opts SignerOpts) (signature []byte, err error) {246	if ms, ok := signer.(MessageSigner); ok {247		return ms.SignMessage(rand, msg, opts)248	}249	if opts.HashFunc() != 0 {250		h := opts.HashFunc().New()251		h.Write(msg)252		msg = h.Sum(nil)253	}254	return signer.Sign(rand, msg, opts)255}256 257// Decapsulator is an interface for an opaque private KEM key that can be used for258// decapsulation operations. For example, an ML-KEM key kept in a hardware module.259//260// It is implemented, for example, by [crypto/mlkem.DecapsulationKey768].261type Decapsulator interface {262	Encapsulator() Encapsulator263	Decapsulate(ciphertext []byte) (sharedKey []byte, err error)264}265 266// Encapsulator is an interface for a public KEM key that can be used for267// encapsulation operations.268//269// It is implemented, for example, by [crypto/mlkem.EncapsulationKey768].270type Encapsulator interface {271	Bytes() []byte272	Encapsulate() (sharedKey, ciphertext []byte)273}274