Software APIs
Typedefs | Enumerations | Functions
ecc.h File Reference

(460b062a5f)

Elliptic curve operations for OpenTitan cryptography library. More...

#include "datatypes.h"

Go to the source code of this file.

Typedefs

typedef enum otcrypto_eddsa_sign_mode otcrypto_eddsa_sign_mode_t
 Enum to define EdDSA mode for signature. More...
 

Enumerations

enum  otcrypto_eddsa_sign_mode {
  kOtcryptoEddsaSignModeEddsa = 0xae1 ,
  kOtcryptoEddsaSignModeHashEddsa = 0x9a6
}
 Enum to define EdDSA mode for signature. More...
 

Functions

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p256_keygen (otcrypto_blinded_key_t *private_key, otcrypto_unblinded_key_t *public_key)
 Generates a key pair for ECDSA with curve P-256. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p384_keygen (otcrypto_blinded_key_t *private_key, otcrypto_unblinded_key_t *public_key)
 Generates a key pair for ECDSA with curve P-384. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p256_sign (const otcrypto_blinded_key_t *private_key, const otcrypto_hash_digest_t message_digest, otcrypto_word32_buf_t signature)
 Generates an ECDSA signature with curve P-256. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p384_sign (const otcrypto_blinded_key_t *private_key, const otcrypto_hash_digest_t message_digest, otcrypto_word32_buf_t signature)
 Generates an ECDSA signature with curve P-384. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p256_verify (const otcrypto_unblinded_key_t *public_key, const otcrypto_hash_digest_t message_digest, otcrypto_const_word32_buf_t signature, hardened_bool_t *verification_result)
 Verifies an ECDSA/P-256 signature. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p384_verify (const otcrypto_unblinded_key_t *public_key, const otcrypto_hash_digest_t message_digest, otcrypto_const_word32_buf_t signature, hardened_bool_t *verification_result)
 Verifies an ECDSA/P-384 signature. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p256_keygen (otcrypto_blinded_key_t *private_key, otcrypto_unblinded_key_t *public_key)
 Generates a key pair for ECDH with curve P-256. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p384_keygen (otcrypto_blinded_key_t *private_key, otcrypto_unblinded_key_t *public_key)
 Generates a key pair for ECDH with curve P-384. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p256 (const otcrypto_blinded_key_t *private_key, const otcrypto_unblinded_key_t *public_key, otcrypto_blinded_key_t *shared_secret)
 Elliptic Curve Diffie Hellman shared secret generation with curve P-256. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p384 (const otcrypto_blinded_key_t *private_key, const otcrypto_unblinded_key_t *public_key, otcrypto_blinded_key_t *shared_secret)
 Elliptic Curve Diffie Hellman shared secret generation with curve P-384. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ed25519_keygen (otcrypto_blinded_key_t *private_key, otcrypto_unblinded_key_t *public_key)
 Generates a new Ed25519 key pair. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ed25519_sign (const otcrypto_blinded_key_t *private_key, otcrypto_const_byte_buf_t input_message, otcrypto_eddsa_sign_mode_t sign_mode, otcrypto_word32_buf_t signature)
 Generates an Ed25519 digital signature. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ed25519_verify (const otcrypto_unblinded_key_t *public_key, otcrypto_const_byte_buf_t input_message, otcrypto_eddsa_sign_mode_t sign_mode, otcrypto_const_word32_buf_t signature, hardened_bool_t *verification_result)
 Verifies an Ed25519 signature. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_x25519_keygen (otcrypto_blinded_key_t *private_key, otcrypto_unblinded_key_t *public_key)
 Generates a new key pair for X25519 key exchange. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_x25519 (const otcrypto_blinded_key_t *private_key, const otcrypto_unblinded_key_t *public_key, otcrypto_blinded_key_t *shared_secret)
 Performs the X25519 Diffie Hellman shared secret generation. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p256_keygen_async_start (const otcrypto_blinded_key_t *private_key)
 Starts asynchronous key generation for ECDSA/P-256. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p256_keygen_async_finalize (otcrypto_blinded_key_t *private_key, otcrypto_unblinded_key_t *public_key)
 Finalizes asynchronous key generation for ECDSA/P-256. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p384_keygen_async_start (const otcrypto_blinded_key_t *private_key)
 Starts asynchronous key generation for ECDSA/P-384. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p384_keygen_async_finalize (otcrypto_blinded_key_t *private_key, otcrypto_unblinded_key_t *public_key)
 Finalizes asynchronous key generation for ECDSA/P-384. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p256_sign_async_start (const otcrypto_blinded_key_t *private_key, const otcrypto_hash_digest_t message_digest)
 Starts asynchronous signature generation for ECDSA/P-256. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p256_sign_async_finalize (otcrypto_word32_buf_t signature)
 Finalizes asynchronous signature generation for ECDSA/P-256. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p384_sign_async_start (const otcrypto_blinded_key_t *private_key, const otcrypto_hash_digest_t message_digest)
 Starts asynchronous signature generation for ECDSA/P-384. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p384_sign_async_finalize (otcrypto_word32_buf_t signature)
 Finalizes asynchronous signature generation for ECDSA/P-384. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p256_verify_async_start (const otcrypto_unblinded_key_t *public_key, const otcrypto_hash_digest_t message_digest, otcrypto_const_word32_buf_t signature)
 Starts asynchronous signature verification for ECDSA/P-256. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p256_verify_async_finalize (otcrypto_const_word32_buf_t signature, hardened_bool_t *verification_result)
 Finalizes asynchronous signature verification for ECDSA/P-256. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p384_verify_async_start (const otcrypto_unblinded_key_t *public_key, const otcrypto_hash_digest_t message_digest, otcrypto_const_word32_buf_t signature)
 Starts asynchronous signature verification for ECDSA/P-384. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p384_verify_async_finalize (otcrypto_const_word32_buf_t signature, hardened_bool_t *verification_result)
 Finalizes asynchronous signature verification for ECDSA/P-384. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p256_keygen_async_start (const otcrypto_blinded_key_t *private_key)
 Starts asynchronous key generation for ECDH/P-256. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p256_keygen_async_finalize (otcrypto_blinded_key_t *private_key, otcrypto_unblinded_key_t *public_key)
 Finalizes asynchronous key generation for ECDH/P-256. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p384_keygen_async_start (const otcrypto_blinded_key_t *private_key)
 Starts asynchronous key generation for ECDH/P-384. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p384_keygen_async_finalize (otcrypto_blinded_key_t *private_key, otcrypto_unblinded_key_t *public_key)
 Finalizes asynchronous key generation for ECDH/P-384. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p256_async_start (const otcrypto_blinded_key_t *private_key, const otcrypto_unblinded_key_t *public_key)
 Starts asynchronous shared secret generation for ECDH/P-256. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p256_async_finalize (otcrypto_blinded_key_t *shared_secret)
 Finalizes asynchronous shared secret generation for ECDH/P-256. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p384_async_start (const otcrypto_blinded_key_t *private_key, const otcrypto_unblinded_key_t *public_key)
 Starts asynchronous shared secret generation for ECDH/P-384. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p384_async_finalize (otcrypto_blinded_key_t *shared_secret)
 Finalizes asynchronous shared secret generation for ECDH/P-384. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ed25519_keygen_async_start (const otcrypto_blinded_key_t *private_key)
 Starts the asynchronous key generation for Ed25519. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ed25519_keygen_async_finalize (otcrypto_blinded_key_t *private_key, otcrypto_unblinded_key_t *public_key)
 Finalizes the asynchronous key generation for Ed25519. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ed25519_sign_async_start (const otcrypto_blinded_key_t *private_key, otcrypto_const_byte_buf_t input_message, otcrypto_eddsa_sign_mode_t sign_mode, otcrypto_word32_buf_t signature)
 Starts the asynchronous Ed25519 digital signature generation. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ed25519_sign_async_finalize (otcrypto_word32_buf_t signature)
 Finalizes the asynchronous Ed25519 digital signature generation. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ed25519_verify_async_start (const otcrypto_unblinded_key_t *public_key, otcrypto_const_byte_buf_t input_message, otcrypto_eddsa_sign_mode_t sign_mode, otcrypto_const_word32_buf_t signature)
 Starts the asynchronous Ed25519 digital signature verification. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ed25519_verify_async_finalize (hardened_bool_t *verification_result)
 Finalizes the asynchronous Ed25519 digital signature verification. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_x25519_keygen_async_start (const otcrypto_blinded_key_t *private_key)
 Starts the asynchronous key generation for X25519. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_x25519_keygen_async_finalize (otcrypto_blinded_key_t *private_key, otcrypto_unblinded_key_t *public_key)
 Finalizes the asynchronous key generation for X25519. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_x25519_async_start (const otcrypto_blinded_key_t *private_key, const otcrypto_unblinded_key_t *public_key)
 Starts the asynchronous X25519 Diffie Hellman shared secret generation. More...
 
OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_x25519_async_finalize (otcrypto_blinded_key_t *shared_secret)
 Finalizes the asynchronous X25519 Diffie Hellman shared secret generation. More...
 

Detailed Description

Elliptic curve operations for OpenTitan cryptography library.

Includes ECDSA, ECDH, Ed25519, and X25519.

Definition in file ecc.h.

Typedef Documentation

◆ otcrypto_eddsa_sign_mode_t

Enum to define EdDSA mode for signature.

Values are hardened.

Enumeration Type Documentation

◆ otcrypto_eddsa_sign_mode

Enum to define EdDSA mode for signature.

Values are hardened.

Definition at line 26 of file ecc.h.

Function Documentation

◆ otcrypto_ecdh_p256()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p256 ( const otcrypto_blinded_key_t private_key,
const otcrypto_unblinded_key_t public_key,
otcrypto_blinded_key_t shared_secret 
)

Elliptic Curve Diffie Hellman shared secret generation with curve P-256.

Parameters
private_keyPointer to the blinded private key (d) struct.
public_keyPointer to the unblinded public key (Q) struct.
[out]shared_secretPointer to generated blinded shared key struct.
Returns
Result of ECDH shared secret generation.

Definition at line 82 of file ecc.c.

◆ otcrypto_ecdh_p256_async_finalize()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p256_async_finalize ( otcrypto_blinded_key_t shared_secret)

