Skip to content

Algorithms - Password Based

Functions

Name
int wc_PBKDF1(byte * output, const byte * passwd, int pLen, const byte * salt, int sLen, int iterations, int kLen, int hashType)
This function implements the Password Based Key Derivation Function 1 (PBKDF1), converting an input password with a concatenated salt into a more secure key, which it stores in output. It allows the user to select between SHA and MD5 as hash functions.
int wc_PBKDF2(byte * output, const byte * passwd, int pLen, const byte * salt, int sLen, int iterations, int kLen, int hashType)
This function implements the Password Based Key Derivation Function 2 (PBKDF2), converting an input password with a concatenated salt into a more secure key, which it stores in output. It allows the user to select any of the supported HMAC hash functions, including: WC_MD5, WC_SHA, WC_SHA256, WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or WC_SHA3_512.
int wc_PKCS12_PBKDF(byte * output, const byte * passwd, int passLen, const byte * salt, int saltLen, int iterations, int kLen, int hashType, int id)
This function implements the Password Based Key Derivation Function (PBKDF) described in RFC 7292 Appendix B. This function converts an input password with a concatenated salt into a more secure key, which it stores in output. It allows the user to select any of the supported HMAC hash functions, including: WC_MD5, WC_SHA, WC_SHA256, WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or WC_SHA3_512.
int wc_PBKDF1_ex(byte * key, int keyLen, byte * iv, int ivLen, const byte * passwd, int passwdLen, const byte * salt, int saltLen, int iterations, int hashType, void * heap)
Extended version of PBKDF1 with heap hint.
int wc_PBKDF2_ex(byte * output, const byte * passwd, int pLen, const byte * salt, int sLen, int iterations, int kLen, int hashType, void * heap, int devId)
Extended version of PBKDF2 with heap hint and device ID.
int wc_PKCS12_PBKDF_ex(byte * output, const byte * passwd, int passLen, const byte * salt, int saltLen, int iterations, int kLen, int hashType, int id, void * heap)
Extended version of PKCS12_PBKDF with heap hint.
int wc_scrypt(byte * output, const byte * passwd, int passLen, const byte * salt, int saltLen, int cost, int blockSize, int parallel, int dkLen)
Implements scrypt key derivation function.
int wc_scrypt_ex(byte * output, const byte * passwd, int passLen, const byte * salt, int saltLen, word32 iterations, int blockSize, int parallel, int dkLen)
Extended scrypt with iteration count instead of cost.
int wc_PBKDF_max_iterations_set(int iters)
Set the current iteration limit for PBKDF.
int wc_PBKDF_max_iterations_get(void )
Get the current iteration limit for PBKDF.
int wc_BufferKeyDecrypt(struct EncryptedInfo * info, byte * der, word32 derSz, const byte * password, int passwordSz, int hashType)
This function decrypts an encrypted key buffer using the provided password. It supports encryption algorithms DES, 3DES, and AES. The encryption information is provided in the EncryptedInfo structure.
int wc_BufferKeyEncrypt(struct EncryptedInfo * info, byte * der, word32 derSz, const byte * password, int passwordSz, int hashType)
This function encrypts a key buffer using the provided password. It supports encryption algorithms DES, 3DES, and AES. The encryption information is provided in the EncryptedInfo structure.

Functions Documentation

function wc_PBKDF1

int wc_PBKDF1(
    byte * output,
    const byte * passwd,
    int pLen,
    const byte * salt,
    int sLen,
    int iterations,
    int kLen,
    int hashType
)

This function implements the Password Based Key Derivation Function 1 (PBKDF1), converting an input password with a concatenated salt into a more secure key, which it stores in output. It allows the user to select between SHA and MD5 as hash functions.

Parameters:

  • output pointer to the buffer in which to store the generated key. Should be at least kLen long
  • passwd pointer to the buffer containing the password to use for the key derivation
  • pLen length of the password to use for key derivation
  • salt pointer to the buffer containing the salt to use for key derivation
  • sLen length of the salt
  • iterations number of times to process the hash
  • kLen desired length of the derived key. Should not be longer than the digest size of the hash chosen
  • hashType the hashing algorithm to use. Valid choices are WC_MD5 and WC_SHA

