The ANSI C interface to the diCrPQC.dll library. More...

Functions
long	DSA_KeyGen (unsigned char lpOutput, long nOutBytes, const char szParams, long nOptions)
	Generate a DSA signing key pair (pk, sk) in a byte array. More...

long	DSA_Sign (unsigned char lpOutput, long nOutBytes, const unsigned char lpMsg, long nMsgLen, const unsigned char lpPrivateKey, long nKeyLen, const unsigned char lpContext, long nCtxLen, const char *szParams, long nOptions)
	Generate a DSA signature over a message. More...

long	DSA_SignPreHash (unsigned char lpOutput, long nOutBytes, const unsigned char lpMsg, long nMsgLen, long nHashAlg, const unsigned char lpPrivateKey, long nKeyLen, const unsigned char lpContext, long nCtxLen, const char *szParams, long nOptions)
	Generate a DSA signature over a pre-hashed message. More...

long	DSA_Verify (const unsigned char lpSignature, long nSigLen, const unsigned char lpMsg, long nMsgLen, const unsigned char lpPublicKey, long nKeyLen, const unsigned char lpContext, long nCtxLen, const char *szParams, long nOptions)
	Verify a DSA signature over a message. More...

long	DSA_VerifyPreHash (const unsigned char lpSignature, long nSigLen, const unsigned char lpMsg, long nMsgLen, long nHashAlg, const unsigned char lpPublicKey, long nKeyLen, const unsigned char lpContext, long nCtxLen, const char *szParams, long nOptions)
	Verify a DSA signature over a pre-hashed message. More...

long	DSA_PublicKeyFromPrivate (unsigned char lpOutput, long nOutBytes, const unsigned char lpPrivateKey, long nKeyLen, long nAlg)
	Extract the public key from a private key. More...

long	DSA_PublicKeySize (long nAlg)
	Return length in bytes of the public key for the DSA algorithm `nAlg`

long	DSA_PrivateKeySize (long nAlg)
	Return length in bytes of the private key for the DSA algorithm `nAlg`

long	DSA_SignatureSize (long nAlg)
	Return length in bytes of the signature for the DSA algorithm `nAlg`

long	KEM_EncapKeySize (long nAlg)
	Return length in bytes of the encapsulation ("public") key `ek` for the KEM algorithm `nAlg`

long	KEM_DecapKeySize (long nAlg)
	Return length in bytes of the decapsulation ("private") key `dk` for the KEM algorithm `nAlg`

long	KEM_CipherTextSize (long nAlg)
	Return length in bytes of the ciphertext `c` for the KEM algorithm `nAlg`

long	KEM_SharedKeySize (long nAlg)
	Return length in bytes of the shared secret key `K` (`SS`) for the KEM algorithm `nAlg`

long	KEM_KeyGen (unsigned char lpOutput, long nOutBytes, const char szParams, long nOptions)
	Generate a KEM encapsulation/decapsulation key pair (ek, dk). More...

long	KEM_Encaps (unsigned char lpOutput, long nOutBytes, const unsigned char lpEncapKey, long nEncapKeyLen, const char *szParams, long nOptions)
	Carry out the KEM encapsulation algorithm. More...

long	KEM_Decaps (unsigned char lpOutput, long nOutBytes, const unsigned char lpCipherText, long nCipherTextLen, const unsigned char lpDecapKey, long nDecapKeyLen, const char szParams, long nOptions)
	Carry out the KEM decapsulation algorithm. More...

long	PQC_Version (void)
	Get version number of the core DLL. More...

long	PQC_DllInfo (char *szOutput, long nOutChars, long nOptions)
	Get information about the core native diCrPQC DLL. More...

long	PQC_ModuleName (char *szOut, long nOutChars, long nOptions)
	Get full path name of core DLL module. More...

long	PQC_ErrorLookup (char *szOutput, long nOutChars, long nErrCode)
	Look up description for error code. More...

long	PQC_AlgName (char *szOutput, long nOutChars, long nOptions)
	Get the algorithm name from its code. More...

long	UTIL_HexFromBytes (char szOutput, long nOutChars, const unsigned char lpInput, long nInputLen)
	Encode an array of bytes into a hexadecimal-encoded string. More...

long	UTIL_HexToBytes (unsigned char lpOutput, long nOutBytes, const char szInput)
	Decode a hexadecimal-encoded string into an array of bytes. More...

long	UTIL_Substring (char szOutput, long nOutChars, const char szInput, long nStart, long nLen)
	Extract a substring of a string. More...

long	UTIL_SubstringBytes (unsigned char lpOutput, long nOutBytes, const unsigned char lpInput, long nInputLen, long nStart, long nLen)
	Extract a substring of a byte array. More...

