wolfCrypt Init and Cleanup

Functions

	Name
int	wc_HashGetOID(enum wc_HashType hash_type) This function will return the OID for the wc_HashType provided.
int	wc_HashGetDigestSize(enum wc_HashType hash_type) This function returns the size of the digest (output) for a hash_type. The returns size is used to make sure the output buffer provided to wc_Hash is large enough.
int	wc_Hash(enum wc_HashType hash_type, const byte * data, word32 data_len, byte * hash, word32 hash_len) This function performs a hash on the provided data buffer and returns it in the hash buffer provided.
int	wc_HashUpdate(wc_HashAlg * hash, enum wc_HashType type, const byte * data, word32 dataSz) This function updates the hash in a wc_HashAlg object with the provided data. The hash algorithm used is the one stored in the wc_HashAlg object when it was initialized with wc_HashInit() or wc_HashInit_ex().
int	wc_HashFinal(wc_HashAlg * hash, enum wc_HashType type, byte * out) This function finalizes the hash in a wc_HashAlg object and writes the resulting digest to out. The hash algorithm used is the one stored in the wc_HashAlg object when it was initialized with wc_HashInit() or wc_HashInit_ex().
int	wc_HashFree(wc_HashAlg * hash, enum wc_HashType type) This function frees any resources held by a wc_HashAlg object. The hash algorithm used is the one stored in the wc_HashAlg object when it was initialized with wc_HashInit() or wc_HashInit_ex(). The wc_HashAlg object itself is not freed.
int	wc_HashSetFlags(wc_HashAlg * hash, enum wc_HashType type, word32 flags) This function sets the flags of the underlying hash object in a wc_HashAlg object. The hash algorithm used is the one stored in the wc_HashAlg object when it was initialized with wc_HashInit() or wc_HashInit_ex(). Available when WOLFSSL_HASH_FLAGS is defined.
int	wc_HashGetFlags(wc_HashAlg * hash, enum wc_HashType type, word32 * flags) This function gets the flags of the underlying hash object in a wc_HashAlg object. The hash algorithm used is the one stored in the wc_HashAlg object when it was initialized with wc_HashInit() or wc_HashInit_ex(). Available when WOLFSSL_HASH_FLAGS is defined.
int	wc_UnpackOctets(byte * out, word32 outSz, const byte * in, word32 inSz, word32 octetSz) Expands a packed octet stream into the one_octet_per_byte_cell form every wolfCrypt byte* API expects. Declared only when WOLFSSL_WIDE_BYTE is set (CHAR_BIT != 8); elsewhere the two layouts coincide and no conversion is needed.
int	wc_PackOctets(byte * out, word32 outSz, const byte * in, word32 inSz, word32 octetSz) Packs a one_octet_per_byte_cell buffer into an octet stream, for storing to flash or handing to a byte_oriented peripheral. Inverse of wc_UnpackOctets(); requires WOLFSSL_WIDE_BYTE.
int	wolfCrypt_Init(void ) Used to initialize resources used by wolfCrypt.
int	wolfCrypt_Cleanup(void ) Used to clean up resources used by wolfCrypt.

Functions Documentation

function wc_HashGetOID

int wc_HashGetOID(
    enum wc_HashType hash_type
)

This function will return the OID for the wc_HashType provided.

Parameters:

• hash_type A hash type from the “enum wc_HashType” such as “WC_HASH_TYPE_SHA256”.

See:

• wc_HashGetDigestSize
• wc_Hash

Return:

• OID returns value greater than 0
• HASH_TYPE_E hash type not supported.
• BAD_FUNC_ARG one of the provided arguments is incorrect.

Example

enum wc_HashType hash_type = WC_HASH_TYPE_SHA256;
int oid = wc_HashGetOID(hash_type);
if (oid > 0) {
    // Success
}

function wc_HashGetDigestSize

int wc_HashGetDigestSize(
    enum wc_HashType hash_type
)

This function returns the size of the digest (output) for a hash_type. The returns size is used to make sure the output buffer provided to wc_Hash is large enough.

Parameters:

• hash_type A hash type from the “enum wc_HashType” such as “WC_HASH_TYPE_SHA256”.

See: wc_Hash

Return:

• Success A positive return value indicates the digest size for the hash.
• Error Returns HASH_TYPE_E if hash_type is not supported.
• Failure Returns BAD_FUNC_ARG if an invalid hash_type was used.

Example

int hash_len = wc_HashGetDigestSize(hash_type);
if (hash_len <= 0) {
WOLFSSL_MSG("Invalid hash type/len");
return BAD_FUNC_ARG;
}

function wc_Hash

int wc_Hash(
    enum wc_HashType hash_type,
    const byte * data,
    word32 data_len,
    byte * hash,
    word32 hash_len
)

This function performs a hash on the provided data buffer and returns it in the hash buffer provided.

Parameters:

• hash_type A hash type from the “enum wc_HashType” such as “WC_HASH_TYPE_SHA256”.
• data Pointer to buffer containing the data to hash.
• data_len Length of the data buffer.
• hash Pointer to buffer used to output the final hash to.
• hash_len Length of the hash buffer.

See: wc_HashGetDigestSize

Return: 0 Success, else error (such as BAD_FUNC_ARG or BUFFER_E).

Example

enum wc_HashType hash_type = WC_HASH_TYPE_SHA256;
int hash_len = wc_HashGetDigestSize(hash_type);
if (hash_len > 0) {
    int ret = wc_Hash(hash_type, data, data_len, hash_data, hash_len);
    if(ret == 0) {
        // Success
    }
}

function wc_HashUpdate

int wc_HashUpdate(
    wc_HashAlg * hash,
    enum wc_HashType type,
    const byte * data,
    word32 dataSz
)

This function updates the hash in a wc_HashAlg object with the provided data. The hash algorithm used is the one stored in the wc_HashAlg object when it was initialized with wc_HashInit() or wc_HashInit_ex().

Parameters:

• hash Pointer to the wc_HashAlg object, previously initialized with wc_HashInit() or wc_HashInit_ex().
• type Must be either WC_HASH_TYPE_NONE or the same hash type that was used to initialize the hash object. The hash type stored in the hash object during initialization is always used to select the algorithm. Any other value results in BAD_FUNC_ARG.
• data Pointer to buffer containing the data to hash. May be NULL only if dataSz is 0.
• dataSz Length of the data buffer in bytes.

See:

• wc_HashFinal
• wc_HashFree

Return:

• 0 Success.
• BAD_FUNC_ARG hash is NULL, data is NULL while dataSz is greater than 0, the hash object was not initialized with a valid hash type, or type is not WC_HASH_TYPE_NONE and does not match the hash type used during initialization.
• HASH_TYPE_E the hash type stored in the hash object is not supported or not compiled in.
• Other negative error codes may be returned by the underlying hash algorithm's update function.

Example

wc_HashAlg hash;
byte digest[WC_SHA256_DIGEST_SIZE];
byte data[] = { 0x61, 0x62, 0x63 };
int ret;

ret = wc_HashInit(&hash, WC_HASH_TYPE_SHA256);
if (ret == 0) {
    ret = wc_HashUpdate(&hash, WC_HASH_TYPE_SHA256, data, sizeof(data));
    if (ret == 0) {
        ret = wc_HashFinal(&hash, WC_HASH_TYPE_SHA256, digest);
    }
    wc_HashFree(&hash, WC_HASH_TYPE_SHA256);
}

function wc_HashFinal

int wc_HashFinal(
    wc_HashAlg * hash,
    enum wc_HashType type,
    byte * out
)

This function finalizes the hash in a wc_HashAlg object and writes the resulting digest to out. The hash algorithm used is the one stored in the wc_HashAlg object when it was initialized with wc_HashInit() or wc_HashInit_ex().

Parameters:

• hash Pointer to the wc_HashAlg object, previously initialized with wc_HashInit() or wc_HashInit_ex().
• type Must be either WC_HASH_TYPE_NONE or the same hash type that was used to initialize the hash object. The hash type stored in the hash object during initialization is always used to select the algorithm. Any other value results in BAD_FUNC_ARG.
• out Pointer to the buffer to receive the digest. It must be at least as large as the digest size of the hash type the object was initialized with (see wc_HashGetDigestSize()).

See:

• wc_HashUpdate
• wc_HashFree
• wc_HashGetDigestSize

Return:

• 0 Success.
• BAD_FUNC_ARG hash or out is NULL, the hash object was not initialized with a valid hash type, or type is not WC_HASH_TYPE_NONE and does not match the hash type used during initialization.
• HASH_TYPE_E the hash type stored in the hash object is not supported or not compiled in.
• Other negative error codes may be returned by the underlying hash algorithm's final function.

Example

wc_HashAlg hash;
byte digest[WC_SHA256_DIGEST_SIZE];
byte data[] = { 0x61, 0x62, 0x63 };
int ret;

ret = wc_HashInit(&hash, WC_HASH_TYPE_SHA256);
if (ret == 0) {
    ret = wc_HashUpdate(&hash, WC_HASH_TYPE_SHA256, data, sizeof(data));
    if (ret == 0) {
        ret = wc_HashFinal(&hash, WC_HASH_TYPE_SHA256, digest);
    }
    wc_HashFree(&hash, WC_HASH_TYPE_SHA256);
}

function wc_HashFree

int wc_HashFree(
    wc_HashAlg * hash,
    enum wc_HashType type
)

This function frees any resources held by a wc_HashAlg object. The hash algorithm used is the one stored in the wc_HashAlg object when it was initialized with wc_HashInit() or wc_HashInit_ex(). The wc_HashAlg object itself is not freed.

Parameters:

• hash Pointer to the wc_HashAlg object, previously initialized with wc_HashInit() or wc_HashInit_ex().
• type Must be either WC_HASH_TYPE_NONE or the same hash type that was used to initialize the hash object. The hash type stored in the hash object during initialization is always used to select the algorithm. Any other value results in BAD_FUNC_ARG.

See:

• wc_HashUpdate
• wc_HashFinal

Return:

• 0 Success.
• BAD_FUNC_ARG hash is NULL, the hash object was not initialized with a valid hash type, or type is not WC_HASH_TYPE_NONE and does not match the hash type used during initialization.
• HASH_TYPE_E the hash type stored in the hash object is not supported or not compiled in.

Example

wc_HashAlg hash;

if (wc_HashInit(&hash, WC_HASH_TYPE_SHA256) == 0) {
    // use hash
    wc_HashFree(&hash, WC_HASH_TYPE_SHA256);
}

function wc_HashSetFlags

int wc_HashSetFlags(
    wc_HashAlg * hash,
    enum wc_HashType type,
    word32 flags
)

This function sets the flags of the underlying hash object in a wc_HashAlg object. The hash algorithm used is the one stored in the wc_HashAlg object when it was initialized with wc_HashInit() or wc_HashInit_ex(). Available when WOLFSSL_HASH_FLAGS is defined.

Parameters:

• hash Pointer to the wc_HashAlg object, previously initialized with wc_HashInit() or wc_HashInit_ex().
• type Must be either WC_HASH_TYPE_NONE or the same hash type that was used to initialize the hash object. The hash type stored in the hash object during initialization is always used to select the algorithm. Any other value results in BAD_FUNC_ARG.
• flags Flags to set (for example WC_HASH_FLAG_ISCOPY).

See: wc_HashGetFlags

Return:

• 0 Success.
• BAD_FUNC_ARG hash is NULL, the hash object was not initialized with a valid hash type, or type is not WC_HASH_TYPE_NONE and does not match the hash type used during initialization.
• HASH_TYPE_E the hash type stored in the hash object is not supported or not compiled in.

Example

wc_HashAlg hash;

if (wc_HashInit(&hash, WC_HASH_TYPE_SHA256) == 0) {
    wc_HashSetFlags(&hash, WC_HASH_TYPE_SHA256, WC_HASH_FLAG_NONE);
    wc_HashFree(&hash, WC_HASH_TYPE_SHA256);
}

function wc_HashGetFlags

int wc_HashGetFlags(
    wc_HashAlg * hash,
    enum wc_HashType type,
    word32 * flags
)

This function gets the flags of the underlying hash object in a wc_HashAlg object. The hash algorithm used is the one stored in the wc_HashAlg object when it was initialized with wc_HashInit() or wc_HashInit_ex(). Available when WOLFSSL_HASH_FLAGS is defined.

Parameters:

• hash Pointer to the wc_HashAlg object, previously initialized with wc_HashInit() or wc_HashInit_ex().
• type Must be either WC_HASH_TYPE_NONE or the same hash type that was used to initialize the hash object. The hash type stored in the hash object during initialization is always used to select the algorithm. Any other value results in BAD_FUNC_ARG.
• flags Pointer to receive the current flags. If NULL, no flags are returned.

See: wc_HashSetFlags

Return:

• 0 Success.
• BAD_FUNC_ARG hash is NULL, the hash object was not initialized with a valid hash type, or type is not WC_HASH_TYPE_NONE and does not match the hash type used during initialization.
• HASH_TYPE_E the hash type stored in the hash object is not supported or not compiled in.

Example

wc_HashAlg hash;
word32 flags = 0;

if (wc_HashInit(&hash, WC_HASH_TYPE_SHA256) == 0) {
    wc_HashGetFlags(&hash, WC_HASH_TYPE_SHA256, &flags);
    wc_HashFree(&hash, WC_HASH_TYPE_SHA256);
}

function wc_UnpackOctets

int wc_UnpackOctets(
    byte * out,
    word32 outSz,
    const byte * in,
    word32 inSz,
    word32 octetSz
)

Expands a packed octet stream into the one-octet-per-byte-cell form every wolfCrypt byte* API expects. Declared only when WOLFSSL_WIDE_BYTE is set (CHAR_BIT != 8); elsewhere the two layouts coincide and no conversion is needed.

Parameters:

• out Destination, one octet per cell
• outSz Size of out in byte cells
• in Packed source, WC_OCTETS_PER_BYTE octets per cell, low octet first, and must not overlap out
• inSz Size of in in byte cells; must be at least WC_PACKED_CELLS(octetSz)
• octetSz Number of octets to expand

See: wc_PackOctets

Return:

• 0 on success
• BAD_FUNC_ARG when out or in is NULL
• BUFFER_E when out is smaller than octetSz, or in smaller than WC_PACKED_CELLS(octetSz)

Example

byte sig[WC_MLDSA_65_SIG_SIZE];
int ret = wc_UnpackOctets(sig, (word32)sizeof(sig), sigPacked,
                          (word32)sizeof(sigPacked),
                          WC_MLDSA_65_SIG_SIZE);

function wc_PackOctets

int wc_PackOctets(
    byte * out,
    word32 outSz,
    const byte * in,
    word32 inSz,
    word32 octetSz
)

Packs a one-octet-per-byte-cell buffer into an octet stream, for storing to flash or handing to a byte-oriented peripheral. Inverse of wc_UnpackOctets(); requires WOLFSSL_WIDE_BYTE.

Parameters:

• out Destination for the packed stream
• outSz Size of out in byte cells
• in Source, one octet per cell, and must not overlap out
• inSz Size of in in byte cells; must be at least octetSz
• octetSz Number of octets to pack

See: wc_UnpackOctets

Return:

• 0 on success
• BAD_FUNC_ARG when out or in is NULL
• BUFFER_E when out is smaller than WC_PACKED_CELLS(octetSz), or in smaller than octetSz

Example

byte packed[WC_PACKED_CELLS(sizeof(sig))];
int ret = wc_PackOctets(packed, (word32)sizeof(packed), sig,
                        (word32)sizeof(sig), (word32)sizeof(sig));

function wolfCrypt_Init

int wolfCrypt_Init(
    void 
)

Used to initialize resources used by wolfCrypt.

Parameters:

• none No parameters.

See: wolfCrypt_Cleanup

Return:

• 0 upon success.
• <0 upon failure of init resources.

Example

...
if (wolfCrypt_Init() != 0) {
    WOLFSSL_MSG("Error with wolfCrypt_Init call");
}

function wolfCrypt_Cleanup

int wolfCrypt_Cleanup(
    void 
)

Used to clean up resources used by wolfCrypt.

Parameters:

• none No parameters.

See: wolfCrypt_Init

Return:

• 0 upon success.
• <0 upon failure of cleaning up resources.

Example

...
if (wolfCrypt_Cleanup() != 0) {
    WOLFSSL_MSG("Error with wolfCrypt_Cleanup call");
}

---

Updated on 2026-10-21 at 04:09:56 +0000