Functions
Decrypt
method
#
Decrypt decrypts ciphertext with priv. If opts is nil or of type
*[PKCS1v15DecryptOptions] then PKCS #1 v1.5 decryption is performed. Otherwise
opts must have type *[OAEPOptions] and OAEP decryption is done.
func (priv *PrivateKey) Decrypt(rand io.Reader, ciphertext []byte, opts crypto.DecrypterOpts) (plaintext []byte, err error)
DecryptOAEP
function
#
DecryptOAEP decrypts ciphertext using RSA-OAEP.
OAEP is parameterised by a hash function that is used as a random oracle.
Encryption and decryption of a given message must use the same hash function
and sha256.New() is a reasonable choice.
The random parameter is legacy and ignored, and it can be nil.
The label parameter must match the value given when encrypting. See
[EncryptOAEP] for details.
func DecryptOAEP(hash hash.Hash, random io.Reader, priv *PrivateKey, ciphertext []byte, label []byte) ([]byte, error)
DecryptPKCS1v15
function
#
DecryptPKCS1v15 decrypts a plaintext using RSA and the padding scheme from PKCS #1 v1.5.
The random parameter is legacy and ignored, and it can be nil.
Note that whether this function returns an error or not discloses secret
information. If an attacker can cause this function to run repeatedly and
learn whether each instance returned an error then they can decrypt and
forge signatures as if they had the private key. See
DecryptPKCS1v15SessionKey for a way of solving this problem.
func DecryptPKCS1v15(random io.Reader, priv *PrivateKey, ciphertext []byte) ([]byte, error)
DecryptPKCS1v15SessionKey
function
#
DecryptPKCS1v15SessionKey decrypts a session key using RSA and the padding
scheme from PKCS #1 v1.5. The random parameter is legacy and ignored, and it
can be nil.
DecryptPKCS1v15SessionKey returns an error if the ciphertext is the wrong
length or if the ciphertext is greater than the public modulus. Otherwise, no
error is returned. If the padding is valid, the resulting plaintext message
is copied into key. Otherwise, key is unchanged. These alternatives occur in
constant time. It is intended that the user of this function generate a
random session key beforehand and continue the protocol with the resulting
value.
Note that if the session key is too small then it may be possible for an
attacker to brute-force it. If they can do that then they can learn whether a
random value was used (because it'll be different for the same ciphertext)
and thus whether the padding was correct. This also defeats the point of this
function. Using at least a 16-byte key will protect against this attack.
This method implements protections against Bleichenbacher chosen ciphertext
attacks [0] described in RFC 3218 Section 2.3.2 [1]. While these protections
make a Bleichenbacher attack significantly more difficult, the protections
are only effective if the rest of the protocol which uses
DecryptPKCS1v15SessionKey is designed with these considerations in mind. In
particular, if any subsequent operations which use the decrypted session key
leak any information about the key (e.g. whether it is a static or random
key) then the mitigations are defeated. This method must be used extremely
carefully, and typically should only be used when absolutely necessary for
compatibility with an existing protocol (such as TLS) that is designed with
these properties in mind.
- [0] “Chosen Ciphertext Attacks Against Protocols Based on the RSA Encryption
Standard PKCS #1”, Daniel Bleichenbacher, Advances in Cryptology (Crypto '98)
- [1] RFC 3218, Preventing the Million Message Attack on CMS,
https://www.rfc-editor.org/rfc/rfc3218.html
func DecryptPKCS1v15SessionKey(random io.Reader, priv *PrivateKey, ciphertext []byte, key []byte) error
EncryptOAEP
function
#
EncryptOAEP encrypts the given message with RSA-OAEP.
OAEP is parameterised by a hash function that is used as a random oracle.
Encryption and decryption of a given message must use the same hash function
and sha256.New() is a reasonable choice.
The random parameter is used as a source of entropy to ensure that
encrypting the same message twice doesn't result in the same ciphertext.
Most applications should use [crypto/rand.Reader] as random.
The label parameter may contain arbitrary data that will not be encrypted,
but which gives important context to the message. For example, if a given
public key is used to encrypt two types of messages then distinct label
values could be used to ensure that a ciphertext for one purpose cannot be
used for another by an attacker. If not required it can be empty.
The message must be no longer than the length of the public modulus minus
twice the hash length, minus a further 2.
func EncryptOAEP(hash hash.Hash, random io.Reader, pub *PublicKey, msg []byte, label []byte) ([]byte, error)
EncryptPKCS1v15
function
#
EncryptPKCS1v15 encrypts the given message with RSA and the padding
scheme from PKCS #1 v1.5. The message must be no longer than the
length of the public modulus minus 11 bytes.
The random parameter is used as a source of entropy to ensure that
encrypting the same message twice doesn't result in the same
ciphertext. Most applications should use [crypto/rand.Reader]
as random. Note that the returned ciphertext does not depend
deterministically on the bytes read from random, and may change
between calls and/or between versions.
WARNING: use of this function to encrypt plaintexts other than
session keys is dangerous. Use RSA OAEP in new protocols.
func EncryptPKCS1v15(random io.Reader, pub *PublicKey, msg []byte) ([]byte, error)
Equal
method
#
Equal reports whether pub and x have the same value.
func (pub *PublicKey) Equal(x crypto.PublicKey) bool
Equal
method
#
Equal reports whether priv and x have equivalent values. It ignores
Precomputed values.
func (priv *PrivateKey) Equal(x crypto.PrivateKey) bool
GenerateKey
function
#
GenerateKey generates a random RSA private key of the given bit size.
If bits is less than 1024, [GenerateKey] returns an error. See the "[Minimum
key size]" section for further details.
Most applications should use [crypto/rand.Reader] as rand. Note that the
returned key does not depend deterministically on the bytes read from rand,
and may change between calls and/or between versions.
[Minimum key size]: #hdr-Minimum_key_size
func GenerateKey(random io.Reader, bits int) (*PrivateKey, error)
GenerateMultiPrimeKey
function
#
GenerateMultiPrimeKey generates a multi-prime RSA keypair of the given bit
size and the given random source.
Table 1 in "[On the Security of Multi-prime RSA]" suggests maximum numbers of
primes for a given bit size.
Although the public keys are compatible (actually, indistinguishable) from
the 2-prime case, the private keys are not. Thus it may not be possible to
export multi-prime private keys in certain formats or to subsequently import
them into other code.
This package does not implement CRT optimizations for multi-prime RSA, so the
keys with more than two primes will have worse performance.
Deprecated: The use of this function with a number of primes different from
two is not recommended for the above security, compatibility, and performance
reasons. Use [GenerateKey] instead.
[On the Security of Multi-prime RSA]: http://www.cacr.math.uwaterloo.ca/techreports/2006/cacr2006-16.pdf
func GenerateMultiPrimeKey(random io.Reader, nprimes int, bits int) (*PrivateKey, error)
HashFunc
method
#
HashFunc returns opts.Hash so that [PSSOptions] implements [crypto.SignerOpts].
func (opts *PSSOptions) HashFunc() crypto.Hash
Precompute
method
#
Precompute performs some calculations that speed up private key operations
in the future. It is safe to run on non-validated private keys.
func (priv *PrivateKey) Precompute()
Public
method
#
Public returns the public key corresponding to priv.
func (priv *PrivateKey) Public() crypto.PublicKey
Sign
method
#
Sign signs digest with priv, reading randomness from rand. If opts is a
*[PSSOptions] then the PSS algorithm will be used, otherwise PKCS #1 v1.5 will
be used. digest must be the result of hashing the input message using
opts.HashFunc().
This method implements [crypto.Signer], which is an interface to support keys
where the private part is kept in, for example, a hardware module. Common
uses should use the Sign* functions in this package directly.
func (priv *PrivateKey) Sign(rand io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error)
SignPKCS1v15
function
#
SignPKCS1v15 calculates the signature of hashed using
RSASSA-PKCS1-V1_5-SIGN from RSA PKCS #1 v1.5. Note that hashed must
be the result of hashing the input message using the given hash
function. If hash is zero, hashed is signed directly. This isn't
advisable except for interoperability.
The random parameter is legacy and ignored, and it can be nil.
This function is deterministic. Thus, if the set of possible
messages is small, an attacker may be able to build a map from
messages to signatures and identify the signed messages. As ever,
signatures provide authenticity, not confidentiality.
func SignPKCS1v15(random io.Reader, priv *PrivateKey, hash crypto.Hash, hashed []byte) ([]byte, error)
SignPSS
function
#
SignPSS calculates the signature of digest using PSS.
digest must be the result of hashing the input message using the given hash
function. The opts argument may be nil, in which case sensible defaults are
used. If opts.Hash is set, it overrides hash.
The signature is randomized depending on the message, key, and salt size,
using bytes from rand. Most applications should use [crypto/rand.Reader] as
rand.
func SignPSS(rand io.Reader, priv *PrivateKey, hash crypto.Hash, digest []byte, opts *PSSOptions) ([]byte, error)
Size
method
#
Size returns the modulus size in bytes. Raw signatures and ciphertexts
for or by this public key will have the same size.
func (pub *PublicKey) Size() int
Validate
method
#
Validate performs basic sanity checks on the key.
It returns nil if the key is valid, or else an error describing a problem.
It runs faster on valid keys if run after [Precompute].
func (priv *PrivateKey) Validate() error
VerifyPKCS1v15
function
#
VerifyPKCS1v15 verifies an RSA PKCS #1 v1.5 signature.
hashed is the result of hashing the input message using the given hash
function and sig is the signature. A valid signature is indicated by
returning a nil error. If hash is zero then hashed is used directly. This
isn't advisable except for interoperability.
The inputs are not considered confidential, and may leak through timing side
channels, or if an attacker has control of part of the inputs.
func VerifyPKCS1v15(pub *PublicKey, hash crypto.Hash, hashed []byte, sig []byte) error
VerifyPSS
function
#
VerifyPSS verifies a PSS signature.
A valid signature is indicated by returning a nil error. digest must be the
result of hashing the input message using the given hash function. The opts
argument may be nil, in which case sensible defaults are used. opts.Hash is
ignored.
The inputs are not considered confidential, and may leak through timing side
channels, or if an attacker has control of part of the inputs.
func VerifyPSS(pub *PublicKey, hash crypto.Hash, digest []byte, sig []byte, opts *PSSOptions) error
bigIntEqual
function
#
bigIntEqual reports whether a and b are equal leaking only their bit length
through timing side-channels.
func bigIntEqual(a *big.Int, b *big.Int) bool
boringPrivateKey
function
#
func boringPrivateKey(*PrivateKey) (*boring.PrivateKeyRSA, error)
boringPrivateKey
function
#
func boringPrivateKey(priv *PrivateKey) (*boring.PrivateKeyRSA, error)
boringPublicKey
function
#
func boringPublicKey(pub *PublicKey) (*boring.PublicKeyRSA, error)
boringPublicKey
function
#
func boringPublicKey(*PublicKey) (*boring.PublicKeyRSA, error)
checkFIPS140OnlyPrivateKey
function
#
func checkFIPS140OnlyPrivateKey(priv *PrivateKey) error
checkFIPS140OnlyPublicKey
function
#
func checkFIPS140OnlyPublicKey(pub *PublicKey) error
checkKeySize
function
#
func checkKeySize(size int) error
checkPublicKeySize
function
#
func checkPublicKeySize(k *PublicKey) error
copyPrivateKey
function
#
func copyPrivateKey(k *PrivateKey) PrivateKey
copyPublicKey
function
#
func copyPublicKey(k *PublicKey) PublicKey
decryptOAEP
function
#
func decryptOAEP(hash hash.Hash, mgfHash hash.Hash, priv *PrivateKey, ciphertext []byte, label []byte) ([]byte, error)
decryptPKCS1v15
function
#
decryptPKCS1v15 decrypts ciphertext using priv. It returns one or zero in
valid that indicates whether the plaintext was correctly structured.
In either case, the plaintext is returned in em so that it may be read
independently of whether it was valid in order to maintain constant memory
access patterns. If the plaintext was valid then index contains the index of
the original message in em, to allow constant time padding removal.
func decryptPKCS1v15(priv *PrivateKey, ciphertext []byte) (valid int, em []byte, index int, err error)
fipsError
function
#
func fipsError(err error) error
fipsError2
function
#
func fipsError2(x T, err error) (T, error)
fipsPrivateKey
function
#
func fipsPrivateKey(priv *PrivateKey) (*rsa.PrivateKey, error)
fipsPublicKey
function
#
func fipsPublicKey(pub *PublicKey) (*rsa.PublicKey, error)
init
function
#
func init()
nonZeroRandomBytes
function
#
nonZeroRandomBytes fills the given slice with non-zero random octets.
func nonZeroRandomBytes(s []byte, random io.Reader) (err error)
precompute
method
#
func (priv *PrivateKey) precompute() (PrecomputedValues, error)
precomputeLegacy
method
#
func (priv *PrivateKey) precomputeLegacy() (PrecomputedValues, error)
privateKeyEqual
function
#
func privateKeyEqual(k1 *PrivateKey, k2 *PrivateKey) bool
publicKeyEqual
function
#
func publicKeyEqual(k1 *PublicKey, k2 *PublicKey) bool
saltLength
method
#
func (opts *PSSOptions) saltLength() int