asn.h

Functions

	Name
int	wc_BerToDer(const byte * ber, word32 berSz, byte * der, word32 * derSz) This function converts BER (Basic Encoding Rules) formatted data to DER (Distinguished Encoding Rules) format. BER allows indefinite length encoding while DER requires definite lengths. This function calculates definite lengths for all indefinite length items.
void	FreeAltNames(DNS_entry * altNames, void * heap) This function frees a linked list of alternative names (DNS_entry structures). It deallocates each node and its associated name string, IP string, and RID string if present.
int	wc_SetUnknownExtCallbackEx(DecodedCert * cert, wc_UnknownExtCallbackEx cb, void * ctx) This function sets an extended callback for handling unknown certificate extensions during certificate parsing. The callback receives additional context information compared to the basic callback.
int	wc_CheckCertSignature(const byte * cert, word32 certSz, void * heap, void * cm) This function verifies the signature on a certificate using a certificate manager. It checks that the certificate is properly signed by a trusted CA.
int	wc_EncodeObjectId(const word16 * in, word32 inSz, byte * out, word32 * outSz) This function encodes an array of word16 values into an ASN.1 Object Identifier (OID) in DER format. OIDs are used to identify algorithms, extensions, and other objects in certificates and cryptographic protocols.
word32	SetAlgoID(int algoOID, byte * output, int type, int curveSz) This function sets the algorithm identifier in DER format. It encodes the algorithm OID and optional parameters based on the algorithm type and curve size.
int	wc_DhPublicKeyDecode(const byte * input, word32 * inOutIdx, DhKey * key, word32 inSz) This function decodes a DER encoded Diffie-Hellman public key. It extracts the public key value from the DER encoding and stores it in the DhKey structure.

Functions Documentation

function wc_BerToDer

int wc_BerToDer(
    const byte * ber,
    word32 berSz,
    byte * der,
    word32 * derSz
)

This function converts BER (Basic Encoding Rules) formatted data to DER (Distinguished Encoding Rules) format. BER allows indefinite length encoding while DER requires definite lengths. This function calculates definite lengths for all indefinite length items.

Parameters:

• ber pointer to the buffer containing BER formatted data
• berSz size of the BER data in bytes
• der pointer to buffer to store DER formatted data (can be NULL to calculate required size)
• derSz pointer to size of der buffer; updated with actual size needed or used

See: wc_EncodeObjectId

Return:

• 0 On success.
• ASN_PARSE_E If the BER data is invalid.
• BAD_FUNC_ARG If ber or derSz are NULL.
• BUFFER_E If der is not NULL and derSz is too small.

Note: This API is not public by default. Define WOLFSSL_PUBLIC_ASN to expose APIs marked WOLFSSL_ASN_API.

Example

byte ber[256] = { }; // BER encoded data
byte der[256];
word32 derSz = sizeof(der);

int ret = wc_BerToDer(ber, sizeof(ber), der, &derSz);
if (ret == 0) {
    // der now contains DER formatted data of length derSz
}

function FreeAltNames

void FreeAltNames(
    DNS_entry * altNames,
    void * heap
)

This function frees a linked list of alternative names (DNS_entry structures). It deallocates each node and its associated name string, IP string, and RID string if present.

Parameters:

• altNames pointer to the head of the alternative names linked list
• heap pointer to heap hint for memory deallocation (can be NULL)

See: AltNameNew

Return: none No return value.

Note: This API is not public by default. Define WOLFSSL_PUBLIC_ASN to expose APIs marked WOLFSSL_ASN_API.

Example

DNS_entry* altNames = NULL;
// populate altNames with certificate alternative names

FreeAltNames(altNames, NULL);
// altNames list is now freed

function wc_SetUnknownExtCallbackEx

int wc_SetUnknownExtCallbackEx(
    DecodedCert * cert,
    wc_UnknownExtCallbackEx cb,
    void * ctx
)

This function sets an extended callback for handling unknown certificate extensions during certificate parsing. The callback receives additional context information compared to the basic callback.

Parameters:

• cert pointer to the DecodedCert structure
• cb callback function to handle unknown extensions
• ctx context pointer passed to the callback

See:

• wc_SetUnknownExtCallback
• wc_InitDecodedCert

Return:

• 0 On success.
• BAD_FUNC_ARG If cert is NULL.

Note: This API is not public by default. Define WOLFSSL_PUBLIC_ASN to expose APIs marked WOLFSSL_ASN_API.

Example

DecodedCert cert;

int UnknownExtCallback(const byte* oid, word32 oidSz, int crit,
                      const byte* der, word32 derSz, void* ctx) {
    // handle unknown extension
    return 0;
}

wc_InitDecodedCert(&cert, derCert, derCertSz, NULL);
wc_SetUnknownExtCallbackEx(&cert, UnknownExtCallback, myContext);
wc_ParseCert(&cert, CERT_TYPE, NO_VERIFY, NULL);

function wc_CheckCertSignature

