dsa.h

Functions

	Name
int	wc_InitDsaKey(DsaKey * key) This function initializes a DsaKey object in order to use it for authentication via the Digital Signature Algorithm (DSA).
void	wc_FreeDsaKey(DsaKey * key) This function frees a DsaKey object after it has been used.
int	wc_DsaSign(const byte * digest, byte * out, DsaKey * key, WC_RNG * rng) This function signs the input digest and stores the result in the output buffer, out.
int	wc_DsaVerify(const byte * digest, const byte * sig, DsaKey * key, int * answer) This function verifies the signature of a digest, given a private key. It stores whether the key properly verifies in the answer parameter, with 1 corresponding to a successful verification, and 0 corresponding to failed verification.
int	wc_DsaPublicKeyDecode(const byte * input, word32 * inOutIdx, DsaKey * key, word32 inSz) This function decodes a DER formatted certificate buffer containing a DSA public key, and stores the key in the given DsaKey structure. It also sets the inOutIdx parameter according to the length of the input read.
int	wc_DsaPrivateKeyDecode(const byte * input, word32 * inOutIdx, DsaKey * key, word32 inSz) This function decodes a DER formatted certificate buffer containing a DSA private key, and stores the key in the given DsaKey structure. It also sets the inOutIdx parameter according to the length of the input read.
int	wc_DsaKeyToDer(DsaKey * key, byte * output, word32 inLen) Convert DsaKey key to DER format, write to output (inLen), return bytes written.
int	wc_MakeDsaKey(WC_RNG * rng, DsaKey * dsa) Create a DSA key.
int	wc_MakeDsaParameters(WC_RNG * rng, int modulus_size, DsaKey * dsa) FIPS 186_4 defines valid for modulus_size values as (1024, 160) (2048, 256) (3072, 256)

Functions Documentation

function wc_InitDsaKey

int wc_InitDsaKey(
    DsaKey * key
)

This function initializes a DsaKey object in order to use it for authentication via the Digital Signature Algorithm (DSA).

Parameters:

• key pointer to the DsaKey structure to initialize

See: wc_FreeDsaKey

Return:

• 0 Returned on success.
• BAD_FUNC_ARG Returned if a NULL key is passed in.

Example

DsaKey key;
int ret;
ret = wc_InitDsaKey(&key); // initialize DSA key

function wc_FreeDsaKey

void wc_FreeDsaKey(
    DsaKey * key
)

This function frees a DsaKey object after it has been used.

Parameters:

• key pointer to the DsaKey structure to free

See: wc_FreeDsaKey

Return: none No returns.

Example

DsaKey key;
// initialize key, use for authentication
...
wc_FreeDsaKey(&key); // free DSA key

function wc_DsaSign

int wc_DsaSign(
    const byte * digest,
    byte * out,
    DsaKey * key,
    WC_RNG * rng
)

This function signs the input digest and stores the result in the output buffer, out.

Parameters:

• digest pointer to the hash to sign
• out pointer to the buffer in which to store the signature
• key pointer to the initialized DsaKey structure with which to generate the signature
• rng pointer to an initialized RNG to use with the signature generation

See: wc_DsaVerify

Return:

• 0 Returned on successfully signing the input digest
• MP_INIT_E may be returned if there is an error in processing the DSA signature.
• MP_READ_E may be returned if there is an error in processing the DSA signature.
• MP_CMP_E may be returned if there is an error in processing the DSA signature.
• MP_INVMOD_E may be returned if there is an error in processing the DSA signature.
• MP_EXPTMOD_E may be returned if there is an error in processing the DSA signature.
• MP_MOD_E may be returned if there is an error in processing the DSA signature.
• MP_MUL_E may be returned if there is an error in processing the DSA signature.
• MP_ADD_E may be returned if there is an error in processing the DSA signature.
• MP_MULMOD_E may be returned if there is an error in processing the DSA signature.
• MP_TO_E may be returned if there is an error in processing the DSA signature.
• MP_MEM may be returned if there is an error in processing the DSA signature.

Example

