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)
int	wc_InitDsaKey_h(DsaKey * key, void * h) Initializes DSA key with heap hint.
int	wc_DsaSign_ex(const byte * digest, word32 digestSz, byte * out, DsaKey * key, WC_RNG * rng) Signs digest with extended parameters.
int	wc_DsaVerify_ex(const byte * digest, word32 digestSz, const byte * sig, DsaKey * key, int * answer) Verifies signature with extended parameters.
int	wc_SetDsaPublicKey(byte * output, DsaKey * key, int outLen, int with_header) Sets DSA public key in output buffer.
int	wc_DsaKeyToPublicDer(DsaKey * key, byte * output, word32 inLen) Converts DSA key to public DER format.
int	wc_DsaImportParamsRaw(DsaKey * dsa, const char * p, const char * q, const char * g) Imports DSA parameters from raw format. The parameters p, q, and g must be provided as ASCII hexadecimal strings (without 0x prefix). These represent the DSA domain parameters: p is the prime modulus, q is the prime divisor (subgroup order), and g is the generator.
int	wc_DsaImportParamsRawCheck(DsaKey * dsa, const char * p, const char * q, const char * g, int trusted, WC_RNG * rng) Imports DSA parameters from raw format with optional validation. The parameters p, q, and g must be provided as ASCII hexadecimal strings (without 0x prefix). The trusted parameter controls whether the prime p is validated: when trusted=1, prime checking is skipped (use when parameters come from a trusted source); when trusted=0, performs full primality testing on p (recommended for untrusted sources).
int	wc_DsaExportParamsRaw(DsaKey * dsa, byte * p, word32 * pSz, byte * q, word32 * qSz, byte * g, word32 * gSz) Exports DSA parameters to raw format.
int	wc_DsaExportKeyRaw(DsaKey * dsa, byte * x, word32 * xSz, byte * y, word32 * ySz) Exports DSA key to raw format.

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:

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:

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:

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:

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:

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
}

function wc_InitDsaKey_h

int wc_InitDsaKey_h(
    DsaKey * key,
    void * h
)

Initializes DSA key with heap hint.

Parameters:

key DSA key structure
h Heap hint for memory allocation

See: wc_InitDsaKey

Return:

0 on success
negative on failure

Example

DsaKey key;
int ret = wc_InitDsaKey_h(&key, NULL);

function wc_DsaSign_ex

int wc_DsaSign_ex(
    const byte * digest,
    word32 digestSz,
    byte * out,
    DsaKey * key,
    WC_RNG * rng
)

Signs digest with extended parameters.

Parameters:

digest Digest to sign
digestSz Digest size
out Output signature buffer
key DSA key
rng Random number generator

See: wc_DsaSign

Return:

0 on success
negative on failure

Example

byte digest[WC_SHA_DIGEST_SIZE];
byte sig[40];
WC_RNG rng;
int ret = wc_DsaSign_ex(digest, sizeof(digest), sig, &key,
                        &rng);

function wc_DsaVerify_ex

int wc_DsaVerify_ex(
    const byte * digest,
    word32 digestSz,
    const byte * sig,
    DsaKey * key,
    int * answer
)

Verifies signature with extended parameters.

Parameters:

digest Digest
digestSz Digest size
sig Signature buffer
key DSA key
answer Verification result

See: wc_DsaVerify

Return:

0 on success
negative on failure

Example

byte digest[WC_SHA_DIGEST_SIZE];
byte sig[40];
int answer;
int ret = wc_DsaVerify_ex(digest, sizeof(digest), sig, &key,
                          &answer);

function wc_SetDsaPublicKey

int wc_SetDsaPublicKey(
    byte * output,
    DsaKey * key,
    int outLen,
    int with_header
)

Sets DSA public key in output buffer.

Parameters:

output Output buffer
key DSA key
outLen Output buffer length
with_header Include header flag

See: wc_DsaKeyToPublicDer

Return:

Size on success
negative on failure

