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 typeH) 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 typeH) 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 pLen, const byte * salt, int sLen, int iterations, int kLen, int typeH, int purpose) 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.

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 typeH
)

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 typeH
)

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 pLen,
    const byte * salt,
    int sLen,
    int iterations,
    int kLen,
    int typeH,
    int purpose
)

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
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
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_PKCS512_PBKDF(key, pass, sizeof(pass), salt, sizeof(salt), 2048,
sizeof(key), WC_SHA512, 1);
if ( ret != 0 ) {
    // error deriving key from password
}

Updated on 2024-12-20 at 01:22:24 +0000