Finalizes asynchronous shared secret generation for ECDH/P-256.

See otcrypto_ecdh_p256 for requirements on input values.

May block until the operation is complete.

Parameters
[out]shared_secretPointer to generated blinded shared key struct.
Returns
Result of async ECDH finalize operation.

Definition at line 896 of file ecc.c.

◆ otcrypto_ecdh_p256_async_start()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p256_async_start ( const otcrypto_blinded_key_t private_key,
const otcrypto_unblinded_key_t public_key 
)

Starts asynchronous shared secret generation for ECDH/P-256.

See otcrypto_ecdh_p256 for requirements on input values.

Parameters
private_keyPointer to the blinded private key (d) struct.
public_keyPointer to the unblinded public key (Q) struct.
Returns
Result of async ECDH start operation.

Definition at line 849 of file ecc.c.

◆ otcrypto_ecdh_p256_keygen()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p256_keygen ( otcrypto_blinded_key_t private_key,
otcrypto_unblinded_key_t public_key 
)

Generates a key pair for ECDH with curve P-256.

The caller should allocate and partially populate the blinded key struct, including populating the key configuration and allocating space for the keyblob. For a hardware-backed key, use the private key handle returned by otcrypto_hw_backed_key. Otherwise, the mode should indicate ECDH with P-256 and the keyblob should be 80 bytes. The value in the checksum field of the blinded key struct will be populated by the key generation function.

Parameters
[out]private_keyPointer to the blinded private key (d) struct.
[out]public_keyPointer to the unblinded public key (Q) struct.
Returns
Result of the ECDH key generation.

Definition at line 70 of file ecc.c.

◆ otcrypto_ecdh_p256_keygen_async_finalize()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p256_keygen_async_finalize ( otcrypto_blinded_key_t private_key,
otcrypto_unblinded_key_t public_key 
)

Finalizes asynchronous key generation for ECDH/P-256.

See otcrypto_ecdh_p256_keygen for requirements on input values.

May block until the operation is complete.

The caller should ensure that the private key configuration matches that passed to the _start function.

Parameters
[out]private_keyPointer to the blinded private key (d) struct.
[out]public_keyPointer to the unblinded public key (Q) struct.
Returns
Result of asynchronous ECDH keygen finalize operation.

Definition at line 815 of file ecc.c.

◆ otcrypto_ecdh_p256_keygen_async_start()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p256_keygen_async_start ( const otcrypto_blinded_key_t private_key)

Starts asynchronous key generation for ECDH/P-256.

See otcrypto_ecdh_p256_keygen for requirements on input values.

Parameters
private_keyDestination structure for private key, or key handle.
Returns
Result of asynchronous ECDH keygen start operation.

Definition at line 789 of file ecc.c.

◆ otcrypto_ecdh_p384()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p384 ( const otcrypto_blinded_key_t private_key,
const otcrypto_unblinded_key_t public_key,
otcrypto_blinded_key_t shared_secret 
)

Elliptic Curve Diffie Hellman shared secret generation with curve P-384.

Parameters
private_keyPointer to the blinded private key (d) struct.
public_keyPointer to the unblinded public key (Q) struct.
[out]shared_secretPointer to generated blinded shared key struct.
Returns
Result of ECDH shared secret generation.

Definition at line 89 of file ecc.c.

◆ otcrypto_ecdh_p384_async_finalize()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p384_async_finalize ( otcrypto_blinded_key_t shared_secret)

Finalizes asynchronous shared secret generation for ECDH/P-384.

See otcrypto_ecdh_p384 for requirements on input values.

May block until the operation is complete.

Parameters
[out]shared_secretPointer to generated blinded shared key struct.
Returns
Result of async ECDH finalize operation.

Definition at line 984 of file ecc.c.

◆ otcrypto_ecdh_p384_async_start()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p384_async_start ( const otcrypto_blinded_key_t private_key,
const otcrypto_unblinded_key_t public_key 
)

Starts asynchronous shared secret generation for ECDH/P-384.

See otcrypto_ecdh_p384 for requirements on input values.

Parameters
private_keyPointer to the blinded private key (d) struct.
public_keyPointer to the unblinded public key (Q) struct.
Returns
Result of async ECDH start operation.

Definition at line 937 of file ecc.c.

◆ otcrypto_ecdh_p384_keygen()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p384_keygen ( otcrypto_blinded_key_t private_key,
otcrypto_unblinded_key_t public_key 
)