long	RNG_Bytes (unsigned char lpOutput, long nOutBytes, const void lpSeed, long nSeedLen)
	Generate a random set of bytes suitable for cryptographic use. More...

long	RNG_Initialize (const char *szSeedFile, long nOptions)
	Initialize the RNG generator using a seed file. More...

long	RNG_InitializeEx (long nOptions)
	Query and initialize the RNG generator using Intel(R) DRNG, if available. More...

long	RNG_MakeSeedFile (const char szSeedFile, const char szPrompt, long nOptions)
	Create a new seed file suitable for use with RNG_Initialize(). More...

Detailed Description

The ANSI C interface to the diCrPQC.dll library.

A simple example program: #include <stdio.h>

#include "diCrPQC.h"

int main(void)

{

long version;

long nAlg;

// Get version of native DLL (if this works, the library has been installed correctly)

version = PQC_Version();

printf("Version=%ld\n", version);

// Get length in bytes of signature for SLH-DSA-SHA2-128f

nAlg = PQC_SLH_DSA_SHA2_128F;

printf("DSA_SignatureSize(SLH-DSA-SHA2-128f)=%ld\n", DSA_SignatureSize(nAlg)); // 17088

return 0;

}

diCrPQC.h
The ANSI C interface to the diCrPQC.dll library.

DSA_SignatureSize
long DSA_SignatureSize(long nAlg)
Return length in bytes of the signature for the DSA algorithm nAlg

PQC_Version
long PQC_Version(void)
Get version number of the core DLL.

Output to szOutput buffer: Functions that provide output to a string char *szOutput require the buffer to be allocated to at least the specified length nOutChars PLUS one extra for the null-terminating byte. To find the required length, pass a NULL szOut or zero nOutChars argument, then add one to the result for the required string buffer size.
unsigned char b[] = { 0xFE, 0xDC, 0xBA, 0x98, 0x76, 0x54, 0x32, 0x10 };

long blen = sizeof(b);

char *hexstr;

long nchars;

nchars = UTIL_HexFromBytes(NULL, 0, b, blen);

assert(nchars > 0);

hexstr = malloc(nchars + 1); // NB plus one

nchars = UTIL_HexFromBytes(hexstr, nchars, b, blen);

printf("hexstr=%s\n", hexstr); // hexstr=FEDCBA9876543210

free(hexstr);

UTIL_HexFromBytes
long UTIL_HexFromBytes(char *szOutput, long nOutChars, const unsigned char *lpInput, long nInputLen)
Encode an array of bytes into a hexadecimal-encoded string.

Output to lpOutput buffer: Functions that provide output to a byte array unsigned char *lpOutput require the buffer to be allocated to exactly the required length nOutBytes. To find the required length, pass a NULL lpOutput or zero nOutBytes argument.

Keypair output: The KeyGen functions output a keypair in concatenated form pk||sk. Similarly the KEM Encaps function outputs a concatenated pair ss||ct. Example:
// Generate a SLH-DSA-SHA-128F (SPHINCS+) keypair

long nAlg = PQC_SLH_DSA_SHA2_128F;

unsigned char *keypair, *pk, *sk;

int nbytes, pklen, sklen;

// Get required output length in bytes

nbytes = DSA_KeyGen(NULL, 0, "", nAlg); // 96

assert(nbytes > 0);

keypair = malloc(nbytes);

// Generate the keypair pk||sk

nbytes = DSA_KeyGen(keypair, nbytes, "", nAlg);

// Split up into required lengths

pklen = DSA_PublicKeySize(nAlg); // 32

sklen = DSA_PrivateKeySize(nAlg); // 64

pk = malloc(pklen); sk = malloc(sklen);

memcpy(pk, keypair, pklen);

memcpy(sk, &keypair[pklen], sklen);

DSA_PublicKeySize
long DSA_PublicKeySize(long nAlg)
Return length in bytes of the public key for the DSA algorithm nAlg

DSA_KeyGen
long DSA_KeyGen(unsigned char *lpOutput, long nOutBytes, const char *szParams, long nOptions)
Generate a DSA signing key pair (pk, sk) in a byte array.

DSA_PrivateKeySize
long DSA_PrivateKeySize(long nAlg)
Return length in bytes of the private key for the DSA algorithm nAlg

Function Documentation

◆ DSA_KeyGen()

long DSA_KeyGen	(	unsigned char *	lpOutput,
		long	nOutBytes,
		const char *	szParams,
		long	nOptions
	)

Generate a DSA signing key pair (pk, sk) in a byte array.

Parameters