Example

byte output[256];
int ret = wc_SetDsaPublicKey(output, &key, sizeof(output), 1);

function wc_DsaKeyToPublicDer

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

Converts DSA key to public DER format.

Parameters:

key DSA key
output Output buffer
inLen Output buffer length

See: wc_SetDsaPublicKey

Return:

Size on success
negative on failure

Example

DsaKey key;
WC_RNG rng;
byte output[256];

// Initialize key and RNG
wc_InitDsaKey(&key);
wc_InitRng(&rng);

// Generate DSA key or import existing key
wc_MakeDsaKey(&rng, &key);

// Convert to public DER format
int ret = wc_DsaKeyToPublicDer(&key, output, sizeof(output));
if (ret > 0) {
    // output contains DER encoded public key of size ret
}

wc_FreeDsaKey(&key);
wc_FreeRng(&rng);

function wc_DsaImportParamsRaw

int wc_DsaImportParamsRaw(
    DsaKey * dsa,
    const char * p,
    const char * q,
    const char * g
)

Imports DSA parameters from raw format. The parameters p, q, and g must be provided as ASCII hexadecimal strings (without 0x prefix). These represent the DSA domain parameters: p is the prime modulus, q is the prime divisor (subgroup order), and g is the generator.

Parameters:

dsa DSA key structure (must be initialized)
p P parameter as ASCII hex string (prime modulus)
q Q parameter as ASCII hex string (prime divisor/subgroup order)
g G parameter as ASCII hex string (generator)

See:

Return:

0 on success
negative on failure

Example

DsaKey dsa;
wc_InitDsaKey(&dsa);

// DSA parameters as ASCII hexadecimal strings (example values)
const char* pStr = "E0A67598CD1B763BC98C8ABB333E5DDA0CD3AA0E5E1F"
                   "B5BA8A7B4EABC10BA338FAE06DD4B90FDA70D7CF0CB0"
                   "C638BE3341BEC0AF8A7330A3307DED2299A0EE606DF0"
                   "35177A239C34A912C202AA5F83B9C4A7CF0235B5316B"
                   "FC6EFB9A248411258B30B839AF172440F32563056CB6"
                   "7A861158DDD90E6A894C72A5BBEF9E286C6B";
const char* qStr = "E950511EAB424B9A19A2AEB4E159B7844C589C4F";
const char* gStr = "D29D5121B0423C2769AB21843E5A3240FF19CACC792D"
                   "C6E7925E6D1A4E6E4E3D119A3D133C8D3C8C8C8C8C8C"
                   "8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C"
                   "8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C";

int ret = wc_DsaImportParamsRaw(&dsa, pStr, qStr, gStr);
if (ret == 0) {
    // DSA parameters successfully imported
    // Can now use dsa for key generation or signing
}
wc_FreeDsaKey(&dsa);

function wc_DsaImportParamsRawCheck

int wc_DsaImportParamsRawCheck(
    DsaKey * dsa,
    const char * p,
    const char * q,
    const char * g,
    int trusted,
    WC_RNG * rng
)

Imports DSA parameters from raw format with optional validation. The parameters p, q, and g must be provided as ASCII hexadecimal strings (without 0x prefix). The trusted parameter controls whether the prime p is validated: when trusted=1, prime checking is skipped (use when parameters come from a trusted source); when trusted=0, performs full primality testing on p (recommended for untrusted sources).

Parameters:

dsa DSA key structure (must be initialized)
p P parameter as ASCII hex string (prime modulus)
q Q parameter as ASCII hex string (prime divisor/subgroup order)
g G parameter as ASCII hex string (generator)
trusted If 1, skip prime validation (trusted source); if 0, perform full primality test on p
rng Random number generator (required when trusted=0 for primality testing)

See:

Return:

0 on success
DH_CHECK_PUB_E if p fails primality test (when trusted=0)
negative on other failures

Example

DsaKey dsa;
WC_RNG rng;