Generates a key pair for ECDH with curve P-384.

The caller should allocate and partially populate the blinded key struct, including populating the key configuration and allocating space for the keyblob. For a hardware-backed key, use the private key handle returned by otcrypto_hw_backed_key. Otherwise, the mode should indicate ECDH with P-384 and the keyblob should be 112 bytes. The value in the checksum field of the blinded key struct will be populated by the key generation function.

Parameters
[out]private_keyPointer to the blinded private key (d) struct.
[out]public_keyPointer to the unblinded public key (Q) struct.
Returns
Result of the ECDH key generation.

Definition at line 76 of file ecc.c.

◆ otcrypto_ecdh_p384_keygen_async_finalize()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p384_keygen_async_finalize ( otcrypto_blinded_key_t private_key,
otcrypto_unblinded_key_t public_key 
)

Finalizes asynchronous key generation for ECDH/P-384.

See otcrypto_ecdh_p384_keygen for requirements on input values.

May block until the operation is complete.

The caller should ensure that the private key configuration matches that passed to the _start function.

Parameters
[out]private_keyPointer to the blinded private key (d) struct.
[out]public_keyPointer to the unblinded public key (Q) struct.
Returns
Result of asynchronous ECDH keygen finalize operation.

Definition at line 832 of file ecc.c.

◆ otcrypto_ecdh_p384_keygen_async_start()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdh_p384_keygen_async_start ( const otcrypto_blinded_key_t private_key)

Starts asynchronous key generation for ECDH/P-384.

See otcrypto_ecdh_p384_keygen for requirements on input values.

Parameters
private_keyDestination structure for private key, or key handle.
Returns
Result of asynchronous ECDH keygen start operation.

Definition at line 802 of file ecc.c.

◆ otcrypto_ecdsa_p256_keygen()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p256_keygen ( otcrypto_blinded_key_t private_key,
otcrypto_unblinded_key_t public_key 
)

Generates a key pair for ECDSA with curve P-256.

The caller should allocate and partially populate the blinded key struct, including populating the key configuration and allocating space for the keyblob. For a hardware-backed key, use the private key handle returned by otcrypto_hw_backed_key. Otherwise, the mode should indicate ECDSA with P-256 and the keyblob should be 80 bytes. The value in the checksum field of the blinded key struct will be populated by the key generation function.

Parameters
[out]private_keyPointer to the blinded private key (d) struct.
[out]public_keyPointer to the unblinded public key (Q) struct.
Returns
Result of the ECDSA key generation.

Definition at line 18 of file ecc.c.

◆ otcrypto_ecdsa_p256_keygen_async_finalize()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p256_keygen_async_finalize ( otcrypto_blinded_key_t private_key,
otcrypto_unblinded_key_t public_key 
)

Finalizes asynchronous key generation for ECDSA/P-256.

See otcrypto_ecdsa_p256_keygen for requirements on input values.

May block until the operation is complete.

The caller should ensure that the private key configuration matches that passed to the _start function.

Parameters
[out]private_keyPointer to the blinded private key (d) struct.
[out]public_keyPointer to the unblinded public key (Q) struct.
Returns
Result of asynchronous ECDSA keygen finalize operation.

Definition at line 470 of file ecc.c.

◆ otcrypto_ecdsa_p256_keygen_async_start()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p256_keygen_async_start ( const otcrypto_blinded_key_t private_key)

Starts asynchronous key generation for ECDSA/P-256.

See otcrypto_ecdsa_p256_keygen for requirements on input values.

Parameters
private_keyDestination structure for private key, or key handle.
Returns
Result of asynchronous ECDSA keygen start operation.

Definition at line 176 of file ecc.c.

◆ otcrypto_ecdsa_p256_sign()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p256_sign ( const otcrypto_blinded_key_t private_key,
const otcrypto_hash_digest_t  message_digest,
otcrypto_word32_buf_t  signature 
)

Generates an ECDSA signature with curve P-256.

The message digest must be exactly 256 bits (32 bytes) long, but may use any hash mode. The caller is responsible for ensuring that the security strength of the hash function is at least equal to the security strength of the curve, but in some cases it may be truncated. See FIPS 186-5 for details.

Parameters
private_keyPointer to the blinded private key (d) struct.
message_digestMessage digest to be signed (pre-hashed).
[out]signaturePointer to the signature struct with (r,s) values.
Returns
Result of the ECDSA signature generation.

Definition at line 30 of file ecc.c.

◆ otcrypto_ecdsa_p256_sign_async_finalize()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p256_sign_async_finalize ( otcrypto_word32_buf_t  signature)

Finalizes asynchronous signature generation for ECDSA/P-256.

See otcrypto_ecdsa_p256_sign for requirements on input values.

May block until the operation is complete.

Parameters
[out]signaturePointer to the signature struct with (r,s) values.
Returns
Result of async ECDSA finalize operation.

Definition at line 649 of file ecc.c.

