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	maxHash
40)
41
42var 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.
63func (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
70var 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.
74func (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.
85func (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.
92func 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.
100type PublicKey interface{}
101
102// PrivateKey represents a private key using an unspecified algorithm.
103type 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.
107type Signer interface {
108	// Public returns the public key corresponding to the opaque,
109	// private key.
110	Public() PublicKey
111
112	// Sign signs digest 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	//
122	// Note that when a signature of a hash of a larger message is needed,
123	// the caller is responsible for hashing the larger message and passing
124	// the hash (as digest) and the hash function (as opts) to Sign.
125	Sign(rand io.Reader, digest []byte, opts SignerOpts) (signature []byte, err error)
126}
127
128// SignerOpts contains options for signing with a Signer.
129type SignerOpts interface {
130	// HashFunc returns an identifier for the hash function used to produce
131	// the message passed to Signer.Sign, or else zero to indicate that no
132	// hashing was done.
133	HashFunc() Hash
134}
135
136// Decrypter is an interface for an opaque private key that can be used for
137// asymmetric decryption operations. An example would be an RSA key
138// kept in a hardware module.
139type Decrypter interface {
140	// Public returns the public key corresponding to the opaque,
141	// private key.
142	Public() PublicKey
143
144	// Decrypt decrypts msg. The opts argument should be appropriate for
145	// the primitive used. See the documentation in each implementation for
146	// details.
147	Decrypt(rand io.Reader, msg []byte, opts DecrypterOpts) (plaintext []byte, err error)
148}
149
150type DecrypterOpts interface{}
151