ECDSA APIs - zpc/ecdsa_ctx.h

Edit online

In file zpc/ecdsa_ctx.h, libzpc provides encryption APIs to support sign and verify operations for elliptic curve cryptography (ECDSA operations) using secure keys from CCA and EP11 cryptographic coprocessors.

Before using the provided ECDSA functions, be sure to read the Restrictions.

Data structures

The ECDSA context structure zpc_ecdsa_ctx is opaque for an application and is stored in objects of type

struct zpc_ecdsa_ctx;

Context objects must not be shared among multiple threads. They may be used for multiple operations by setting or resetting the key or initialization vector.

zpc_ecdsa_ctx_alloc

Purpose: Allocates a new context object for an ECDSA sign/verify operation.

Format:


int zpc_ecdsa_ctx_alloc(
    struct zpc_ecdsa_ctx **ctx);

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an ECDSA context

Return codes:

0 on success. Otherwise, a non-zero error code is returned.

zpc_ecdsa_ctx_set_key

Purpose: Set the key to be used in the context of an ECDSA sign/verify operation. If the key contains only one key part, private or public, only one operation, sign or verify, is possible with this key object.

Format:


int zpc_ecdsa_ctx_set_key(
    struct zpc_ecdsa_ctx *ctx, 
    struct zpc_ec_key *key);

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an ECDSA context
input	key	Pointer to an ECC key

Return codes:

0 on success. Otherwise, a non-zero error code is returned.

zpc_ecdsa_sign

Purpose: Perform an ECDSA sign operation.

The zpc_ecdsa_sign function supports ECDSA signatures with the following NIST curves:

prime256 (OID = 1.2.840.10045.3.1.7)
secp384 (OID = 1.3.132.0.34)
secp521 (OID = 1.3.132.0.35)

It also supports EdDSA signatures with the following Edwards curves:

Ed25519 (OID = 1.3.101.112)
Ed448 (OID = 1.3.101.113)

Format:


int zpc_ecdsa_sign(
    struct zpc_ecdsa_ctx *ctx, 
    unsigned char *hash, 
    unsigned int hash_len,  
    const unsigned char *signature, 
    unsigned int *sig_len);

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an ECDSA context
input	hash	Pointer to the hashed message to be signed
input	hash_len	Length of the input hashed message [bytes]. The input hash length is dependent on the used elliptic curve. For p256, use a SHA-256 hash with a length of 32 bytes, for p384, use a SHA2-384 hash with 48 bytes, and for p521, use a SHA2-512 hash with 64 bytes. Applications should not use weaker hash functions to produce smaller hashes than the recommended ones. However, shorter inputs would be right-aligned in the CPACF parameter block. Longer inputs are truncated to the recommended input lengths by cutting off rightmost bytes. For ed25519 and ed448, input messages of any length can be signed.
output	signature	Pointer to the generated signature
input, output	sig_len	Pointer to the signature length field (length is given in bytes). On input, the application must specify the buffer length to receive the signature [bytes]. If the signature is NULL, only the length of the signature is returned. The signature lengths related to the elliptic curves are: p256: 64 bytes p384: 96 bytes p521: 132 bytes ed25519: 64 bytes ed448: 114 bytes

Return codes:

0 on success. Otherwise, a non-zero error code is returned.

zpc_ecdsa_verify

Purpose: Perform an ECDSA verify operation.

Format:


int zpc_ecdsa_verify(
    struct zpc_ecdsa_ctx *ctx, 
    unsigned char *hash, 
    unsigned int hash_len,
    const unsigned char *signature, 
    unsigned int sig_len);

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an ECDSA context
input	hash	Pointer to the hashed message to be verified
input	hash_len	Length of the input hashed message [bytes]. The input hash length is dependent on the used elliptic curve. For p256, use a SHA-256 hash with a length of 32 bytes, for p384, use a SHA2-384 hash with 48 bytes, and for p521, use a SHA2-512 hash with 64 bytes. Applications should not use weaker hash functions to produce smaller hashes than the recommended ones. However, shorter inputs would be right-aligned in the CPACF parameter block. Longer inputs are truncated to the recommended input lengths by cutting off rightmost bytes. For ed25519 and ed448, input messages of any length can be verified.
input	signature	Pointer to the signature to be verified
input	sig_len	Signature length field [byte]. The signature lengths related to the elliptic curves are: p256: 64 bytes p384: 96 bytes p521: 132 bytes ed25519: 64 bytes ed448: 114 bytes

Return codes:

0 on success. Otherwise, a non-zero error code is returned.

zpc_ecdsa_ctx_free

Purpose: Free an ECDSA context.

Format:


void zpc_ecdsa_ctx_free(
     struct zpc_ecdsa_ctx **ctx);

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an ECDSA context