◆ otcrypto_ecdsa_p256_sign_async_start()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p256_sign_async_start ( const otcrypto_blinded_key_t private_key,
const otcrypto_hash_digest_t  message_digest 
)

Starts asynchronous signature generation for ECDSA/P-256.

See otcrypto_ecdsa_p256_sign for requirements on input values.

Parameters
private_keyPointer to the blinded private key (d) struct.
message_digestMessage digest to be signed (pre-hashed).
elliptic_curvePointer to the elliptic curve to be used.
Returns
Result of async ECDSA start operation.

Definition at line 511 of file ecc.c.

◆ otcrypto_ecdsa_p256_verify()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p256_verify ( const otcrypto_unblinded_key_t public_key,
const otcrypto_hash_digest_t  message_digest,
otcrypto_const_word32_buf_t  signature,
hardened_bool_t verification_result 
)

Verifies an ECDSA/P-256 signature.

The message digest must be exactly 256 bits (32 bytes) long, but may use any hash mode. The caller is responsible for ensuring that the security strength of the hash function is at least equal to the security strength of the curve, but in some cases it may be truncated. See FIPS 186-5 for details.

The caller must check the verification_result parameter, NOT only the returned status code, to know if the signature passed verification. The status code, as for other operations, only indicates whether errors were encountered, and may return OK even when the signature is invalid.

Parameters
public_keyPointer to the unblinded public key (Q) struct.
message_digestMessage digest to be verified (pre-hashed).
signaturePointer to the signature to be verified.
[out]verification_resultWhether the signature passed verification.
Returns
Result of the ECDSA verification operation.

Definition at line 48 of file ecc.c.

◆ otcrypto_ecdsa_p256_verify_async_finalize()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p256_verify_async_finalize ( otcrypto_const_word32_buf_t  signature,
hardened_bool_t verification_result 
)

Finalizes asynchronous signature verification for ECDSA/P-256.

See otcrypto_ecdsa_p256_verify for requirements on input values.

May block until the operation is complete.

Parameters
[out]verification_resultWhether the signature passed verification.
Returns
Result of async ECDSA verify finalize operation.

Definition at line 724 of file ecc.c.

◆ otcrypto_ecdsa_p256_verify_async_start()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p256_verify_async_start ( const otcrypto_unblinded_key_t public_key,
const otcrypto_hash_digest_t  message_digest,
otcrypto_const_word32_buf_t  signature 
)

Starts asynchronous signature verification for ECDSA/P-256.

See otcrypto_ecdsa_p256_verify for requirements on input values.

Parameters
public_keyPointer to the unblinded public key (Q) struct.
message_digestMessage digest to be verified (pre-hashed).
signaturePointer to the signature to be verified.
Returns
Result of async ECDSA verify start function.

Definition at line 683 of file ecc.c.

◆ otcrypto_ecdsa_p384_keygen()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p384_keygen ( otcrypto_blinded_key_t private_key,
otcrypto_unblinded_key_t public_key 
)

Generates a key pair for ECDSA with curve P-384.

The caller should allocate and partially populate the blinded key struct, including populating the key configuration and allocating space for the keyblob. For a hardware-backed key, use the private key handle returned by otcrypto_hw_backed_key. Otherwise, the mode should indicate ECDSA with P-384 and the keyblob should be 112 bytes. The value in the checksum field of the blinded key struct will be populated by the key generation function.

Parameters
[out]private_keyPointer to the blinded private key (d) struct.
[out]public_keyPointer to the unblinded public key (Q) struct.
Returns
Result of the ECDSA key generation.

Definition at line 24 of file ecc.c.

◆ otcrypto_ecdsa_p384_keygen_async_finalize()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p384_keygen_async_finalize ( otcrypto_blinded_key_t private_key,
otcrypto_unblinded_key_t public_key 
)

Finalizes asynchronous key generation for ECDSA/P-384.

See otcrypto_ecdsa_p384_keygen for requirements on input values.

May block until the operation is complete.

The caller should ensure that the private key configuration matches that passed to the _start function.

Parameters
[out]private_keyPointer to the blinded private key (d) struct.
[out]public_keyPointer to the unblinded public key (Q) struct.
Returns
Result of asynchronous ECDSA keygen finalize operation.

Definition at line 489 of file ecc.c.

◆ otcrypto_ecdsa_p384_keygen_async_start()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p384_keygen_async_start ( const otcrypto_blinded_key_t private_key)

Starts asynchronous key generation for ECDSA/P-384.

See otcrypto_ecdsa_p384_keygen for requirements on input values.

Parameters
private_keyDestination structure for private key, or key handle.
Returns
Result of asynchronous ECDSA keygen start operation.

Definition at line 219 of file ecc.c.

◆ otcrypto_ecdsa_p384_sign()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p384_sign ( const otcrypto_blinded_key_t private_key,
const otcrypto_hash_digest_t  message_digest,
otcrypto_word32_buf_t  signature 
)