[out]	lpOutput	Buffer of sufficient length to receive the output `pk\|\|sk`.
[in]	nOutBytes	Length of output buffer in bytes.
[in]	szParams	Optional parameters string. Set as NULL or `""` to ignore.
[in]	nOptions	Select one signature algorithm from: Module-Lattice-Based Digital Signature Standard (ML-DSA) specified in FIPS.204 `PQC_ML_DSA_44` / `PQC_ML_DSA_65` / `PQC_ML_DSA_87` Stateless Hash-Based Digital Signature Standard (SHL-DSA) specified in FIPS.205 `PQC_SLH_DSA_SHA2_128F` / `PQC_SLH_DSA_SHA2_128S` `PQC_SLH_DSA_SHA2_192F` / `PQC_SLH_DSA_SHA2_192S` `PQC_SLH_DSA_SHA2_256F` / `PQC_SLH_DSA_SHA2_256S` `PQC_SLH_DSA_SHAKE_128F` / `PQC_SLH_DSA_SHAKE_128S` `PQC_SLH_DSA_SHAKE_192F` / `PQC_SLH_DSA_SHAKE_128S` `PQC_SLH_DSA_SHAKE_256F` / `PQC_SLH_DSA_SHAKE_256S`

Returns: Number of bytes in or required for the output; or a negative error code.

Remarks: Output is pk||sk as a concatenated byte array.; Use szParams to pass known test random material encoded in hexadecimal [default=add fresh randomness]. For SLH-DSA pass a 3*n value SK.seed||SK.prf||PK.seed (48/72/96 bytes). For ML-DSA pass a 32-byte value seed (denoted ξ in FIPS.204).

◆ DSA_PublicKeyFromPrivate()

long DSA_PublicKeyFromPrivate	(	unsigned char *	lpOutput,
		long	nOutBytes,
		const unsigned char *	lpPrivateKey,
		long	nKeyLen,
		long	nAlg
	)

Extract the public key from a private key.

Parameters

[out]	lpOutput	Buffer of sufficient length to receive the output.
[in]	nOutBytes	Length of output buffer in bytes.
	lpPrivateKey	Private key in a byte array.
	nKeyLen	Length of private key in bytes.
	nAlg	Select one option for DSA signature algorithm.

Returns: Number of bytes in or required for the output; or a negative error code.

◆ DSA_Sign()

long DSA_Sign	(	unsigned char *	lpOutput,
		long	nOutBytes,
		const unsigned char *	lpMsg,
		long	nMsgLen,
		const unsigned char *	lpPrivateKey,
		long	nKeyLen,
		const unsigned char *	lpContext,
		long	nCtxLen,
		const char *	szParams,
		long	nOptions
	)

Generate a DSA signature over a message.

Parameters

[out]	lpOutput	Buffer of sufficient length to receive the output.
[in]	nOutBytes	Length of output buffer in bytes.
[in]	lpMsg	Message to be signed.
[in]	nMsgLen	Message length in bytes.
[in]	lpPrivateKey	Private key encoded as a byte array.
[in]	nKeyLen	Length of private key in bytes.
[in]	lpContext	Optional context string in a byte array. Set as NULL to ignore.
[in]	nCtxLen	Length of context string in bytes (maximum 255). Set as 0 to ignore.
[in]	szParams	Optional parameters string. Set as NULL or `""` to ignore.
[in]	nOptions	Select one signature algorithm from: Module-Lattice-Based Digital Signature Standard (ML-DSA) specified in FIPS.204 `PQC_ML_DSA_44` / `PQC_ML_DSA_65` / `PQC_ML_DSA_87` Stateless Hash-Based Digital Signature Standard (SHL-DSA) specified in FIPS.205 `PQC_SLH_DSA_SHA2_128F` / `PQC_SLH_DSA_SHA2_128S` `PQC_SLH_DSA_SHA2_192F` / `PQC_SLH_DSA_SHA2_192S` `PQC_SLH_DSA_SHA2_256F` / `PQC_SLH_DSA_SHA2_256S` `PQC_SLH_DSA_SHAKE_128F` / `PQC_SLH_DSA_SHAKE_128S` `PQC_SLH_DSA_SHAKE_192F` / `PQC_SLH_DSA_SHAKE_128S` `PQC_SLH_DSA_SHAKE_256F` / `PQC_SLH_DSA_SHAKE_256S` and optionally add `PQC_SIG_DETERMINISTIC` to use the deterministic variant when signing [default = hedged mode with randomness]. Use the bitwise OR operator "\|" to combine options. (For ML-DSA only) add the `PQC_SIG_EXTERNAL_MU` option flag to use the `ExternalMu-ML-DSA.Sign` algorithm (see remarks).

Returns: Number of bytes in or required for the output; or a negative error code.

Remarks: Use szParams to pass known test random material encoded in hexadecimal [default = add fresh randomness if in hedged mode]. For SLH-DSA pass a value addrnd of exactly n bytes (16|24|32 bytes). For ML-DSA pass a 32-byte value rnd.; When using the ExternalMu-ML-DSA.Sign option (ML-DSA only), pass the value of mu instead of the message in the parameter lpMsg. This must be exactly 64 bytes long. Caller is responsible for computing the value of mu independently prior to input.; For ML-DSA, the private key may be passed in expanded form (2560|4032|4896 bytes) or as a 32-byte seed. The key form is detected automatically by its length.

