 |
Software APIs
|
|
Software APIs
|
RSA signature operations for the OpenTitan cryptography library. More...
#include "datatypes.h"Go to the source code of this file.
Typedefs | |
| typedef enum otcrypto_rsa_padding | otcrypto_rsa_padding_t |
| Enum to define padding scheme for RSA signature data. More... | |
| typedef enum otcrypto_rsa_size | otcrypto_rsa_size_t |
| Enum to define possible lengths of RSA (public) keys. More... | |
Enumerations | |
| enum | otcrypto_rsa_padding { kOtcryptoRsaPaddingPkcs = 0x94e, kOtcryptoRsaPaddingPss = 0x6b1 } |
| Enum to define padding scheme for RSA signature data. More... | |
| enum | otcrypto_rsa_size { kOtcryptoRsaSize2048 = 0x5d1, kOtcryptoRsaSize3072 = 0xc35, kOtcryptoRsaSize4096 = 0x8da } |
| Enum to define possible lengths of RSA (public) keys. More... | |
| enum | { kOtcryptoRsa2048PublicKeyBytes = 260, kOtcryptoRsa3072PublicKeyBytes = 388, kOtcryptoRsa4096PublicKeyBytes = 516, kOtcryptoRsa2048PrivateKeyBytes = 256, kOtcryptoRsa3072PrivateKeyBytes = 384, kOtcryptoRsa4096PrivateKeyBytes = 512, kOtcryptoRsa2048PrivateKeyblobBytes = 512, kOtcryptoRsa3072PrivateKeyblobBytes = 768, kOtcryptoRsa4096PrivateKeyblobBytes = 1024 } |
RSA signature operations for the OpenTitan cryptography library.
Definition in file rsa.h.
| typedef enum otcrypto_rsa_padding otcrypto_rsa_padding_t |
Enum to define padding scheme for RSA signature data.
Values are hardened.
| typedef enum otcrypto_rsa_size otcrypto_rsa_size_t |
Enum to define possible lengths of RSA (public) keys.
Values are hardened.
| anonymous enum |
| enum otcrypto_rsa_padding |
| enum otcrypto_rsa_size |
| otcrypto_status_t otcrypto_rsa_decrypt | ( | const otcrypto_blinded_key_t * | private_key, |
| const otcrypto_hash_mode_t | hash_mode, | ||
| otcrypto_const_word32_buf_t | ciphertext, | ||
| otcrypto_const_byte_buf_t | label, | ||
| otcrypto_byte_buf_t | plaintext, | ||
| size_t * | plaintext_bytelen | ||
| ) |
Decrypts a message with RSA.
The only padding scheme available is OAEP, where the hash function is a member of the SHA-2 or SHA-3 family and the mask generation function is MGF1 with the same hash function.
The caller should allocate space for the plaintext buffer and set the allocated length in the len field. The length should be at least as long as the maximum message length imposed by OAEP; that is, k - 2*hLen - 2 bytes long, where k is the byte-length of the RSA modulus and hLen is the length of the hash function digest. If the plaintext buffer is not long enough, this function will return an error.
Decryption recovers the original length of the plaintext buffer and will return its value in plaintext_bytelen.
Note: RSA encryption is included for compatibility with legacy interfaces, and is typically not recommended for modern applications because it is slower and more fragile than other encryption methods. Consult an expert before using RSA encryption.
| private_key | Pointer to blinded private key struct. | |
| hash_mode | Hash function to use for OAEP encoding. | |
| ciphertext | Ciphertext to decrypt. | |
| label | Label for OAEP encoding. | |
| [out] | plaintext | Buffer for the decrypted message. |
| [out] | plaintext_bytelen | Recovered byte-length of plaintext. |
| otcrypto_status_t otcrypto_rsa_decrypt_async_finalize | ( | const otcrypto_hash_mode_t | hash_mode, |
| otcrypto_const_byte_buf_t | label, | ||
| otcrypto_byte_buf_t | plaintext, | ||
| size_t * | plaintext_bytelen | ||
| ) |
Finalizes the asynchronous decryption function.
See otcrypto_rsa_decrypt for details on the requirements for plaintext length and the way in which the actual length of the plaintext is returned.
| hash_mode | Hash function to use for OAEP encoding. | |
| label | Label for OAEP encoding. | |
| [out] | plaintext | Buffer for the decrypted message. |
| [out] | plaintext_bytelen | Recovered byte-length of plaintext. |
| otcrypto_status_t otcrypto_rsa_decrypt_async_start | ( | const otcrypto_blinded_key_t * | private_key, |
| otcrypto_const_word32_buf_t | ciphertext | ||
| ) |
Starts the asynchronous decryption function.
See otcrypto_rsa_decrypt for details on the length requirements for ciphertext.
| private_key | Pointer to blinded private key struct. |
| ciphertext | Ciphertext to decrypt. |
| otcrypto_status_t otcrypto_rsa_encrypt | ( | const otcrypto_unblinded_key_t * | public_key, |
| const otcrypto_hash_mode_t | hash_mode, | ||
| otcrypto_const_byte_buf_t | message, | ||
| otcrypto_const_byte_buf_t | label, | ||
| otcrypto_word32_buf_t | ciphertext | ||
| ) |
Encrypts a message with RSA.
The only padding scheme available is OAEP, where the hash function is a member of the SHA-2 or SHA-3 family and the mask generation function is MGF1 with the same hash function.
OAEP imposes strict limits on the length of the message (see IETF RFC 8017 for details). Specifically, the message is at most k - 2*hLen - 2 bytes long, where k is the byte-length of the RSA modulus and hLen is the length of the hash function digest. If the message is too long, this function will return an error.
The caller should allocate space for the ciphertext buffer and set the length of expected output in the len field of signature. The ciphertext is always the same length as the RSA modulus (so an RSA-2048 ciphertext is always 2048 bits long). If the length does not match the private key mode, this function returns an error.
Note: RSA encryption is included for compatibility with legacy interfaces, and is typically not recommended for modern applications because it is slower and more fragile than other encryption methods. Consult an expert before using RSA encryption.
| private_key | Pointer to public key struct. | |
| hash_mode | Hash function to use for OAEP encoding. | |
| message | Message to encrypt. | |
| label | Label for OAEP encoding. | |
| [out] | ciphertext | Buffer for the ciphertext. |
| otcrypto_status_t otcrypto_rsa_encrypt_async_finalize | ( | otcrypto_word32_buf_t | ciphertext | ) |
Finalizes the asynchronous encryption function.
See otcrypto_rsa_encrypt for details on the length requirements for ciphertext. Infers the RSA size from ciphertext's length, and will return an error if this does not match the RSA size for the current OTBN data.
| [out] | ciphertext | Buffer for the ciphertext. |
| otcrypto_status_t otcrypto_rsa_encrypt_async_start | ( | const otcrypto_unblinded_key_t * | public_key, |
| const otcrypto_hash_mode_t | hash_mode, | ||
| otcrypto_const_byte_buf_t | message, | ||
| otcrypto_const_byte_buf_t | label | ||
| ) |
Starts the asynchronous encryption function.
See otcrypto_rsa_encrypt for details on the length requirements for message.
| private_key | Pointer to public key struct. |
| hash_mode | Hash function to use for OAEP encoding. |
| message | Message to encrypt. |
| label | Label for OAEP encoding. |
| otcrypto_status_t otcrypto_rsa_keygen | ( | otcrypto_rsa_size_t | size, |
| otcrypto_unblinded_key_t * | public_key, | ||
| otcrypto_blinded_key_t * | private_key | ||
| ) |
Performs the RSA key generation.
Computes RSA private key (d) and RSA public key exponent (e) and modulus (n).
The caller should allocate space for the public key and set the key and key_length fields accordingly.
The caller should fully populate the blinded key configuration and allocate space for the keyblob, setting config.key_length and keyblob_length accordingly.
The value in the checksum field of key structs is not checked here and will be populated by the key generation function.
| size | RSA size parameter. | |
| [out] | public_key | Pointer to public key struct. |
| [out] | private_key | Pointer to blinded private key struct. |
| otcrypto_status_t otcrypto_rsa_keygen_async_finalize | ( | otcrypto_unblinded_key_t * | public_key, |
| otcrypto_blinded_key_t * | private_key | ||
| ) |
Finalizes the asynchronous RSA key generation function.
See otcrypto_rsa_keygen for details on the requirements for public_key and private_key.
| [out] | public_key | Pointer to public key struct. |
| [out] | private_key | Pointer to blinded private key struct. |
| otcrypto_status_t otcrypto_rsa_keygen_async_start | ( | otcrypto_rsa_size_t | size | ) |
Starts the asynchronous RSA key generation function.
Initializes OTBN and starts the OTBN routine to compute the RSA private key (d), RSA public key exponent (e) and modulus (n).
| size | RSA size parameter. |
| otcrypto_status_t otcrypto_rsa_keypair_from_cofactor | ( | otcrypto_rsa_size_t | size, |
| otcrypto_const_word32_buf_t | modulus, | ||
| uint32_t | e, | ||
| otcrypto_const_word32_buf_t | cofactor_share0, | ||
| otcrypto_const_word32_buf_t | cofactor_share1, | ||
| otcrypto_unblinded_key_t * | public_key, | ||
| otcrypto_blinded_key_t * | private_key | ||
| ) |
Constructs an RSA keypair from the public key and one prime cofactor.
The caller should allocate space for the private key and set the keyblob, keyblob_length, and key_length fields accordingly. Similarly, the caller should allocate space for the public key and set the key and key_length fields.
| size | RSA size parameter. | |
| modulus | RSA modulus (n). | |
| exponent | RSA public exponent (e). | |
| cofactor_share0 | First share of the prime cofactor (p or q). | |
| cofactor_share1 | Second share of the prime cofactor (p or q). | |
| [out] | public_key | Destination public key struct. |
| [out] | private_key | Destination private key struct. |
| otcrypto_status_t otcrypto_rsa_keypair_from_cofactor_async_finalize | ( | otcrypto_unblinded_key_t * | public_key, |
| otcrypto_blinded_key_t * | private_key | ||
| ) |
Finalizes constructing an RSA private key using a cofactor.
See otcrypto_rsa_keypair_from_cofactor for the details on the requirements for output buffers.
The public key returned from this function is recomputed; we recommend that the caller compare it to the originally passed public key value to ensure that everything went as expected. If the key is invalid in certain ways (such as the modulus not being divisible by the key), then the modulus will not match the original input.
| [out] | public_key | Destination public key struct. |
| [out] | private_key | Destination private key struct. |
| otcrypto_status_t otcrypto_rsa_keypair_from_cofactor_async_start | ( | otcrypto_rsa_size_t | size, |
| otcrypto_const_word32_buf_t | modulus, | ||
| uint32_t | e, | ||
| otcrypto_const_word32_buf_t | cofactor_share0, | ||
| otcrypto_const_word32_buf_t | cofactor_share1 | ||
| ) |
Starts constructing an RSA private key using a cofactor.
See otcrypto_rsa_keypair_from_cofactor for the details on the requirements for input buffers.
| size | RSA size parameter. |
| modulus | RSA modulus (n). |
| exponent | RSA public exponent (e). |
| cofactor_share0 | First share of the prime cofactor (p or q). |
| cofactor_share1 | Second share of the prime cofactor (p or q). |
| otcrypto_status_t otcrypto_rsa_private_key_from_exponents | ( | otcrypto_rsa_size_t | size, |
| otcrypto_const_word32_buf_t | modulus, | ||
| uint32_t | e, | ||
| otcrypto_const_word32_buf_t | d_share0, | ||
| otcrypto_const_word32_buf_t | d_share1, | ||
| otcrypto_blinded_key_t * | private_key | ||
| ) |
Constructs an RSA private key from the modulus and public/private exponents.
The caller should allocate space for the private key and set the keyblob, keyblob_length, and key_length fields accordingly.
| size | RSA size parameter. | |
| modulus | RSA modulus (n). | |
| exponent | RSA public exponent (e). | |
| d_share0 | First share of the RSA private exponent d. | |
| d_share1 | Second share of the RSA private exponent d. | |
| [out] | public_key | Destination public key struct. |
| otcrypto_status_t otcrypto_rsa_public_key_construct | ( | otcrypto_rsa_size_t | size, |
| otcrypto_const_word32_buf_t | modulus, | ||
| uint32_t | exponent, | ||
| otcrypto_unblinded_key_t * | public_key | ||
| ) |
Constructs an RSA public key from the modulus and public exponent.
The caller should allocate space for the public key and set the key and key_length fields accordingly.
| size | RSA size parameter. | |
| modulus | RSA modulus (n). | |
| exponent | RSA public exponent (e). | |
| [out] | public_key | Destination public key struct. |
| otcrypto_status_t otcrypto_rsa_sign | ( | const otcrypto_blinded_key_t * | private_key, |
| const otcrypto_hash_digest_t | message_digest, | ||
| otcrypto_rsa_padding_t | padding_mode, | ||
| otcrypto_word32_buf_t | signature | ||
| ) |
Computes the digital signature on the input message data.
The caller should allocate space for the signature buffer and set the length of expected output in the len field of signature. If the user-set length and the output length does not match, an error message will be returned.
| private_key | Pointer to blinded private key struct. | |
| message_digest | Message digest to be signed (pre-hashed). | |
| padding_mode | Padding scheme to be used for the data. | |
| [out] | signature | Pointer to the generated signature struct. |
| otcrypto_status_t otcrypto_rsa_sign_async_finalize | ( | otcrypto_word32_buf_t | signature | ) |
| otcrypto_status_t otcrypto_rsa_sign_async_start | ( | const otcrypto_blinded_key_t * | private_key, |
| const otcrypto_hash_digest_t | message_digest, | ||
| otcrypto_rsa_padding_t | padding_mode | ||
| ) |
Starts the asynchronous digital signature generation function.
Initializes OTBN and starts the OTBN routine to compute the digital signature on the input message.
| private_key | Pointer to blinded private key struct. |
| message_digest | Message digest to be signed (pre-hashed). |
| padding_mode | Padding scheme to be used for the data. |
| otcrypto_status_t otcrypto_rsa_verify | ( | const otcrypto_unblinded_key_t * | public_key, |
| const otcrypto_hash_digest_t | message_digest, | ||
| otcrypto_rsa_padding_t | padding_mode, | ||
| otcrypto_const_word32_buf_t | signature, | ||
| hardened_bool_t * | verification_result | ||
| ) |
Verifies the authenticity of the input signature.
An "OK" status code does not mean that the signature passed verification; the caller must check both the returned status and verification_result before trusting the signature.
| public_key | Pointer to public key struct. | |
| message_digest | Message digest to be verified (pre-hashed). | |
| padding_mode | Padding scheme to be used for the data. | |
| signature | Pointer to the input signature to be verified. | |
| [out] | verification_result | Result of signature verification. |
| otcrypto_status_t otcrypto_rsa_verify_async_finalize | ( | const otcrypto_hash_digest_t | message_digest, |
| otcrypto_rsa_padding_t | padding_mode, | ||
| hardened_bool_t * | verification_result | ||
| ) |
Finalizes the asynchronous signature verification function.
An "OK" status code does not mean that the signature passed verification; the caller must check both the returned status and verification_result before trusting the signature.
| message_digest | Message digest to be verified (pre-hashed). | |
| padding_mode | Padding scheme to be used for the data. | |
| [out] | verification_result | Result of signature verification. |
| otcrypto_status_t otcrypto_rsa_verify_async_start | ( | const otcrypto_unblinded_key_t * | public_key, |
| otcrypto_const_word32_buf_t | signature | ||
| ) |
Starts the asynchronous signature verification function.
Initializes OTBN and starts the OTBN routine to recover the message from the input signature.
| public_key | Pointer to public key struct. |
| signature | Pointer to the input signature to be verified. |