Generates an ECDSA signature with curve P-384.

The message digest must be exactly 384 bits (48 bytes) long, but may use any hash mode. The caller is responsible for ensuring that the security strength of the hash function is at least equal to the security strength of the curve, but in some cases it may be truncated. See FIPS 186-5 for details.

Parameters
private_keyPointer to the blinded private key (d) struct.
message_digestMessage digest to be signed (pre-hashed).
[out]signaturePointer to the signature struct with (r,s) values.
Returns
Result of the ECDSA signature generation.

Definition at line 39 of file ecc.c.

◆ otcrypto_ecdsa_p384_sign_async_finalize()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p384_sign_async_finalize ( otcrypto_word32_buf_t  signature)

Finalizes asynchronous signature generation for ECDSA/P-384.

See otcrypto_ecdsa_p384_sign for requirements on input values.

May block until the operation is complete.

Parameters
[out]signaturePointer to the signature struct with (r,s) values.
Returns
Result of async ECDSA finalize operation.

Definition at line 666 of file ecc.c.

◆ otcrypto_ecdsa_p384_sign_async_start()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p384_sign_async_start ( const otcrypto_blinded_key_t private_key,
const otcrypto_hash_digest_t  message_digest 
)

Starts asynchronous signature generation for ECDSA/P-384.

See otcrypto_ecdsa_p384_sign for requirements on input values.

Parameters
private_keyPointer to the blinded private key (d) struct.
message_digestMessage digest to be signed (pre-hashed).
elliptic_curvePointer to the elliptic curve to be used.
Returns
Result of async ECDSA start operation.

Definition at line 560 of file ecc.c.

◆ otcrypto_ecdsa_p384_verify()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p384_verify ( const otcrypto_unblinded_key_t public_key,
const otcrypto_hash_digest_t  message_digest,
otcrypto_const_word32_buf_t  signature,
hardened_bool_t verification_result 
)

Verifies an ECDSA/P-384 signature.

The message digest must be exactly 384 bits (48 bytes) long, but may use any hash mode. The caller is responsible for ensuring that the security strength of the hash function is at least equal to the security strength of the curve, but in some cases it may be truncated. See FIPS 186-5 for details.

The caller must check the verification_result parameter, NOT only the returned status code, to know if the signature passed verification. The status code, as for other operations, only indicates whether errors were encountered, and may return OK even when the signature is invalid.

Parameters
public_keyPointer to the unblinded public key (Q) struct.
message_digestMessage digest to be verified (pre-hashed).
signaturePointer to the signature to be verified.
[out]verification_resultWhether the signature passed verification.
Returns
Result of the ECDSA verification operation.

Definition at line 59 of file ecc.c.

◆ otcrypto_ecdsa_p384_verify_async_finalize()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p384_verify_async_finalize ( otcrypto_const_word32_buf_t  signature,
hardened_bool_t verification_result 
)

Finalizes asynchronous signature verification for ECDSA/P-384.

See otcrypto_ecdsa_p384_verify for requirements on input values.

May block until the operation is complete.

Parameters
[out]verification_resultWhether the signature passed verification.
Returns
Result of async ECDSA verify finalize operation.

Definition at line 777 of file ecc.c.

◆ otcrypto_ecdsa_p384_verify_async_start()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ecdsa_p384_verify_async_start ( const otcrypto_unblinded_key_t public_key,
const otcrypto_hash_digest_t  message_digest,
otcrypto_const_word32_buf_t  signature 
)

Starts asynchronous signature verification for ECDSA/P-384.

See otcrypto_ecdsa_p384_verify for requirements on input values.

Parameters
public_keyPointer to the unblinded public key (Q) struct.
message_digestMessage digest to be verified (pre-hashed).
signaturePointer to the signature to be verified.
Returns
Result of async ECDSA verify start function.

Definition at line 736 of file ecc.c.

◆ otcrypto_ed25519_keygen()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ed25519_keygen ( otcrypto_blinded_key_t private_key,
otcrypto_unblinded_key_t public_key 
)

Generates a new Ed25519 key pair.

Computes the private exponent (d) and public key (Q) based on Curve25519.

No domain_parameter is needed and is automatically set for Ed25519.

The caller should allocate and partially populate the blinded key struct, including populating the key configuration and allocating space for the keyblob. The caller should indicate the length of the allocated keyblob; this function will return an error if the keyblob length does not match expectations. If the key is hardware-backed, the caller should pass a fully populated private key handle as returned by otcrypto_hw_backed_key. For non-hardware-backed keys, the keyblob should be twice the length of the key. The value in the checksum field of the blinded key struct will be populated by the key generation function.

Parameters
[out]private_keyPointer to the blinded private key struct.
[out]public_keyPointer to the unblinded public key struct.
Returns
Result of the Ed25519 key generation.

Definition at line 96 of file ecc.c.