◆ DSA_SignPreHash()

long DSA_SignPreHash	(	unsigned char *	lpOutput,
		long	nOutBytes,
		const unsigned char *	lpMsg,
		long	nMsgLen,
		long	nHashAlg,
		const unsigned char *	lpPrivateKey,
		long	nKeyLen,
		const unsigned char *	lpContext,
		long	nCtxLen,
		const char *	szParams,
		long	nOptions
	)

Generate a DSA signature over a pre-hashed message.

Parameters

[out]	lpOutput	Buffer of sufficient length to receive the output.
[in]	nOutBytes	Length of output buffer in bytes.
[in]	lpMsg	Hash digest of message to be signed `PH_M = PH(M)`.
[in]	nMsgLen	Hash digest length in bytes.
[in]	nHashAlg	Pre-hash function `PH()`. Select one from `PQC_DSA_PREHASH_SHA256` / `PQC_DSA_PREHASH_SHA384` / `PQC_DSA_PREHASH_SHA512` `PQC_DSA_PREHASH_SHA512_256` / `PQC_DSA_PREHASH_SHA3_256` `PQC_DSA_PREHASH_SHA3_384` / `PQC_DSA_PREHASH_SHA3_512` `PQC_DSA_PREHASH_SHAKE128_256` / `PQC_DSA_PREHASH_SHAKE256_512`
[in]	lpPrivateKey	Private key encoded as a byte array.
[in]	nKeyLen	Length of private key in bytes.
[in]	lpContext	Optional context string in a byte array. Set as NULL to ignore.
[in]	nCtxLen	Length of context string in bytes (maximum 255). Set as 0 to ignore.
[in]	szParams	Optional parameters string. Set as NULL or `""` to ignore.
[in]	nOptions	Select one signature algorithm from: Module-Lattice-Based Digital Signature Standard (ML-DSA) specified in FIPS-204 `PQC_ML_DSA_44` / `PQC_ML_DSA_65` / `PQC_ML_DSA_87` Stateless Hash-Based Digital Signature Standard (SHL-DSA) specified in FIPS-205 `PQC_SLH_DSA_SHA2_128F` / `PQC_SLH_DSA_SHA2_128S` `PQC_SLH_DSA_SHA2_192F` / `PQC_SLH_DSA_SHA2_192S` `PQC_SLH_DSA_SHA2_256F` / `PQC_SLH_DSA_SHA2_256S` `PQC_SLH_DSA_SHAKE_128F` / `PQC_SLH_DSA_SHAKE_128S` `PQC_SLH_DSA_SHAKE_192F` / `PQC_SLH_DSA_SHAKE_128S` `PQC_SLH_DSA_SHAKE_256F` / `PQC_SLH_DSA_SHAKE_256S` and optionally add `PQC_SIG_DETERMINISTIC` to use the deterministic variant when signing [default = hedged mode with randomness]. Use the bitwise OR operator "\|" to combine options.

Returns: Number of bytes in or required for the output; or a negative error code.

Remarks: Use szParams to pass known test random material encoded in hexadecimal [default = add fresh randomness if in hedged mode]. For SLH-DSA pass a value addrnd of exactly n bytes (16/24/32 bytes). For ML-DSA pass a 32-byte value rnd. For the pre-hash version, the hash digest of the message is passed instead of the message itself. Caller is responsible for computing the hash digest independently prior to input. The hash function used must be identifed in the nHashAlg parameter.; For ML-DSA, the private key may be passed in expanded form (2560|4032|4896 bytes) or as a 32-byte seed. The key form is detected automatically by its length.

◆ DSA_Verify()

long DSA_Verify	(	const unsigned char *	lpSignature,
		long	nSigLen,
		const unsigned char *	lpMsg,
		long	nMsgLen,
		const unsigned char *	lpPublicKey,
		long	nKeyLen,
		const unsigned char *	lpContext,
		long	nCtxLen,
		const char *	szParams,
		long	nOptions
	)

Verify a DSA signature over a message.

Parameters