DsaKey key;
// initialize DSA key, load private Key
int ret;
WC_RNG rng;
wc_InitRng(&rng);
byte hash[] = { // initialize with hash digest };
byte signature[40]; // signature will be 40 bytes (320 bits)

ret = wc_DsaSign(hash, signature, &key, &rng);
if (ret != 0) {
    // error generating DSA signature
}

function wc_DsaVerify

int wc_DsaVerify(
    const byte * digest,
    const byte * sig,
    DsaKey * key,
    int * answer
)

This function verifies the signature of a digest, given a private key. It stores whether the key properly verifies in the answer parameter, with 1 corresponding to a successful verification, and 0 corresponding to failed verification.

Parameters:

• digest pointer to the digest containing the subject of the signature
• sig pointer to the buffer containing the signature to verify
• key pointer to the initialized DsaKey structure with which to verify the signature
• answer pointer to an integer which will store whether the verification was successful

See: wc_DsaSign

Return:

• 0 Returned on successfully processing the verify request. Note: this does not mean that the signature is verified, only that the function succeeded
• MP_INIT_E may be returned if there is an error in processing the DSA signature.
• MP_READ_E may be returned if there is an error in processing the DSA signature.
• MP_CMP_E may be returned if there is an error in processing the DSA signature.
• MP_INVMOD_E may be returned if there is an error in processing the DSA signature.
• MP_EXPTMOD_E may be returned if there is an error in processing the DSA signature.
• MP_MOD_E may be returned if there is an error in processing the DSA signature.
• MP_MUL_E may be returned if there is an error in processing the DSA signature.
• MP_ADD_E may be returned if there is an error in processing the DSA signature.
• MP_MULMOD_E may be returned if there is an error in processing the DSA signature.
• MP_TO_E may be returned if there is an error in processing the DSA signature.
• MP_MEM may be returned if there is an error in processing the DSA signature.

Example

DsaKey key;
// initialize DSA key, load public Key

int ret;
int verified;
byte hash[] = { // initialize with hash digest };
byte signature[] = { // initialize with signature to verify };
ret = wc_DsaVerify(hash, signature, &key, &verified);
if (ret != 0) {
    // error processing verify request
} else if (answer == 0) {
    // invalid signature
}

function wc_DsaPublicKeyDecode

int wc_DsaPublicKeyDecode(
    const byte * input,
    word32 * inOutIdx,
    DsaKey * key,
    word32 inSz
)

This function decodes a DER formatted certificate buffer containing a DSA public key, and stores the key in the given DsaKey structure. It also sets the inOutIdx parameter according to the length of the input read.

Parameters:

• input pointer to the buffer containing the DER formatted DSA public key
• inOutIdx pointer to an integer in which to store the final index of the certificate read
• key pointer to the DsaKey structure in which to store the public key
• inSz size of the input buffer

See:

• wc_InitDsaKey
• wc_DsaPrivateKeyDecode

Return:

• 0 Returned on successfully setting the public key for the DsaKey object
• ASN_PARSE_E Returned if there is an error in the encoding while reading the certificate buffer
• ASN_DH_KEY_E Returned if one of the DSA parameters is incorrectly formatted

Example

int ret, idx=0;

DsaKey key;
wc_InitDsaKey(&key);
byte derBuff[] = { // DSA public key};
ret = wc_DsaPublicKeyDecode(derBuff, &idx, &key, inSz);
if (ret != 0) {
    // error reading public key
}

function wc_DsaPrivateKeyDecode

int wc_DsaPrivateKeyDecode(
    const byte * input,
    word32 * inOutIdx,
    DsaKey * key,
    word32 inSz
)

This function decodes a DER formatted certificate buffer containing a DSA private key, and stores the key in the given DsaKey structure. It also sets the inOutIdx parameter according to the length of the input read.

Parameters:

• input pointer to the buffer containing the DER formatted DSA private key
• inOutIdx pointer to an integer in which to store the final index of the certificate read
• key pointer to the DsaKey structure in which to store the private key
• inSz size of the input buffer

See:

• wc_InitDsaKey
• wc_DsaPublicKeyDecode

Return:

• 0 Returned on successfully setting the private key for the DsaKey object
• ASN_PARSE_E Returned if there is an error in the encoding while reading the certificate buffer
• ASN_DH_KEY_E Returned if one of the DSA parameters is incorrectly formatted

Example

int ret, idx=0;

DsaKey key;
wc_InitDsaKey(&key);
byte derBuff[] = { // DSA private key };
ret = wc_DsaPrivateKeyDecode(derBuff, &idx, &key, inSz);
if (ret != 0) {
    // error reading private key
}

function wc_DsaKeyToDer

int wc_DsaKeyToDer(
    DsaKey * key,
    byte * output,
    word32 inLen
)

Convert DsaKey key to DER format, write to output (inLen), return bytes written.

Parameters:

• key Pointer to DsaKey structure to convert.
• output Pointer to output buffer for converted key.
• inLen Length of key input.

See:

• wc_InitDsaKey
• wc_FreeDsaKey
• wc_MakeDsaKey

Return:

• outLen Success, number of bytes written
• BAD_FUNC_ARG key or output are null or key->type is not DSA_PRIVATE.
• MEMORY_E Error allocating memory.

Example

DsaKey key;
WC_RNG rng;
int derSz;
int bufferSize = // Sufficient buffer size;
byte der[bufferSize];

wc_InitDsaKey(&key);
wc_InitRng(&rng);
wc_MakeDsaKey(&rng, &key);
derSz = wc_DsaKeyToDer(&key, der, bufferSize);

function wc_MakeDsaKey

int wc_MakeDsaKey(
    WC_RNG * rng,
    DsaKey * dsa
)

Create a DSA key.

Parameters:

• rng Pointer to WC_RNG structure.
• dsa Pointer to DsaKey structure.

See:

• wc_InitDsaKey
• wc_FreeDsaKey
• wc_DsaSign

Return:

• MP_OKAY Success
• BAD_FUNC_ARG Either rng or dsa is null.
• MEMORY_E Couldn't allocate memory for buffer.
• MP_INIT_E Error initializing mp_int

Example

WC_RNG rng;
DsaKey dsa;
wc_InitRng(&rng);
wc_InitDsa(&dsa);
if(wc_MakeDsaKey(&rng, &dsa) != 0)
{
    // Error creating key
}

function wc_MakeDsaParameters

int wc_MakeDsaParameters(
    WC_RNG * rng,
    int modulus_size,
    DsaKey * dsa
)

FIPS 186-4 defines valid for modulus_size values as (1024, 160) (2048, 256) (3072, 256)

Parameters:

• rng pointer to wolfCrypt rng.
• modulus_size 1024, 2048, or 3072 are valid values.
• dsa Pointer to a DsaKey structure.

See:

• wc_MakeDsaKey
• wc_DsaKeyToDer
• wc_InitDsaKey

Return:

• 0 Success
• BAD_FUNC_ARG rng or dsa is null or modulus_size is invalid.
• MEMORY_E Error attempting to allocate memory.

Example

DsaKey key;
WC_RNG rng;
wc_InitDsaKey(&key);
wc_InitRng(&rng);
if(wc_MakeDsaParameters(&rng, 1024, &genKey) != 0)
{
    // Handle error
}

Source code

int wc_InitDsaKey(DsaKey* key);

void wc_FreeDsaKey(DsaKey* key);

int wc_DsaSign(const byte* digest, byte* out,
                           DsaKey* key, WC_RNG* rng);

int wc_DsaVerify(const byte* digest, const byte* sig,
                             DsaKey* key, int* answer);

int wc_DsaPublicKeyDecode(const byte* input, word32* inOutIdx,
                                      DsaKey* key, word32 inSz);

int wc_DsaPrivateKeyDecode(const byte* input, word32* inOutIdx,
                                       DsaKey* key, word32 inSz);

int wc_DsaKeyToDer(DsaKey* key, byte* output, word32 inLen);

int wc_MakeDsaKey(WC_RNG *rng, DsaKey *dsa);

int wc_MakeDsaParameters(WC_RNG *rng, int modulus_size, DsaKey *dsa);

---

Updated on 2024-11-21 at 01:17:07 +0000