rsa

Documentation

Overview

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

Index

• Constants
• Variables
• func DecryptOAEP(hash hash.Hash, random io.Reader, priv *PrivateKey, ciphertext []byte, ...) (msg []byte, err error)
• func DecryptPKCS1v15(rand io.Reader, priv *PrivateKey, ciphertext []byte) (out []byte, err error)
• func DecryptPKCS1v15SessionKey(rand io.Reader, priv *PrivateKey, ciphertext []byte, key []byte) (err error)
• func EncryptOAEP(hash hash.Hash, random io.Reader, pub *PublicKey, msg []byte, label []byte) (out []byte, err error)
• func EncryptPKCS1v15(rand io.Reader, pub *PublicKey, msg []byte) (out []byte, err error)
• func SignPKCS1v15(rand io.Reader, priv *PrivateKey, hash crypto.Hash, hashed []byte) (s []byte, err error)
• func SignPSS(rand io.Reader, priv *PrivateKey, hash crypto.Hash, hashed []byte, ...) (s []byte, err error)
• func VerifyPKCS1v15(pub *PublicKey, hash crypto.Hash, hashed []byte, sig []byte) (err error)
• func VerifyPSS(pub *PublicKey, hash crypto.Hash, hashed []byte, sig []byte, opts *PSSOptions) error
• type CRTValue
• type OAEPOptions
• type PKCS1v15DecryptOptions
• type PSSOptions
  • func (pssOpts *PSSOptions) HashFunc() crypto.Hash
• type PrecomputedValues
• type PrivateKey
  • func GenerateKey(random io.Reader, bits int) (priv *PrivateKey, err error)
  • func GenerateMultiPrimeKey(random io.Reader, nprimes int, bits int) (priv *PrivateKey, err error)
  • func (priv *PrivateKey) Decrypt(rand io.Reader, ciphertext []byte, opts crypto.DecrypterOpts) (plaintext []byte, err error)
  • func (priv *PrivateKey) Precompute()
  • func (priv *PrivateKey) Public() crypto.PublicKey
  • func (priv *PrivateKey) Sign(rand io.Reader, msg []byte, opts crypto.SignerOpts) ([]byte, error)
  • func (priv *PrivateKey) Validate() error
• type PublicKey

Constants

const (
	// PSSSaltLengthAuto causes the salt in a PSS signature to be as large
	// as possible when signing, and to be auto-detected when verifying.
	PSSSaltLengthAuto = 0
	// PSSSaltLengthEqualsHash causes the salt length to equal the length
	// of the hash used in the signature.
	PSSSaltLengthEqualsHash = -1
)

Variables

var ErrDecryption = errors.New("crypto/rsa: decryption error")

ErrDecryption represents a failure to decrypt a message. It is deliberately vague to avoid adaptive attacks.

var ErrMessageTooLong = errors.New("crypto/rsa: message too long for RSA public key size")

ErrMessageTooLong is returned when attempting to encrypt a message which is too large for the size of the public key.

var ErrVerification = errors.New("crypto/rsa: verification error")

ErrVerification represents a failure to verify a signature. It is deliberately vague to avoid adaptive attacks.

Functions

func DecryptOAEP

func DecryptOAEP(hash hash.Hash, random io.Reader, priv *PrivateKey, ciphertext []byte, label []byte) (msg []byte, err error)

DecryptOAEP decrypts ciphertext using RSA-OAEP. If random != nil, DecryptOAEP uses RSA blinding to avoid timing side-channel attacks.

func DecryptPKCS1v15

func DecryptPKCS1v15(rand io.Reader, priv *PrivateKey, ciphertext []byte) (out []byte, err error)

DecryptPKCS1v15 decrypts a plaintext using RSA and the padding scheme from PKCS#1 v1.5. If rand != nil, it uses RSA blinding to avoid timing side-channel attacks.

func DecryptPKCS1v15SessionKey

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

DecryptPKCS1v15SessionKey decrypts a session key using RSA and the padding scheme from PKCS#1 v1.5. If rand != nil, it uses RSA blinding to avoid timing side-channel attacks. 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).

func EncryptOAEP

func EncryptOAEP(hash hash.Hash, random io.Reader, pub *PublicKey, msg []byte, label []byte) (out []byte, err error)

EncryptOAEP encrypts the given message with RSA-OAEP. The message must be no longer than the length of the public modulus less twice the hash length plus 2.

func EncryptPKCS1v15

