rsa

Documentation

Overview

Package rsa implements RSA encryption as specified in PKCS #1 and RFC 8017.

RSA is a single, fundamental operation that is used in this package to implement either public-key encryption or public-key signatures.

The original specification for encryption and signatures with RSA is PKCS #1 and the terms "RSA encryption" and "RSA signatures" by default refer to PKCS #1 version 1.5. However, that specification has flaws and new designs should use version 2, usually called by just OAEP and PSS, where possible.

Two sets of interfaces are included in this package. When a more abstract interface isn't necessary, there are functions for encrypting/decrypting with v1.5/OAEP and signing/verifying with v1.5/PSS. If one needs to abstract over the public key primitive, the PrivateKey type implements the Decrypter and Signer interfaces from the crypto package.

Operations in this package are implemented using constant-time algorithms, except for GenerateKey, [PrivateKey.Precompute], and [PrivateKey.Validate]. Every other operation only leaks the bit size of the involved values, which all depend on the selected key size.

Index

• func DecryptPKCS1v15(random io.Reader, priv *internalRsa.PrivateKey, ciphertext []byte) ([]byte, error)
• func DecryptPKCS1v15SessionKey(random io.Reader, priv *internalRsa.PrivateKey, ciphertext []byte, key []byte) error
• func EncryptPKCS1v15(random io.Reader, pub *internalRsa.PublicKey, msg []byte) ([]byte, error)
• func GenerateKey(random io.Reader, bits int) (*internalRsa.PrivateKey, error)
• func GenerateMultiPrimeKey(random io.Reader, nprimes int, bits int) (*internalRsa.PrivateKey, error)
• func Prime(rand io.Reader, bits int) (*big.Int, error)
• func SignPKCS1v15(random io.Reader, priv *internalRsa.PrivateKey, hash crypto.Hash, ...) ([]byte, error)
• func VerifyPKCS1v15(pub *internalRsa.PublicKey, hash crypto.Hash, hashed []byte, sig []byte) error

Functions

func DecryptPKCS1v15

func DecryptPKCS1v15(random io.Reader, priv *internalRsa.PrivateKey, ciphertext []byte) ([]byte, error)

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 as 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 DecryptPKCS1v15SessionKey

func DecryptPKCS1v15SessionKey(random io.Reader, priv *internalRsa.PrivateKey, ciphertext []byte, key []byte) error

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 as nil. It 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. This will remove any possibility that an attacker can learn any information about the plaintext. See “Chosen Ciphertext Attacks Against Protocols Based on the RSA Encryption Standard PKCS #1”, Daniel Bleichenbacher, Advances in Cryptology (Crypto '98).

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 defeats the point of this function. Using at least a 16-byte key will protect against this attack.

func EncryptPKCS1v15

func EncryptPKCS1v15(random io.Reader, pub *internalRsa.PublicKey, msg []byte) ([]byte, error)

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.

WARNING: use of this function to encrypt plaintexts other than session keys is dangerous. Use RSA OAEP in new protocols.

func GenerateKey

func GenerateKey(random io.Reader, bits int) (*internalRsa.PrivateKey, error)

GenerateKey generates an RSA keypair of the given bit size using the random source random (for example, crypto/rand.Reader).

func GenerateMultiPrimeKey

func GenerateMultiPrimeKey(random io.Reader, nprimes int, bits int) (*internalRsa.PrivateKey, error)

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.

Note: 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.

func Prime

func Prime(rand io.Reader, bits int) (*big.Int, error)

Prime returns a number of the given bit length that is prime with high probability. Prime will return error for any error returned by rand.Read or if bits < 2.

func SignPKCS1v15

func SignPKCS1v15(random io.Reader, priv *internalRsa.PrivateKey, hash crypto.Hash, hashed []byte) ([]byte, error)

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 as 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 VerifyPKCS1v15

func VerifyPKCS1v15(pub *internalRsa.PublicKey, hash crypto.Hash, hashed []byte, sig []byte) error

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.