[in]	lpSignature	Signature in a byte array.
[in]	nSigLen	Signature length in bytes.
[in]	lpMsg	Message to be verified.
[in]	nMsgLen	Message length in bytes.
[in]	lpPublicKey	Public key encoded as a byte array.
[in]	nKeyLen	Length of public key in bytes.
[in]	lpContext	Same context string in a byte array as used when signing. Set as NULL to ignore.
[in]	nCtxLen	Length of context string in bytes (maximum 255). Set as 0 to ignore.
[in]	szParams	Optional parameters string. Set as NULL or `""` to ignore. Not used in this version.
[in]	nOptions	Select one signature algorithm from: Module-Lattice-Based Digital Signature Standard (ML-DSA) specified in FIPS.204 `PQC_ML_DSA_44` / `PQC_ML_DSA_65` / `PQC_ML_DSA_87` Stateless Hash-Based Digital Signature Standard (SHL-DSA) specified in FIPS.205 `PQC_SLH_DSA_SHA2_128F` / `PQC_SLH_DSA_SHA2_128S` `PQC_SLH_DSA_SHA2_192F` / `PQC_SLH_DSA_SHA2_192S` `PQC_SLH_DSA_SHA2_256F` / `PQC_SLH_DSA_SHA2_256S` `PQC_SLH_DSA_SHAKE_128F` / `PQC_SLH_DSA_SHAKE_128S` `PQC_SLH_DSA_SHAKE_192F` / `PQC_SLH_DSA_SHAKE_128S` `PQC_SLH_DSA_SHAKE_256F` / `PQC_SLH_DSA_SHAKE_256S` and optionally (for ML-DSA only) add the `PQC_SIG_EXTERNAL_MU` option flag to use the `ExternalMu-ML-DSA.Verify` algorithm (see remarks).

Returns: 0 if signature is valid else a negative error code.

Remarks: When using the ExternalMu-ML-DSA.Verify option (ML-DSA only), pass the value of mu instead of the message in the parameter lpMsg. This must be exactly 64 bytes long. Caller is responsible for computing the value of mu independently prior to input.

◆ DSA_VerifyPreHash()

long DSA_VerifyPreHash	(	const unsigned char *	lpSignature,
		long	nSigLen,
		const unsigned char *	lpMsg,
		long	nMsgLen,
		long	nHashAlg,
		const unsigned char *	lpPublicKey,
		long	nKeyLen,
		const unsigned char *	lpContext,
		long	nCtxLen,
		const char *	szParams,
		long	nOptions
	)

Verify a DSA signature over a pre-hashed message.

Parameters

[in]	lpSignature	Signature in a byte array.
[in]	nSigLen	Signature length in bytes.
[in]	lpMsg	Hash digest of message to be verified `PH_M = PH(M)`.
[in]	nMsgLen	Hash digest length in bytes.
[in]	nHashAlg	Pre-hash function `PH()`. Select one from `PQC_DSA_PREHASH_SHA256` / `PQC_DSA_PREHASH_SHA384` / `PQC_DSA_PREHASH_SHA512` `PQC_DSA_PREHASH_SHA512_256` / `PQC_DSA_PREHASH_SHA3_256` `PQC_DSA_PREHASH_SHA3_384` / `PQC_DSA_PREHASH_SHA3_512` `PQC_DSA_PREHASH_SHAKE128_256` / `PQC_DSA_PREHASH_SHAKE256_512`
[in]	lpPublicKey	Public key encoded as a byte array.
[in]	nKeyLen	Length of public key in bytes.
[in]	lpContext	Optional context string in a byte array. Set as NULL to ignore.
[in]	nCtxLen	Length of context string in bytes (maximum 255). Set as 0 to ignore.
[in]	szParams	Optional parameters string. Set as NULL or `""` to ignore. Not used in this version.
[in]	nOptions	Select one signature algorithm from: Module-Lattice-Based Digital Signature Standard (ML-DSA) specified in FIPS.204 `PQC_ML_DSA_44` / `PQC_ML_DSA_65` / `PQC_ML_DSA_87` Stateless Hash-Based Digital Signature Standard (SHL-DSA) specified in FIPS.205 `PQC_SLH_DSA_SHA2_128F` / `PQC_SLH_DSA_SHA2_128S` `PQC_SLH_DSA_SHA2_192F` / `PQC_SLH_DSA_SHA2_192S` `PQC_SLH_DSA_SHA2_256F` / `PQC_SLH_DSA_SHA2_256S` `PQC_SLH_DSA_SHAKE_128F` / `PQC_SLH_DSA_SHAKE_128S` `PQC_SLH_DSA_SHAKE_192F` / `PQC_SLH_DSA_SHAKE_128S` `PQC_SLH_DSA_SHAKE_256F` / `PQC_SLH_DSA_SHAKE_256S`

Returns: 0 if signature is valid else a negative error code.

Remarks: For the pre-hash version, the hash digest of the message is passed instead of the message itself. Caller is responsible for computing the hash digest independently prior to input. The hash function used must be identifed in the nHashAlg parameter.

◆ KEM_Decaps()

long KEM_Decaps	(	unsigned char *	lpOutput,
		long	nOutBytes,
		const unsigned char *	lpCipherText,
		long	nCipherTextLen,
		const unsigned char *	lpDecapKey,
		long	nDecapKeyLen,
		const char *	szParams,
		long	nOptions
	)

