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.
6package crypto
7
8import (
9	"hash"
10	"io"
11	"strconv"
12)
13
14// Hash identifies a cryptographic hash function that is implemented in another
15// package.
16type Hash uint
17
18// HashFunc simply returns the value of h so that Hash implements SignerOpts.
19func (h Hash) HashFunc() Hash {
20	return h
21}
22
23const (
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
46var 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.
71func (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
78var 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.
82func (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.
93func (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.
100func 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.
108type PublicKey interface{}
109
110// PrivateKey represents a private key using an unspecified algorithm.
111type 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.
115type 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.
137type 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.
147type 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
158type DecrypterOpts interface{}
159