Asymmetric Signature Algorithm Definitions¶

struct sig_alg¶: generic public key signature algorithm

Definition:

struct sig_alg {
    int (*sign)(struct crypto_sig *tfm,const void *src, unsigned int slen, void *dst, unsigned int dlen);
    int (*verify)(struct crypto_sig *tfm,const void *src, unsigned int slen, const void *digest, unsigned int dlen);
    int (*set_pub_key)(struct crypto_sig *tfm, const void *key, unsigned int keylen);
    int (*set_priv_key)(struct crypto_sig *tfm, const void *key, unsigned int keylen);
    unsigned int (*key_size)(struct crypto_sig *tfm);
    unsigned int (*digest_size)(struct crypto_sig *tfm);
    unsigned int (*max_size)(struct crypto_sig *tfm);
    int (*init)(struct crypto_sig *tfm);
    void (*exit)(struct crypto_sig *tfm);
    struct crypto_alg base;
};

Members

sign: Function performs a sign operation as defined by public key algorithm. Optional.
verify: Function performs a complete verify operation as defined by public key algorithm, returning verification status. Optional.
set_pub_key: Function invokes the algorithm specific set public key function, which knows how to decode and interpret the BER encoded public key and parameters. Mandatory.
set_priv_key: Function invokes the algorithm specific set private key function, which knows how to decode and interpret the BER encoded private key and parameters. Optional.
key_size: Function returns key size. Mandatory.
digest_size: Function returns maximum digest size. Optional.
max_size: Function returns maximum signature size. Optional.
init: Initialize the cryptographic transformation object. This function is used to initialize the cryptographic transformation object. This function is called only once at the instantiation time, right after the transformation context was allocated. In case the cryptographic hardware has some special requirements which need to be handled by software, this function shall check for the precise requirement of the transformation and put any software fallbacks in place.
exit: Deinitialize the cryptographic transformation object. This is a counterpart to init, used to remove various changes set in init.
base: Common crypto API algorithm data structure

Asymmetric Signature API¶

The Public Key Signature API is used with the algorithms of type CRYPTO_ALG_TYPE_SIG (listed as type “sig” in /proc/crypto)

struct crypto_sig *crypto_alloc_sig(const char *alg_name, u32 type, u32 mask)¶: allocate signature tfm handle

Parameters

const char *alg_name: is the cra_name / name or cra_driver_name / driver name of the signing algorithm e.g. “ecdsa”
u32 type: specifies the type of the algorithm
u32 mask: specifies the mask for the algorithm

Description

Allocate a handle for public key signature algorithm. The returned struct crypto_sig is the handle that is required for any subsequent API invocation for signature operations.

Return

allocated handle in case of success; IS_ERR() is true in case: of an error, PTR_ERR() returns the error code.

void crypto_free_sig(struct crypto_sig *tfm)¶: free signature tfm handle

Parameters

struct crypto_sig *tfm: signature tfm handle allocated with crypto_alloc_sig()

Description

If tfm is a NULL or error pointer, this function does nothing.

unsigned int crypto_sig_keysize(struct crypto_sig *tfm)¶: Get key size

Parameters

struct crypto_sig *tfm: signature tfm handle allocated with crypto_alloc_sig()

Description

Function returns the key size in bytes. Function assumes that the key is already set in the transformation. If this function is called without a setkey or with a failed setkey, you may end up in a NULL dereference.

unsigned int crypto_sig_digestsize(struct crypto_sig *tfm)¶: Get maximum digest size

Parameters

struct crypto_sig *tfm: signature tfm handle allocated with crypto_alloc_sig()

Description

Function returns the maximum digest size in bytes. Function assumes that the key is already set in the transformation. If this function is called without a setkey or with a failed setkey, you may end up in a NULL dereference.

unsigned int crypto_sig_maxsize(struct crypto_sig *tfm)¶: Get maximum signature size

Parameters

struct crypto_sig *tfm: signature tfm handle allocated with crypto_alloc_sig()

Description

Function returns the maximum signature size in bytes. Function assumes that the key is already set in the transformation. If this function is called without a setkey or with a failed setkey, you may end up in a NULL dereference.

int crypto_sig_sign(struct crypto_sig *tfm, const void *src, unsigned int slen, void *dst, unsigned int dlen)¶: Invoke signing operation

Parameters

struct crypto_sig *tfm: signature tfm handle allocated with crypto_alloc_sig()
const void *src: source buffer
unsigned int slen: source length
void *dst: destination obuffer
unsigned int dlen: destination length

Description

Function invokes the specific signing operation for a given algorithm

Return

zero on success; error code in case of error

int crypto_sig_verify(struct crypto_sig *tfm, const void *src, unsigned int slen, const void *digest, unsigned int dlen)¶: Invoke signature verification

Parameters

struct crypto_sig *tfm: signature tfm handle allocated with crypto_alloc_sig()
const void *src: source buffer
unsigned int slen: source length
const void *digest: digest
unsigned int dlen: digest length

Description

Function invokes the specific signature verification operation for a given algorithm.

Return

zero on verification success; error code in case of error.

int crypto_sig_set_pubkey(struct crypto_sig *tfm, const void *key, unsigned int keylen)¶: Invoke set public key operation

Parameters

struct crypto_sig *tfm: tfm handle
const void *key: BER encoded public key, algo OID, paramlen, BER encoded parameters
unsigned int keylen: length of the key (not including other data)

Description

Function invokes the algorithm specific set key function, which knows how to decode and interpret the encoded key and parameters

Return

zero on success; error code in case of error

int crypto_sig_set_privkey(struct crypto_sig *tfm, const void *key, unsigned int keylen)¶: Invoke set private key operation

Parameters

struct crypto_sig *tfm: tfm handle
const void *key: BER encoded private key, algo OID, paramlen, BER encoded parameters
unsigned int keylen: length of the key (not including other data)

Description

Function invokes the algorithm specific set key function, which knows how to decode and interpret the encoded key and parameters

Return

zero on success; error code in case of error