◆ otcrypto_ed25519_keygen_async_finalize()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ed25519_keygen_async_finalize ( otcrypto_blinded_key_t private_key,
otcrypto_unblinded_key_t public_key 
)

Finalizes the asynchronous key generation for Ed25519.

Returns kOtcryptoStatusValueOk and copies private key (d) and public key (Q), if the OTBN status is done, or kOtcryptoStatusValueAsyncIncomplete if the OTBN is busy or kOtcryptoStatusValueInternalError if there is an error.

The caller must ensure that config matches the key configuration initially passed to the _start complement of this function.

Parameters
[out]private_keyPointer to the blinded private key struct.
[out]public_keyPointer to the unblinded public key struct.
Returns
Result of asynchronous ed25519 keygen finalize operation.

Definition at line 1031 of file ecc.c.

◆ otcrypto_ed25519_keygen_async_start()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ed25519_keygen_async_start ( const otcrypto_blinded_key_t private_key)

Starts the asynchronous key generation for Ed25519.

Initializes OTBN and begins generating an Ed25519 key pair. The caller should set the config field of private_key with their desired key configuration options. If the key is hardware-backed, the caller should pass a fully populated private key handle such as the kind returned by otcrypto_hw_backed_key.

No domain_parameter is needed and is automatically set for X25519.

Parameters
private_keyDestination structure for private key, or key handle.
Returns
Result of asynchronous ed25519 keygen start operation.

Definition at line 1025 of file ecc.c.

◆ otcrypto_ed25519_sign()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ed25519_sign ( const otcrypto_blinded_key_t private_key,
otcrypto_const_byte_buf_t  input_message,
otcrypto_eddsa_sign_mode_t  sign_mode,
otcrypto_word32_buf_t  signature 
)

Generates an Ed25519 digital signature.

Parameters
private_keyPointer to the blinded private key struct.
input_messageInput message to be signed.
sign_modeParameter for EdDSA or Hash EdDSA sign mode.
[out]signaturePointer to the EdDSA signature with (r,s) values.
Returns
Result of the EdDSA signature generation.

Definition at line 102 of file ecc.c.

◆ otcrypto_ed25519_sign_async_finalize()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ed25519_sign_async_finalize ( otcrypto_word32_buf_t  signature)

Finalizes the asynchronous Ed25519 digital signature generation.

Returns kOtcryptoStatusValueOk and copies the signature if the OTBN status is done, or kOtcryptoStatusValueAsyncIncomplete if the OTBN is busy or kOtcryptoStatusValueInternalError if there is an error.

Parameters
[out]signaturePointer to the EdDSA signature to get (s) value.
Returns
Result of async Ed25519 finalize operation.

Definition at line 1045 of file ecc.c.

◆ otcrypto_ed25519_sign_async_start()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ed25519_sign_async_start ( const otcrypto_blinded_key_t private_key,
otcrypto_const_byte_buf_t  input_message,
otcrypto_eddsa_sign_mode_t  sign_mode,
otcrypto_word32_buf_t  signature 
)

Starts the asynchronous Ed25519 digital signature generation.

Initializes OTBN and starts the OTBN routine to compute the digital signature on the input message. The domain_parameter field for Ed25519 is automatically set.

Parameters
private_keyPointer to the blinded private key struct.
input_messageInput message to be signed.
sign_modeParameter for EdDSA or Hash EdDSA sign mode.
[out]signaturePointer to the EdDSA signature to get (r) value.
Returns
Result of async Ed25519 start operation.

Definition at line 1037 of file ecc.c.

◆ otcrypto_ed25519_verify()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ed25519_verify ( const otcrypto_unblinded_key_t public_key,
otcrypto_const_byte_buf_t  input_message,
otcrypto_eddsa_sign_mode_t  sign_mode,
otcrypto_const_word32_buf_t  signature,
hardened_bool_t verification_result 
)

Verifies an Ed25519 signature.

Parameters
public_keyPointer to the unblinded public key struct.
input_messageInput message to be signed for verification.
sign_modeParameter for EdDSA or Hash EdDSA sign mode.
signaturePointer to the signature to be verified.
[out]verification_resultResult of signature verification (Pass/Fail).
Returns
Result of the EdDSA verification operation.

Definition at line 110 of file ecc.c.

◆ otcrypto_ed25519_verify_async_finalize()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ed25519_verify_async_finalize ( hardened_bool_t verification_result)

Finalizes the asynchronous Ed25519 digital signature verification.

Returns kOtcryptoStatusValueOk and populates the verification result with a PASS or FAIL, if the OTBN status is done, kOtcryptoStatusValueAsyncIncomplete if the OTBN is busy or kOtcryptoStatusValueInternalError if there is an error.

Parameters
[out]verification_resultResult of signature verification (Pass/Fail).
Returns
Result of async Ed25519 verification finalize operation.

Definition at line 1060 of file ecc.c.