Carry out the KEM decapsulation algorithm.

Parameters

[out]	lpOutput	Buffer of sufficient length to receive the output `ss`.
[in]	nOutBytes	Length of output buffer in bytes.
[in]	lpCipherText	Ciphertext `ct` in a byte array.
[in]	nCipherTextLen	Length of ciphertext in bytes.
[in]	lpDecapKey	Decapsulation key `dk` in bytes (either as 64-byte seed or in expanded form).
[in]	nDecapKeyLen	Length of decapsulation key in bytes.
[in]	szParams	Optional parameters string. Set as NULL or `""` to ignore (for future use - not used in this release).
[in]	nOptions	Select one KEM algorithm from: Module-Lattice-based Key-Encapsulation Mechanism Standard (ML-KEM) specified in FIPS.203 `PQC_ML_KEM_512` / `PQC_ML_KEM_768` / `PQC_ML_KEM_1024`

Returns: Number of bytes in or required for the output; or a negative error code.

Remarks: Output is the shared secret key ss in a byte array. On failure, ss will contain a pseudo-random value.; The decapsulation (private) key may be passed in expanded form (1632|2400|3168 bytes) or as a 64-byte seed. The key form is detected automatically by its length.

◆ KEM_Encaps()

long KEM_Encaps	(	unsigned char *	lpOutput,
		long	nOutBytes,
		const unsigned char *	lpEncapKey,
		long	nEncapKeyLen,
		const char *	szParams,
		long	nOptions
	)

Carry out the KEM encapsulation algorithm.

Parameters

[out]	lpOutput	Buffer of sufficient length to receive the output `ss\|\|ct`.
[in]	nOutBytes	Length of output buffer in bytes.
[in]	lpEncapKey	Encapsulation key `ek` in a byte array.
[in]	nEncapKeyLen	Length of encapsulation key in bytes.
[in]	szParams	Optional parameters string. Set as NULL or `""` to ignore.
[in]	nOptions	Select one KEM algorithm from: Module-Lattice-based Key-Encapsulation Mechanism Standard (ML-KEM) specified in FIPS.203 `PQC_ML_KEM_512` / `PQC_ML_KEM_768` / `PQC_ML_KEM_1024`

Returns: Number of bytes in or required for the output; or a negative error code.

Remarks: Output is ss||ct as a concatenated pair of byte arrays, where ss is the shared key and ct is the ciphertext.; Use szParams to pass known test random material of exactly 32 bytes (m) encoded in hexadecimal [default=add fresh randomness].

◆ KEM_KeyGen()

long KEM_KeyGen	(	unsigned char *	lpOutput,
		long	nOutBytes,
		const char *	szParams,
		long	nOptions
	)

Generate a KEM encapsulation/decapsulation key pair (ek, dk).

Parameters

[out]	lpOutput	Buffer of sufficient length to receive the output `ek\|\|dk`.
[in]	nOutBytes	Length of output buffer in bytes.
[in]	szParams	Optional parameters string. Set as NULL or `""` to ignore.
[in]	nOptions	Select one KEM algorithm from: Module-Lattice-based Key-Encapsulation Mechanism Standard (ML-KEM) specified in FIPS.203 `PQC_ML_KEM_512` / `PQC_ML_KEM_768` / `PQC_ML_KEM_1024`

Returns: Number of bytes in or required for the output; or a negative error code.

Remarks: Output is ek||dk as a concatenated pair of byte arrays, where ek is the encapsulation key ("public key") and dk the decapsulation key ("private key").; Use szParams to pass known test random material of exactly 64 bytes (d||z) encoded in hexadecimal [default=add fresh randomness].

◆ PQC_AlgName()

long PQC_AlgName	(	char *	szOutput,
		long	nOutChars,
		long	nOptions
	)

Get the algorithm name from its code.

Parameters

[out]	szOutput	Buffer to receive output string.
[in]	nOutChars	Maximum number of characters to be received in output buffer.
[in]	nOptions	Algorithm code.

Returns: Number of characters in or required for output string.

Remarks: Example:
char namebuf[256];

PQC_AlgName(namebuf, sizeof(namebuf) - 1, PQC_ML_DSA_65);

printf("PQC_AlgName=[%s]\n", namebuf); // PQC_AlgName=[ML-DSA-65]

PQC_AlgName
long PQC_AlgName(char *szOutput, long nOutChars, long nOptions)
Get the algorithm name from its code.

◆ PQC_DllInfo()

long PQC_DllInfo	(	char *	szOutput,
		long	nOutChars,
		long	nOptions
	)

Get information about the core native diCrPQC DLL.

Parameters

[out]	szOutput	Buffer to receive output string.
[in]	nOutChars	Maximum number of characters to be received in output buffer.
[in]	nOptions	For future use.