See:

Return:

  • 0 Returned on successfully deriving a key from the input password
  • BAD_FUNC_ARG Returned if there is an invalid hash type given (valid type are: MD5 and SHA), iterations is less than 1, or the key length (kLen) requested is greater than the hash length of the provided hash
  • MEMORY_E Returned if there is an error allocating memory for a SHA or MD5 object

Example

int ret;
byte key[WC_MD5_DIGEST_SIZE];
byte pass[] = { }; // initialize with password
byte salt[] = { }; // initialize with salt

ret = wc_PBKDF1(key, pass, sizeof(pass), salt, sizeof(salt), 1000,
sizeof(key), WC_MD5);
if ( ret != 0 ) {
    // error deriving key from password
}

function wc_PBKDF2

int wc_PBKDF2(
    byte * output,
    const byte * passwd,
    int pLen,
    const byte * salt,
    int sLen,
    int iterations,
    int kLen,
    int hashType
)

This function implements the Password Based Key Derivation Function 2 (PBKDF2), converting an input password with a concatenated salt into a more secure key, which it stores in output. It allows the user to select any of the supported HMAC hash functions, including: WC_MD5, WC_SHA, WC_SHA256, WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or WC_SHA3_512.

Parameters:

  • output pointer to the buffer in which to store the generated key. Should be kLen long
  • passwd pointer to the buffer containing the password to use for the key derivation
  • pLen length of the password to use for key derivation
  • salt pointer to the buffer containing the salt to use for key derivation
  • sLen length of the salt
  • iterations number of times to process the hash
  • kLen desired length of the derived key
  • hashType the hashing algorithm to use. Valid choices are: WC_MD5, WC_SHA, WC_SHA256, WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or WC_SHA3_512

See:

Return:

  • 0 Returned on successfully deriving a key from the input password
  • BAD_FUNC_ARG Returned if there is an invalid hash type given or iterations is less than 1
  • MEMORY_E Returned if there is an allocating memory for the HMAC object

Example

int ret;
byte key[64];
byte pass[] = { }; // initialize with password
byte salt[] = { }; // initialize with salt

ret = wc_PBKDF2(key, pass, sizeof(pass), salt, sizeof(salt), 2048, sizeof(key),
WC_SHA512);
if ( ret != 0 ) {
    // error deriving key from password
}

function wc_PKCS12_PBKDF

int wc_PKCS12_PBKDF(
    byte * output,
    const byte * passwd,
    int passLen,
    const byte * salt,
    int saltLen,
    int iterations,
    int kLen,
    int hashType,
    int id
)

This function implements the Password Based Key Derivation Function (PBKDF) described in RFC 7292 Appendix B. This function converts an input password with a concatenated salt into a more secure key, which it stores in output. It allows the user to select any of the supported HMAC hash functions, including: WC_MD5, WC_SHA, WC_SHA256, WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or WC_SHA3_512.

Parameters:

  • output pointer to the buffer in which to store the generated key. Should be kLen long
  • passwd pointer to the buffer containing the password to use for the key derivation
  • passLen length of the password to use for key derivation
  • salt pointer to the buffer containing the salt to use for key derivation
  • saltLen length of the salt
  • iterations number of times to process the hash
  • kLen desired length of the derived key
  • hashType the hashing algorithm to use. Valid choices are: WC_MD5, WC_SHA, WC_SHA256, WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or WC_SHA3_512
  • id this is a byte identifier indicating the purpose of key generation. It is used to diversify the key output, and should be assigned as follows: ID=1: pseudorandom bits are to be used as key material for performing encryption or decryption. ID=2: pseudorandom bits are to be used an IV (Initial Value) for encryption or decryption. ID=3: pseudorandom bits are to be used as an integrity key for MACing.

See:

Return:

  • 0 Returned on successfully deriving a key from the input password
  • BAD_FUNC_ARG Returned if there is an invalid hash type given, iterations is less than 1, or the key length (kLen) requested is greater than the hash length of the provided hash
  • MEMORY_E Returned if there is an allocating memory
  • MP_INIT_E may be returned if there is an error during key generation
  • MP_READ_E may be returned if there is an error during key generation
  • MP_CMP_E may be returned if there is an error during key generation
  • MP_INVMOD_E may be returned if there is an error during key generation
  • MP_EXPTMOD_E may be returned if there is an error during key generation
  • MP_MOD_E may be returned if there is an error during key generation
  • MP_MUL_E may be returned if there is an error during key generation
  • MP_ADD_E may be returned if there is an error during key generation
  • MP_MULMOD_E may be returned if there is an error during key generation
  • MP_TO_E may be returned if there is an error during key generation
  • MP_MEM may be returned if there is an error during key generation

Example

int ret;
byte key[64];
byte pass[] = { }; // initialize with password
byte salt[] = { }; // initialize with salt

ret = wc_PKCS12_PBKDF(key, pass, sizeof(pass), salt, sizeof(salt), 2048,
sizeof(key), WC_SHA512, 1);
if ( ret != 0 ) {
    // error deriving key from password
}

function wc_PBKDF1_ex

int wc_PBKDF1_ex(
    byte * key,
    int keyLen,
    byte * iv,
    int ivLen,
    const byte * passwd,
    int passwdLen,
    const byte * salt,
    int saltLen,
    int iterations,
    int hashType,
    void * heap
)

Extended version of PBKDF1 with heap hint.

Parameters:

  • key Output key buffer
  • keyLen Key length
  • iv Output IV buffer
  • ivLen IV length
  • passwd Password buffer
  • passwdLen Password length
  • salt Salt buffer
  • saltLen Salt length
  • iterations Iteration count
  • hashType Hash algorithm type
  • heap Heap hint for memory allocation

See:

Return:

  • 0 on success
  • BAD_FUNC_ARG on invalid arguments or iterations is greater than current_wc_pbkdf_max_iterations
  • MEMORY_E on memory allocation error

Example

byte key[16], iv[16];
byte pass[] = "password";
byte salt[] = "salt";
int ret = wc_PBKDF1_ex(key, sizeof(key), iv, sizeof(iv),
    pass, sizeof(pass), salt, sizeof(salt), 1000, WC_SHA, NULL);

function wc_PBKDF2_ex

int wc_PBKDF2_ex(
    byte * output,
    const byte * passwd,
    int pLen,
    const byte * salt,
    int sLen,
    int iterations,
    int kLen,
    int hashType,
    void * heap,
    int devId
)

Extended version of PBKDF2 with heap hint and device ID.

Parameters:

  • output Output key buffer
  • passwd Password buffer
  • pLen Password length
  • salt Salt buffer
  • sLen Salt length
  • iterations Iteration count
  • kLen Key length
  • hashType Hash algorithm type
  • heap Heap hint for memory allocation
  • devId Device ID for hardware acceleration

See:

Return:

  • 0 on success
  • BAD_FUNC_ARG on invalid arguments or iterations is greater than current_wc_pbkdf_max_iterations
  • MEMORY_E on memory allocation error

Example

byte key[32];
byte pass[] = "password";
byte salt[] = "salt";
int ret = wc_PBKDF2_ex(key, pass, sizeof(pass), salt,
    sizeof(salt), 2048, sizeof(key), WC_SHA256, NULL,
    INVALID_DEVID);

function wc_PKCS12_PBKDF_ex

int wc_PKCS12_PBKDF_ex(
    byte * output,
    const byte * passwd,
    int passLen,
    const byte * salt,
    int saltLen,
    int iterations,
    int kLen,
    int hashType,
    int id,
    void * heap
)

Extended version of PKCS12_PBKDF with heap hint.

Parameters:

  • output Output key buffer
  • passwd Password buffer
  • passLen Password length
  • salt Salt buffer
  • saltLen Salt length
  • iterations Iteration count
  • kLen Key length
  • hashType Hash algorithm type
  • id Purpose identifier (1=key, 2=IV, 3=MAC)
  • heap Heap hint for memory allocation

See:

Return:

  • 0 on success
  • BAD_FUNC_ARG on invalid arguments or iterations is greater than current_wc_pbkdf_max_iterations
  • MEMORY_E on memory allocation error

Example

byte key[32];
byte pass[] = "password";
byte salt[] = "salt";
int ret = wc_PKCS12_PBKDF_ex(key, pass, sizeof(pass), salt,
    sizeof(salt), 2048, sizeof(key), WC_SHA256, 1, NULL);

function wc_scrypt

int wc_scrypt(
    byte * output,
    const byte * passwd,
    int passLen,
    const byte * salt,
    int saltLen,
    int cost,
    int blockSize,
    int parallel,
    int dkLen
)

Implements scrypt key derivation function.

Parameters:

  • output Output key buffer
  • passwd Password buffer
  • passLen Password length
  • salt Salt buffer
  • saltLen Salt length
  • cost CPU/memory cost parameter (N)
  • blockSize Block size parameter (r)
  • parallel Parallelization parameter (p)
  • dkLen Derived key length

See: wc_scrypt_ex

Return:

  • 0 on success
  • BAD_FUNC_ARG on invalid arguments
  • MEMORY_E on memory allocation error

Example

byte key[32];
byte pass[] = "password";
byte salt[] = "salt";
int ret = wc_scrypt(key, pass, sizeof(pass), salt,
    sizeof(salt), 16384, 8, 1, sizeof(key));

function wc_scrypt_ex

int wc_scrypt_ex(
    byte * output,
    const byte * passwd,
    int passLen,
    const byte * salt,
    int saltLen,
    word32 iterations,
    int blockSize,
    int parallel,
    int dkLen
)

Extended scrypt with iteration count instead of cost.

Parameters:

  • output Output key buffer
  • passwd Password buffer
  • passLen Password length
  • salt Salt buffer
  • saltLen Salt length
  • iterations Iteration count
  • blockSize Block size parameter (r)
  • parallel Parallelization parameter (p)
  • dkLen Derived key length

See: wc_scrypt

Return:

  • 0 on success
  • BAD_FUNC_ARG on invalid arguments
  • MEMORY_E on memory allocation error

Example

byte key[32];
byte pass[] = "password";
byte salt[] = "salt";
int ret = wc_scrypt_ex(key, pass, sizeof(pass), salt,
    sizeof(salt), 16384, 8, 1, sizeof(key));

function wc_PBKDF_max_iterations_set

int wc_PBKDF_max_iterations_set(
    int iters
)

Set the current iteration limit for PBKDF.

Parameters:

  • iters The new iteration limit.

See: wc_scrypt

Return:

  • Previous iteration limit on success
  • BAD_FUNC_ARG on invalid arguments

By default, the iteration limit is set to WC_PBKDF_DEFAULT_MAX_ITERATIONS, which can be overridden at build time. This function allows runtime override of the limit.