◆ otcrypto_ed25519_verify_async_start()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_ed25519_verify_async_start ( const otcrypto_unblinded_key_t public_key,
otcrypto_const_byte_buf_t  input_message,
otcrypto_eddsa_sign_mode_t  sign_mode,
otcrypto_const_word32_buf_t  signature 
)

Starts the asynchronous Ed25519 digital signature verification.

Initializes OTBN and starts the OTBN routine to verify the signature. The domain_parameter for Ed25519 is set automatically.

Parameters
public_keyPointer to the unblinded public key struct.
input_messageInput message to be signed for verification.
sign_modeParameter for EdDSA or Hash EdDSA sign mode.
signaturePointer to the signature to be verified.
Returns
Result of async Ed25519 verification start operation.

Definition at line 1051 of file ecc.c.

◆ otcrypto_x25519()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_x25519 ( const otcrypto_blinded_key_t private_key,
const otcrypto_unblinded_key_t public_key,
otcrypto_blinded_key_t shared_secret 
)

Performs the X25519 Diffie Hellman shared secret generation.

Parameters
private_keyPointer to blinded private key (u-coordinate).
public_keyPointer to the public scalar from the sender.
[out]shared_secretPointer to shared secret key (u-coordinate).
Returns
Result of the X25519 operation.

Definition at line 125 of file ecc.c.

◆ otcrypto_x25519_async_finalize()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_x25519_async_finalize ( otcrypto_blinded_key_t shared_secret)

Finalizes the asynchronous X25519 Diffie Hellman shared secret generation.

Returns kOtcryptoStatusValueOk and copies shared_secret if the OTBN status is done, or kOtcryptoStatusValueAsyncIncomplete if the OTBN is busy or kOtcryptoStatusValueInternalError if there is an error.

Parameters
[out]shared_secretPointer to shared secret key (u-coordinate).
Returns
Result of async X25519 finalize operation.

Definition at line 1085 of file ecc.c.

◆ otcrypto_x25519_async_start()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_x25519_async_start ( const otcrypto_blinded_key_t private_key,
const otcrypto_unblinded_key_t public_key 
)

Starts the asynchronous X25519 Diffie Hellman shared secret generation.

Initializes OTBN and starts the OTBN routine to perform Diffie Hellman shared secret generation based on Curve25519. The domain parameter is automatically set for X25519 API.

Parameters
private_keyPointer to the blinded private key (u-coordinate).
public_keyPointer to the public scalar from the sender.
Returns
Result of the async X25519 start operation.

Definition at line 1078 of file ecc.c.

◆ otcrypto_x25519_keygen()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_x25519_keygen ( otcrypto_blinded_key_t private_key,
otcrypto_unblinded_key_t public_key 
)

Generates a new key pair for X25519 key exchange.

Computes the private scalar (d) and public key (Q) based on Curve25519.

No domain_parameter is needed and is automatically set for X25519.

The caller should allocate and partially populate the blinded key struct, including populating the key configuration and allocating space for the keyblob. The caller should indicate the length of the allocated keyblob; this function will return an error if the keyblob length does not match expectations. If the key is hardware-backed, the caller should pass a fully populated private key handle as returned by otcrypto_hw_backed_key. For non-hardware-backed keys, the keyblob should be twice the length of the key. The value in the checksum field of the blinded key struct will be populated by the key generation function.

Parameters
[out]private_keyPointer to the blinded private key struct.
[out]public_keyPointer to the unblinded public key struct.
Returns
Result of the X25519 key generation.

Definition at line 119 of file ecc.c.

◆ otcrypto_x25519_keygen_async_finalize()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_x25519_keygen_async_finalize ( otcrypto_blinded_key_t private_key,
otcrypto_unblinded_key_t public_key 
)

Finalizes the asynchronous key generation for X25519.

Returns kOtcryptoStatusValueOk and copies private key (d) and public key (Q), if the OTBN status is done, or kOtcryptoStatusValueAsyncIncomplete if the OTBN is busy or kOtcryptoStatusValueInternalError if there is an error.

The caller must ensure that config matches the key configuration initially passed to the _start complement of this function.

Parameters
[out]private_keyPointer to the blinded private key struct.
[out]public_keyPointer to the unblinded public key struct.
Returns
Result of asynchronous X25519 keygen finalize operation.

Definition at line 1072 of file ecc.c.

◆ otcrypto_x25519_keygen_async_start()

OT_WARN_UNUSED_RESULT otcrypto_status_t otcrypto_x25519_keygen_async_start ( const otcrypto_blinded_key_t private_key)

Starts the asynchronous key generation for X25519.

Initializes OTBN and begins generating an X25519 key pair. The caller should set the config field of private_key with their desired key configuration options. If the key is hardware-backed, the caller should pass a fully populated private key handle such as the kind returned by otcrypto_hw_backed_key.

No domain_parameter is needed and is automatically set for X25519.

Parameters
private_keyDestination structure for private key, or key handle.
Returns
Result of asynchronous X25519 keygen start operation.

Definition at line 1066 of file ecc.c.