package core:crypto/rsa

Source

Private_Key is a RSA private key.

• decrypt_oaep
• private_key_clear
• private_key_d
• private_key_dp
• private_key_dq
• private_key_e
• private_key_equal
• private_key_generate
• private_key_iq
• private_key_n
• private_key_p
• private_key_q
• private_key_set
• private_key_set_bytes
• private_key_set_insecure_test
• private_key_size
• public_key_set_priv
• sign_pkcs1
• sign_pss
• unsafe_decrypt_tls_pms

Public_Key is a RSA public key.

• encrypt_oaep
• public_key_clear
• public_key_e
• public_key_equal
• public_key_n
• public_key_set
• public_key_set_bytes
• public_key_set_priv
• public_key_size
• verify_pkcs1
• verify_pss

Default size for a RSA key (in bits).

Maxmimum size for a RSA public exponent (in bits).

Note: This implementation supports arbitrary size exponents, however limit it to something sensible (some implementations are known to choke on exponents >= 2^32), with the most common choice being 65537.

Maximum size for a RSA factor (in bits). This is for RSA private-key operations. Default is to support factors up to a bit more than half the maximum modulus size.

This value MUST be a multiple of 32.

Maximum size for a RSA modulus (in bits).

This value MUST be a multiple of 64. This value MUST NOT exceed 47666 (some computations in RSA key generation rely on the factor size being no more than 23833 bits). RSA key sizes beyond 3072 bits don't make a lot of sense anyway.

Minimum size for a RSA modulus (in bits).

Note: 1024-bits is arguably insufficient as of this writing, with 2048-bits being a more sensible value, however 1024-bits is likely still in frequent enough use.

Note: CA signed TLS certificates have a strict requirement of a modulus size that is at least 2048-bits https://cabforum.org/working-groups/server/baseline-requirements/documents/.

PKCS1_HASH_OIDS maps common hash algorithms to the OIDs for use with PKCS#1 signatures.

decrypt_oaep returns the plaintext and true iff it successfully decrypts the ciphertext with OAEP parameterized by label, hash_algo, and mgf1_algo, and writes the plaintext into dst. If mgf1_algo is unspecified, hash_algo will be used.

Note: dst MUST be large enough to contain the plaintext.

encrypt_oaep returns true iff it successfully encrypts the plaintext with OAEP parameterized by label, hash_algo, and mgf1_algo, and writes the cipherttext into dst. If mgf1_algo is unspecified, hash_algo will be used.

This routine will fail if the system entropy source is unavailable.

oaep_max_plaintext_size returns the maximum supported plaintext size for a given key, with OAEP parameterized by hash_algo and mgf1_algo. If mgf1_algo is unspecified, hash_algo will be used.

private_key_clear clears priv_key to the uninitialized state.

private_key_d copies the private key's private exponent d to dst if dst is non-nil and of sufficient size, and returns the number of bytes copied/would be copied (ie: calling with dst = nil gets the required size).

Note: The data returned MUST be kept confidential.

private_key_dp copies the private key's first reduced exponent d % (p-1) to dst if dst is non-nil and of sufficient size, and returns the number of bytes copied/would be copied (ie: calling with dst = nil gets the required size).

Note: The data returned MUST be kept confidential.

private_key_dq copies the private key's second reduced exponent d % (q-1) to dst if dst is non-nil and of sufficient size, and returns the number of bytes copied/would be copied (ie: calling with dst = nil gets the required size).

Note: The data returned MUST be kept confidential.

private_key_e returns the private key's public exponent as a u32.

private_key_equal returns true iff priv_key is equal to other.

private_key_generate uses the system entropy source to generate a new Private_Key. The key size is specified in bits, and must be a multiple of 8.

private_key_iq copies the private key's CRT coefficient iq to dst if dst is non-nil and of sufficient size, and returns the number of bytes copied/would be copied (ie: calling withdst = nil gets the required size).

Note: The data returned MUST be kept confidential.

private_key_n copies the private key's public modulus to dst if dst is non-nil and of sufficient size, and returns the number of bytes copied/would be copied (ie: calling with dst = nil gets the required size).

private_key_p copies the private key's first prime factor p to dst if dst is non-nil and of sufficient size, and returns the number of bytes copied/would be copied (ie: calling with dst = nil gets the required size).

Note: The data returned MUST be kept confidential.

private_key_q copies the private key's second prime factor q to dst if dst is non-nil and of sufficient size, and returns the number of bytes copied/would be copied (ie: calling with dst = nil gets the required size).

Note: The data returned MUST be kept confidential.

private_key_set sets priv_key to src.

private_key_set_bytes sets a private key from byte-encoded components, and returns true iff the operation was successful.

Note: All values are mandatory, and match the values included in the PKCS private key format.

WARNING: This routine validates that it is possible to sign/verify with the deserialized values, however d is not checked at all, nor is the primality of p and q.

private_key_set_insecure_test sets the private key to the pregenerated INSECURE test key "testRSA2048" from RFC 9500 2.1.

WARNING: This key MUST only be used for testing purposes.

private_key_size returns the size of the private key's public modulus in bytes. All ciphertexts and signatures will also be this size.

public_key_clear clears pub_key to the uninitialized state.

public_key_e returns the public key's exponent e as a u32.

public_key_equal returns true iff pub_key is equal to other.

public_key_n copies the public key's modulus n to dst if dst is non-nil and of sufficient size, and returns the number of bytes copied/would be copied (ie: calling with dst = nil gets the required size).

public_key_set sets pub_key to src.

public_key_set_bytes sets a public key from byte-encoded components, and returns true iff the operation was successful.

public_key_set_priv sets pub_key to the public component of priv_key.

public_key_size returns the size of the public key's modulus in bytes. All ciphertexts and signatures will also be this size.

sign_pkcs1 returns true iff it successfully writes the PKCS#1 signature by priv_key over msg, hashed using hash_algo. If pre_hashed is set to true, it is assumed that msg is already hashed.

sign_pss returns true iff it successfully writes the PKCS#1 signature by priv_key over msg, hashed using hash_algo, and MGF1 parameterized by mgf1_algo and salt_len. If mgf1_algo is unspecified, hash_algo will be used. If pre_hashed is set to true, it is assumed that msg is already hashed. A reasonable choice for salt_len is the digest size of hash_algo, and FIPS 140-3 mandates that as the maximum permissible size.

This routine will fail if the system entropy source is unavailable.

size returns the size of the key's public modulus in bytes. All ciphertexts and signatures will also be this size.

unsafe_decrypt_tls_pms decrypts a TLS RSA-Encrypted Premaster Secret Message, unconditionally moves the decrypted plaintext to data[:48], and returns 1 iff the operation was successful.

WARNING: This routine MUST only be used when implementing server-side support for TLS 1.2's Client Key Exchange message, and extreme care MUST be taken when handling failures. This key exchange scheme was removed in TLS 1.3, and not implementing support in the first place is strongly RECOMMENDED even for TLS 1.2 servers.

verify_pkcs1 returns true iff sig is a valid PKCS#1 signature by pub_key over msg, hased using hash_algo. If pre_hashed is set to true, it is assumed that msg is already hashed.

verify_pss returns true iff sig is a valid PSS signature by pub_key over msg, hashed using hash_algo, and MGF1 parameterized by mgf1_algo and salt_len. If mgf1_algo is unspecified, hash_algo will be used. If pre_hashed is set to true, it is assumed that msg is already hashed.