Package: crypto/rsa

package rsa Import Path crypto/rsa (on golang.org and go.dev) Dependency Relation imports 10 packages, and imported by 3 packages Involved Source Files pkcs1v15.go pss.go d-> rsa.go Exported Type Names

type CRTValue (struct) CRTValue contains the precomputed Chinese remainder theorem values. Exported Fields (3) Coeff *big.Int Exp *big.Int R *big.Int

type OAEPOptions (struct) OAEPOptions is an interface for passing options to OAEP decryption using the crypto.Decrypter interface. Exported Fields (2) Hash crypto.Hash Label []byte

type PKCS1v15DecryptOptions (struct) PKCS1v15DecrypterOpts is for passing options to PKCS #1 v1.5 decryption using the crypto.Decrypter interface. One Exported Field SessionKeyLen int

type PrecomputedValues (struct) Exported Fields (4) CRTValues []CRTValue Dp *big.Int Dq *big.Int Qinv *big.Int

type PrivateKey (struct) A PrivateKey represents an RSA key Exported Fields (6) D *big.Int Precomputed PrecomputedValues Primes []*big.Int PublicKey PublicKey PublicKey.E int PublicKey.N *big.Int Exported Methods (7) (*T) Decrypt(rand io.Reader, ciphertext []byte, opts crypto.DecrypterOpts) (plaintext []byte, err error) (*T) Equal(x crypto.PrivateKey) bool (*T) Precompute() (*T) Public() crypto.PublicKey (*T) Sign(rand io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error) (*T) Size() int (*T) Validate() error Implements (2+) *T : crypto.Decrypter *T : crypto.Signer As Outputs Of (3+) func GenerateKey(random io.Reader, bits int) (*PrivateKey, error) func GenerateMultiPrimeKey(random io.Reader, nprimes int, bits int) (*PrivateKey, error) func crypto/x509.ParsePKCS1PrivateKey(der []byte) (*PrivateKey, error) As Inputs Of (6+) func DecryptOAEP(hash hash.Hash, random io.Reader, priv *PrivateKey, ciphertext []byte, label []byte) ([]byte, error) func DecryptPKCS1v15(rand io.Reader, priv *PrivateKey, ciphertext []byte) ([]byte, error) func DecryptPKCS1v15SessionKey(rand io.Reader, priv *PrivateKey, ciphertext []byte, key []byte) error func SignPKCS1v15(rand io.Reader, priv *PrivateKey, hash crypto.Hash, hashed []byte) ([]byte, error) func SignPSS(rand io.Reader, priv *PrivateKey, hash crypto.Hash, digest []byte, opts *PSSOptions) ([]byte, error) func crypto/x509.MarshalPKCS1PrivateKey(key *PrivateKey) []byte

type PSSOptions (struct) PSSOptions contains options for creating and verifying PSS signatures. Exported Fields (2) Hash crypto.Hash SaltLength int One Exported Method (*T) HashFunc() crypto.Hash Implements (1+) *T : crypto.SignerOpts As Inputs Of (2+) func SignPSS(rand io.Reader, priv *PrivateKey, hash crypto.Hash, digest []byte, opts *PSSOptions) ([]byte, error) func VerifyPSS(pub *PublicKey, hash crypto.Hash, digest []byte, sig []byte, opts *PSSOptions) error

type PublicKey (struct) A PublicKey represents the public part of an RSA key. Exported Fields (2) E int N *big.Int Exported Methods (2) (*T) Equal(x crypto.PublicKey) bool (*T) Size() int As Outputs Of (1+) func crypto/x509.ParsePKCS1PublicKey(der []byte) (*PublicKey, error) As Inputs Of (6+) func EncryptOAEP(hash hash.Hash, random io.Reader, pub *PublicKey, msg []byte, label []byte) ([]byte, error) func EncryptPKCS1v15(rand io.Reader, pub *PublicKey, msg []byte) ([]byte, error) func VerifyPKCS1v15(pub *PublicKey, hash crypto.Hash, hashed []byte, sig []byte) error func VerifyPSS(pub *PublicKey, hash crypto.Hash, digest []byte, sig []byte, opts *PSSOptions) error func crypto/x509.MarshalPKCS1PublicKey(key *PublicKey) []byte func github.com/go-sql-driver/mysql.RegisterServerPubKey(name string, pubKey *PublicKey)

Exported Values

func DecryptOAEP(hash hash.Hash, random io.Reader, priv *PrivateKey, ciphertext []byte, label []byte) ([]byte, error) 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, if not nil, is used to blind the private-key operation and avoid timing side-channel attacks. Blinding is purely internal to this function – the random data need not match that used when encrypting. The label parameter must match the value given when encrypting. See EncryptOAEP for details.

func DecryptPKCS1v15(rand io.Reader, priv *PrivateKey, ciphertext []byte) ([]byte, 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. 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(rand io.Reader, priv *PrivateKey, ciphertext []byte, key []byte) 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). 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 EncryptOAEP(hash hash.Hash, random io.Reader, pub *PublicKey, msg []byte, label []byte) ([]byte, error) 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. 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 decrypt 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 EncryptPKCS1v15(rand io.Reader, pub *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 rand 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.

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

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

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

func GenerateKey(random io.Reader, bits int) (*PrivateKey, error) GenerateKey generates an RSA keypair of the given bit size using the random source random (for example, crypto/rand.Reader).

func GenerateMultiPrimeKey(random io.Reader, nprimes int, bits int) (*PrivateKey, 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

const PSSSaltLengthAuto = 0 PSSSaltLengthAuto causes the salt in a PSS signature to be as large as possible when signing, and to be auto-detected when verifying.

const PSSSaltLengthEqualsHash = -1 PSSSaltLengthEqualsHash causes the salt length to equal the length of the hash used in the signature.

func SignPKCS1v15(rand io.Reader, priv *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. If rand is not nil then RSA blinding will be used to avoid timing side-channel attacks. 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 SignPSS(rand io.Reader, priv *PrivateKey, hash crypto.Hash, digest []byte, opts *PSSOptions) ([]byte, error) 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.

func VerifyPKCS1v15(pub *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.

func VerifyPSS(pub *PublicKey, hash crypto.Hash, digest []byte, sig []byte, opts *PSSOptions) error 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.