Returns: Number of characters in or required for output string.

Remarks: Platform is the platform the core native DLL was compiled for: Win32 or X64.
"Platform=X64;Compiled=Apr 2 2024 19:13:31;Licence=T"

◆ PQC_ErrorLookup()

long PQC_ErrorLookup	(	char *	szOutput,
		long	nOutChars,
		long	nErrCode
	)

Look up description for error code.

Parameters

[out]	szOutput	Buffer to receive output string.
[in]	nOutChars	Maximum number of characters to be received in output buffer.
[in]	nErrCode	Value of error code to lookup (may be positive or negative).

Returns: Number of characters in or required for output string, or zero if no corresponding error code.

Remarks: Example:
char buf[256];

long nErrCode = -6;

long r = PQC_ErrorLookup(buf, sizeof(buf) - 1, nErrCode);

if (r > 0) printf("Error %ld: %s\n", nErrCode, buf);

PQC_ErrorLookup
long PQC_ErrorLookup(char *szOutput, long nOutChars, long nErrCode)
Look up description for error code.

Output:
Error -6: Parameter is wrong or missing (BAD_PARAM_ERROR)

◆ PQC_ModuleName()

long PQC_ModuleName	(	char *	szOut,
		long	nOutChars,
		long	nOptions
	)

Get full path name of core DLL module.

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes.
[in]	nOptions	Not used. Specify zero.

Returns: Number of characters in or required for output string; or a negative error code

Remarks: This may return C:\Windows\System32 when it is really C:\Windows\SysWOW64.; Example
"C:\Windows\System32\diCrPQC.dll"

◆ PQC_Version()

long PQC_Version ( void )

Get version number of the core DLL.

Returns: Version number as an integer in the form major*10000+minor*100+revision, e.g. core DLL file version 1.2.x.3 will return 10203.

◆ RNG_Bytes()

long RNG_Bytes	(	unsigned char *	lpOutput,
		long	nOutBytes,
		const void *	lpSeed,
		long	nSeedLen
	)

Generate a random set of bytes suitable for cryptographic use.

Parameters

[out]	lpOutput	Buffer to receive the random data.
[in]	nOutBytes	Length of output buffer in bytes.
[in]	lpSeed	Optional seed containing "user-supplied entropy" to be used by the random number generator. Specify an empty string ("") or NULL to ignore.
[in]	nSeedLen	Length of the seed string.

Returns: If successful, the return value is zero.

Remarks: If Intel(R) DRNG support is available on your system, then 256 bytes of SP800-90 compliant RNG entropy will be added automatically on first use of this function.

◆ RNG_Initialize()

long RNG_Initialize	(	const char *	szSeedFile,
		long	nOptions
	)

Initialize the RNG generator using a seed file.

Parameters

[in]	szSeedFile	Full path name of seed file.
[in]	nOptions	Not used - specify zero (0).

Returns: If successful, the return value is zero.

Remarks: Use this function if Intel(R) DRNG is not available on your system (check using RNG_InitializeEx()). Call at the start of a session to load entropy stored in the seed file, and use again at the end of a session to save any accumulated entropy. If the seed file does not exist, it will be created using any available entropy. The seed file is automatically updated by this procedure. Use RNG_MakeSeedFile() to create the first time.

◆ RNG_InitializeEx()

long RNG_InitializeEx ( long nOptions )

Query and initialize the RNG generator using Intel(R) DRNG, if available.

Parameters

[in] nOptions Specify PQC_RNG_NO_INTEL_DRNG to explicitly turn off support, else use zero (0).

Returns: Support status for Intel(R) DRNG. If available, then returns a positive value 1 or greater; else a negative error code.

Remarks: Use the NO_INTEL_DRNG option if for some reason it is interfering with your application.

◆ RNG_MakeSeedFile()

long RNG_MakeSeedFile	(	const char *	szSeedFile,
		const char *	szPrompt,
		long	nOptions
	)

Create a new seed file suitable for use with RNG_Initialize().

Parameters

[in]	szSeedFile	Full path name of seed file to be created. Any existing file of the same name will be overwritten without warning.
[in]	szPrompt	Optional prompt. Specify NULL or ‘"’` for default prompt.
[in]	nOptions	Select one of: `PQC_DEFAULT` (0) for default options `PQC_RNG_STRENGTH_112` to make user generate an estimated 112 bits of security `PQC_RNG_STRENGTH_128` to make user generate an estimated 128 bits of security (default) `PQC_RNG_STRENGTH_192` to make user generate an estimated 192 bits of security `PQC_RNG_STRENGTH_256` to make user generate an estimated 256 bits of security

Returns: If successful, the return value is zero.

Remarks: This uses a console dialog window and expects the user to type in random keystrokes. Such a GUI interface may not be appropriate in some circumstances.