int wc_CheckCertSignature(
    const byte * cert,
    word32 certSz,
    void * heap,
    void * cm
)

This function verifies the signature on a certificate using a certificate manager. It checks that the certificate is properly signed by a trusted CA.

Parameters:

• cert pointer to the DER encoded certificate
• certSz size of the certificate in bytes
• heap pointer to heap hint for memory allocation (can be NULL)
• cm pointer to certificate manager containing trusted CAs

See:

• wolfSSL_CertManagerNew
• wolfSSL_CertManagerLoadCA

Return:

• 0 On successful signature verification.
• ASN_SIG_CONFIRM_E If signature verification fails.
• Other negative values on error.

Example

byte cert[2048] = { }; // DER encoded certificate
word32 certSz = sizeof(cert);
WOLFSSL_CERT_MANAGER* cm;

cm = wolfSSL_CertManagerNew();
wolfSSL_CertManagerLoadCA(cm, "ca-cert.pem", NULL);

int ret = wc_CheckCertSignature(cert, certSz, NULL, cm);
if (ret == 0) {
    // certificate signature is valid
}
wolfSSL_CertManagerFree(cm);

function wc_EncodeObjectId

int wc_EncodeObjectId(
    const word16 * in,
    word32 inSz,
    byte * out,
    word32 * outSz
)

This function encodes an array of word16 values into an ASN.1 Object Identifier (OID) in DER format. OIDs are used to identify algorithms, extensions, and other objects in certificates and cryptographic protocols.

Parameters:

• in pointer to array of word16 values representing OID components
• inSz number of components in the OID
• out pointer to buffer to store encoded OID (can be NULL to calculate size)
• outSz pointer to size of out buffer; updated with actual size

See: wc_BerToDer

Return:

• 0 On success.
• BAD_FUNC_ARG If in, inSz, or outSz are invalid.
• BUFFER_E If out is not NULL and outSz is too small.

Example

word16 oid[] = {1, 2, 840, 113549, 1, 1, 11}; // sha256WithRSAEncryption
byte encoded[32];
word32 encodedSz = sizeof(encoded);

int ret = wc_EncodeObjectId(oid, sizeof(oid)/sizeof(word16),
                            encoded, &encodedSz);
if (ret == 0) {
    // encoded contains DER encoded OID
}

function SetAlgoID

word32 SetAlgoID(
    int algoOID,
    byte * output,
    int type,
    int curveSz
)

This function sets the algorithm identifier in DER format. It encodes the algorithm OID and optional parameters based on the algorithm type and curve size.

Parameters:

• algoOID algorithm object identifier constant
• output pointer to buffer to store encoded algorithm ID
• type type of encoding (oidSigType, oidHashType, etc.)
• curveSz size of the curve for ECC algorithms (0 for non-ECC)

See: wc_EncodeObjectId

Return:

• Length of the encoded algorithm identifier on success.
• Negative value on error.

Example

byte algId[32];
word32 len;

len = SetAlgoID(CTC_SHA256wRSA, algId, oidSigType, 0);
if (len > 0) {
    // algId contains encoded algorithm identifier
}

function wc_DhPublicKeyDecode

int wc_DhPublicKeyDecode(
    const byte * input,
    word32 * inOutIdx,
    DhKey * key,
    word32 inSz
)

This function decodes a DER encoded Diffie-Hellman public key. It extracts the public key value from the DER encoding and stores it in the DhKey structure.

Parameters:

• input pointer to buffer containing DER encoded public key
• inOutIdx pointer to index in buffer; updated to end of key
• key pointer to DhKey structure to store decoded public key
• inSz size of the input buffer

See:

• wc_InitDhKey
• wc_DhKeyDecode

Return:

• 0 On success.
• BAD_FUNC_ARG If input, inOutIdx, key, or inSz are invalid.
• ASN_PARSE_E If the DER encoding is invalid.
• Other negative values on error.

Example

byte derKey[256] = { }; // DER encoded DH public key
word32 idx = 0;
DhKey key;

wc_InitDhKey(&key);
int ret = wc_DhPublicKeyDecode(derKey, &idx, &key, sizeof(derKey));
if (ret == 0) {
    // key now contains the decoded public key
}
wc_FreeDhKey(&key);

Source code

int wc_BerToDer(const byte* ber, word32 berSz, byte* der, word32* derSz);

void FreeAltNames(DNS_entry* altNames, void* heap);

int wc_SetUnknownExtCallbackEx(DecodedCert* cert,
                               wc_UnknownExtCallbackEx cb, void *ctx);

int wc_CheckCertSignature(const byte* cert, word32 certSz, void* heap,
                          void* cm);

int wc_EncodeObjectId(const word16* in, word32 inSz, byte* out,
                      word32* outSz);

word32 SetAlgoID(int algoOID, byte* output, int type, int curveSz);

int wc_DhPublicKeyDecode(const byte* input, word32* inOutIdx, DhKey* key,
                         word32 inSz);

---

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