// Initialize DSA key and RNG
wc_InitDsaKey(&dsa);
wc_InitRng(&rng);

// DSA parameters as ASCII hexadecimal strings
const char* pStr = "E0A67598CD1B763BC98C8ABB333E5DDA0CD3AA0E5E1F"
                   "B5BA8A7B4EABC10BA338FAE06DD4B90FDA70D7CF0CB0"
                   "C638BE3341BEC0AF8A7330A3307DED2299A0EE606DF0"
                   "35177A239C34A912C202AA5F83B9C4A7CF0235B5316B"
                   "FC6EFB9A248411258B30B839AF172440F32563056CB6"
                   "7A861158DDD90E6A894C72A5BBEF9E286C6B";
const char* qStr = "E950511EAB424B9A19A2AEB4E159B7844C589C4F";
const char* gStr = "D29D5121B0423C2769AB21843E5A3240FF19CACC792D"
                   "C6E7925E6D1A4E6E4E3D119A3D133C8D3C8C8C8C8C8C"
                   "8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C"
                   "8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C8C";

// Import with validation (trusted=0 performs primality test on p)
int ret = wc_DsaImportParamsRawCheck(&dsa, pStr, qStr, gStr, 0,
                                     &rng);
if (ret == 0) {
    // Parameters imported and validated successfully
}

wc_FreeDsaKey(&dsa);
wc_FreeRng(&rng);

function wc_DsaExportParamsRaw

int wc_DsaExportParamsRaw(
    DsaKey * dsa,
    byte * p,
    word32 * pSz,
    byte * q,
    word32 * qSz,
    byte * g,
    word32 * gSz
)

Exports DSA parameters to raw format.

Parameters:

dsa DSA key structure
p P parameter buffer
pSz P parameter size (in/out)
q Q parameter buffer
qSz Q parameter size (in/out)
g G parameter buffer
gSz G parameter size (in/out)

See: wc_DsaImportParamsRaw

Return:

0 on success
negative on failure

Example

byte p[256], q[32], g[256];
word32 pSz = sizeof(p), qSz = sizeof(q), gSz = sizeof(g);
int ret = wc_DsaExportParamsRaw(&dsa, p, &pSz, q, &qSz, g,
                                &gSz);

function wc_DsaExportKeyRaw

int wc_DsaExportKeyRaw(
    DsaKey * dsa,
    byte * x,
    word32 * xSz,
    byte * y,
    word32 * ySz
)

Exports DSA key to raw format.

Parameters:

dsa DSA key structure
x Private key buffer
xSz Private key size (in/out)
y Public key buffer
ySz Public key size (in/out)

See: wc_DsaImportParamsRaw

Return:

0 on success
negative on failure

Example

byte x[32], y[256];
word32 xSz = sizeof(x), ySz = sizeof(y);
int ret = wc_DsaExportKeyRaw(&dsa, x, &xSz, y, &ySz);

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);
int wc_InitDsaKey_h(DsaKey* key, void* h);

int wc_DsaSign_ex(const byte* digest, word32 digestSz, byte* out,
    DsaKey* key, WC_RNG* rng);

int wc_DsaVerify_ex(const byte* digest, word32 digestSz,
    const byte* sig, DsaKey* key, int* answer);

int wc_SetDsaPublicKey(byte* output, DsaKey* key, int outLen,
    int with_header);

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

int wc_DsaImportParamsRaw(DsaKey* dsa, const char* p, const char* q,
    const char* g);

int wc_DsaImportParamsRawCheck(DsaKey* dsa, const char* p,
    const char* q, const char* g, int trusted, WC_RNG* rng);

int wc_DsaExportParamsRaw(DsaKey* dsa, byte* p, word32* pSz, byte* q,
    word32* qSz, byte* g, word32* gSz);

int wc_DsaExportKeyRaw(DsaKey* dsa, byte* x, word32* xSz, byte* y,
    word32* ySz);

Updated on 2025-12-31 at 01:16:03 +0000