◆ UTIL_HexFromBytes()

long UTIL_HexFromBytes	(	char *	szOutput,
		long	nOutChars,
		const unsigned char *	lpInput,
		long	nInputLen
	)

Encode an array of bytes into a hexadecimal-encoded string.

Parameters

[out]	szOutput	Buffer to receive encoded string.
[in]	nOutChars	Maximum number of characters to be received in output buffer.
[in]	lpInput	Byte array to be encoded.
[in]	nInputLen	Number of bytes to be encoded.

Returns: Number of characters in or required for output string; or a negative error code.

Remarks: Pass a NULL szOutput or zero nOutChars to find the required number of characters (then add one for the terminating null). HINT: the answer is two times the number of bytes.

◆ UTIL_HexToBytes()

long UTIL_HexToBytes	(	unsigned char *	lpOutput,
		long	nOutBytes,
		const char *	szInput
	)

Decode a hexadecimal-encoded string into an array of bytes.

Parameters

[out]	lpOutput	Buffer of sufficient length to receive the output.
[in]	nOutBytes	Length of output buffer in bytes.
[in]	szInput	Hexadecimal-encoded data to be decoded.

Returns: Number of bytes in or required for the output; or a negative error code.

Remarks: Expecting input to be a string of printable ASCII characters in the range [0-9A-Fa-f]. Whitespace and ASCII punctuation characters are allowed and will be ignored (e.g. DE:AD:BE:AF is OK), but those in the range [G-Zg-z] that are obviously non-hex will cause an error.; Pass a NULL lpOutput or zero nOutBytes to find the required number of bytes (this may be an upper bound).

◆ UTIL_Substring()

long UTIL_Substring	(	char *	szOutput,
		long	nOutChars,
		const char *	szInput,
		long	nStart,
		long	nLen
	)

Extract a substring of a string.

Parameters

[out]	szOutput	Buffer to receive output string (must exist and be long enough).
[in]	nOutChars	Maximum number of characters to be received in output buffer (excluding terminating zero).
[in]	szInput	Source string.
[in]	nStart	Start index (0 is the first character in the string). A negative value means count backwards from end of string.
[in]	nLen	Length of substring to extract (specify 0 to indicate all characters to end of string).

Returns: Number of characters in output string or a negative error code.

Remarks: Examples:
char *src = "The quick brown fox jumps over the lazy dog";

char dest[256];

UTIL_Substring(dest, sizeof(dest)-1, src, 0, 3);

printf("%s\n", dest); // The

UTIL_Substring(dest, sizeof(dest)-1, src, 4, 5);

printf("%s\n", dest); // quick

UTIL_Substring(dest, sizeof(dest)-1, src, -8, 4);

printf("%s\n", dest); // lazy

UTIL_Substring(dest, sizeof(dest)-1, src, -8, 0);

printf("%s\n", dest); // lazy dog

UTIL_Substring
long UTIL_Substring(char *szOutput, long nOutChars, const char *szInput, long nStart, long nLen)
Extract a substring of a string.; It is an error (NULL_ERROR) if szOutput is NULL.

◆ UTIL_SubstringBytes()

long UTIL_SubstringBytes	(	unsigned char *	lpOutput,
		long	nOutBytes,
		const unsigned char *	lpInput,
		long	nInputLen,
		long	nStart,
		long	nLen
	)

Extract a substring of a byte array.

Parameters

[out]	lpOutput	Buffer to receive output byte array (must exist and be long enough).
[in]	nOutBytes	Maximum number of bytes to be received in output buffer.
[in]	lpInput	Source byte array.
[in]	nInputLen	Length of source in bytes.
[in]	nStart	Start index (0 is the first byte in the array). A negative value means count backwards from end of array.
[in]	nLen	Length of substring to extract (specify 0 to indicate all bytes to end of array).

Returns: Number of bytes in output array.

Remarks: It is an error (NULL_ERROR) if lpOutput is NULL.

Functions

Detailed Description

Function Documentation

◆ DSA_KeyGen()

◆ DSA_PublicKeyFromPrivate()

◆ DSA_Sign()

◆ DSA_SignPreHash()

◆ DSA_Verify()

◆ DSA_VerifyPreHash()

◆ KEM_Decaps()

◆ KEM_Encaps()

◆ KEM_KeyGen()

◆ PQC_AlgName()

◆ PQC_DllInfo()

◆ PQC_ErrorLookup()

◆ PQC_ModuleName()

◆ PQC_Version()

◆ RNG_Bytes()

◆ RNG_Initialize()

◆ RNG_InitializeEx()

◆ RNG_MakeSeedFile()

◆ UTIL_HexFromBytes()

◆ UTIL_HexToBytes()

◆ UTIL_Substring()

◆ UTIL_SubstringBytes()