func EncryptPKCS1v15(rand io.Reader, pub *PublicKey, msg []byte) (out []byte, err 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. WARNING: use of this function to encrypt plaintexts other than session keys is dangerous. Use RSA OAEP in new protocols.

func SignPKCS1v15

func SignPKCS1v15(rand io.Reader, priv *PrivateKey, hash crypto.Hash, hashed []byte) (s []byte, err 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.

func SignPSS

func SignPSS(rand io.Reader, priv *PrivateKey, hash crypto.Hash, hashed []byte, opts *PSSOptions) (s []byte, err error)

SignPSS calculates the signature of hashed using RSASSA-PSS [1]. Note that hashed 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.

func VerifyPKCS1v15

func VerifyPKCS1v15(pub *PublicKey, hash crypto.Hash, hashed []byte, sig []byte) (err 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.

func VerifyPSS

func VerifyPSS(pub *PublicKey, hash crypto.Hash, hashed []byte, sig []byte, opts *PSSOptions) error

VerifyPSS verifies a PSS 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. The opts argument may be nil, in which case sensible defaults are used.

Types

type CRTValue

type CRTValue struct {
	Exp   *big.Int // D mod (prime-1).
	Coeff *big.Int // R·Coeff ≡ 1 mod Prime.
	R     *big.Int // product of primes prior to this (inc p and q).
}

CRTValue contains the precomputed chinese remainder theorem values.

type OAEPOptions

type OAEPOptions struct {
	// Hash is the hash function that will be used when generating the mask.
	Hash crypto.Hash
	// Label is an arbitrary byte string that must be equal to the value
	// used when encrypting.
	Label []byte
}

OAEPOptions is an interface for passing options to OAEP decryption using the crypto.Decrypter interface.

type PKCS1v15DecryptOptions

type PKCS1v15DecryptOptions struct {
	// SessionKeyLen is the length of the session key that is being
	// decrypted. If not zero, then a padding error during decryption will
	// cause a random plaintext of this length to be returned rather than
	// an error. These alternatives happen in constant time.
	SessionKeyLen int
}

PKCS1v15DecrypterOpts is for passing options to PKCS#1 v1.5 decryption using the crypto.Decrypter interface.

type PSSOptions

type PSSOptions struct {
	// SaltLength controls the length of the salt used in the PSS
	// signature. It can either be a number of bytes, or one of the special
	// PSSSaltLength constants.
	SaltLength int

	// Hash, if not zero, overrides the hash function passed to SignPSS.
	// This is the only way to specify the hash function when using the
	// crypto.Signer interface.
	Hash crypto.Hash
}

PSSOptions contains options for creating and verifying PSS signatures.

func (*PSSOptions) HashFunc

func (pssOpts *PSSOptions) HashFunc() crypto.Hash

HashFunc returns pssOpts.Hash so that PSSOptions implements crypto.SignerOpts.

type PrecomputedValues

type PrecomputedValues struct {
	Dp, Dq *big.Int // D mod (P-1) (or mod Q-1)
	Qinv   *big.Int // Q^-1 mod P

	// CRTValues is used for the 3rd and subsequent primes. Due to a
	// historical accident, the CRT for the first two primes is handled
	// differently in PKCS#1 and interoperability is sufficiently
	// important that we mirror this.
	CRTValues []CRTValue
}

type PrivateKey

type PrivateKey struct {
	PublicKey            // public part.
	D         *big.Int   // private exponent
	Primes    []*big.Int // prime factors of N, has >= 2 elements.

	// Precomputed contains precomputed values that speed up private
	// operations, if available.
	Precomputed PrecomputedValues
}

A PrivateKey represents an RSA key

func GenerateKey

func GenerateKey(random io.Reader, bits int) (priv *PrivateKey, err 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) (priv *PrivateKey, err error)

GenerateMultiPrimeKey generates a multi-prime RSA keypair of the given bit size and the given random source, as suggested in [1]. 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.

Table 1 in [2] suggests maximum numbers of primes for a given size.

[1] US patent 4405829 (1972, expired) [2] http://www.cacr.math.uwaterloo.ca/techreports/2006/cacr2006-16.pdf

func (*PrivateKey) Decrypt

func (priv *PrivateKey) Decrypt(rand io.Reader, ciphertext []byte, opts crypto.DecrypterOpts) (plaintext []byte, err error)

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 (*PrivateKey) Precompute

func (priv *PrivateKey) Precompute()

Precompute performs some calculations that speed up private key operations in the future.

func (*PrivateKey) Public

func (priv *PrivateKey) Public() crypto.PublicKey

Public returns the public key corresponding to priv.

func (*PrivateKey) Sign

func (priv *PrivateKey) Sign(rand io.Reader, msg []byte, opts crypto.SignerOpts) ([]byte, error)

Sign signs msg 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. This method is intended 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.

func (*PrivateKey) Validate

func (priv *PrivateKey) Validate() error

Validate performs basic sanity checks on the key. It returns nil if the key is valid, or else an error describing a problem.

type PublicKey

type PublicKey struct {
	N *big.Int // modulus
	E int      // public exponent
}

A PublicKey represents the public part of an RSA key.