Note that [wc_PBKDF_max_iterations_set()](group__Password.md#function-wc_pbkdf_max_iterations_set) has no provisions for thread synchronization. Users should arrange to call it at startup or idle times, when there are no other PBKDF calls in progress.

Example

int prev_iter_limit = wc_PBKDF_max_iterations_set(100000000);

function wc_PBKDF_max_iterations_get

int wc_PBKDF_max_iterations_get(
    void 
)

Get the current iteration limit for PBKDF.

See: wc_scrypt

Return: Current iteration limit

Example

int cur_iter_limit = wc_PBKDF_max_iterations_get();

function wc_BufferKeyDecrypt

int wc_BufferKeyDecrypt(
    struct EncryptedInfo * info,
    byte * der,
    word32 derSz,
    const byte * password,
    int passwordSz,
    int hashType
)

This function decrypts an encrypted key buffer using the provided password. It supports encryption algorithms DES, 3DES, and AES. The encryption information is provided in the EncryptedInfo structure.

Parameters:

  • info pointer to EncryptedInfo structure containing encryption algorithm and parameters
  • der pointer to the encrypted key buffer
  • derSz size of the encrypted key buffer
  • password pointer to the password buffer
  • passwordSz size of the password
  • hashType hash algorithm to use for key derivation

See: wc_BufferKeyEncrypt

Return:

  • 0 on success
  • BAD_FUNC_ARG if der is NULL
  • BAD_FUNC_ARG if password is NULL
  • BAD_FUNC_ARG if info is NULL
  • BAD_FUNC_ARG if info->keySz is 0
  • BAD_FUNC_ARG if info->keySz > WC_MAX_SYM_KEY_SIZE
  • ALGO_ID_E if info->cipherType is not one of the cipher types this function handles
  • BUFFER_E if IV buffer is too small
  • NOT_COMPILED_IN if info->cipherType is a cipher type this function handles, but support for it was disabled in this build
  • Negative value on error

Example

EncryptedInfo info;
byte encryptedKey[32]; // encrypted key data, decrypted in place
byte password[] = "mypassword";

XMEMSET(&info, 0, sizeof(info));
info.cipherType = WC_CIPHER_AES_CBC;
info.keySz = 16;       // size of the key derived from the password

// info.iv holds the IV as hex characters, the way it appears in a PEM
// DEK-Info header.  It is Base16-decoded in place, and must decode to
// at least PKCS5_SALT_SZ bytes.  The decoded bytes are used both as the
// key derivation salt and as the cipher IV.
XMEMCPY(info.iv, "0123456789ABCDEF0123456789ABCDEF", 32);
info.ivSz = 32;        // length of the hex string, not the decoded IV

int ret = wc_BufferKeyDecrypt(&info, encryptedKey,
                              sizeof(encryptedKey), password,
                              sizeof(password)-1, WC_SHA256);
if (ret != 0) {
    // decryption error
}

function wc_BufferKeyEncrypt

int wc_BufferKeyEncrypt(
    struct EncryptedInfo * info,
    byte * der,
    word32 derSz,
    const byte * password,
    int passwordSz,
    int hashType
)

This function encrypts a key buffer using the provided password. It supports encryption algorithms DES, 3DES, and AES. The encryption information is provided in the EncryptedInfo structure.

Parameters:

  • info pointer to EncryptedInfo structure containing encryption algorithm and parameters
  • der pointer to the key buffer to encrypt
  • derSz size of the key buffer
  • password pointer to the password buffer
  • passwordSz size of the password
  • hashType hash algorithm to use for key derivation

See: wc_BufferKeyDecrypt

Return:

  • 0 on success
  • BAD_FUNC_ARG if der is NULL
  • BAD_FUNC_ARG if password is NULL
  • BAD_FUNC_ARG if info is NULL
  • BAD_FUNC_ARG if info->keySz is 0
  • BAD_FUNC_ARG if info->keySz > WC_MAX_SYM_KEY_SIZE
  • BAD_FUNC_ARG if info->ivSz < PKCS5_SALT_SZ
  • ALGO_ID_E if info->cipherType is not one of the cipher types this function handles
  • NOT_COMPILED_IN if info->cipherType is a cipher type this function handles, but support for it was disabled in this build
  • Negative value on error

Example

EncryptedInfo info;
byte key[32]; // key data to encrypt, encrypted in place
byte password[] = "mypassword";

XMEMSET(&info, 0, sizeof(info));
info.cipherType = WC_CIPHER_AES_CBC;
info.keySz = 16;   // size of the key derived from the password
info.ivSz  = 16;   // must be at least PKCS5_SALT_SZ

// Unlike wc_BufferKeyDecrypt, info.iv holds raw bytes here.  Fill it
// with info.ivSz random bytes; the first PKCS5_SALT_SZ of them are used
// as the key derivation salt, and the buffer is also used as the
// cipher IV.
WC_RNG rng;
wc_InitRng(&rng);
wc_RNG_GenerateBlock(&rng, info.iv, info.ivSz);

int ret = wc_BufferKeyEncrypt(&info, key, sizeof(key), password,
                              sizeof(password)-1, WC_SHA256);
if (ret != 0) {
    // encryption error
}
wc_FreeRng(&rng);

Updated on 2026-11-18 at 01:26:40 +0000