wolfssl/doc/dox_comments/header_files/pwdbased.h

/*!
    \ingroup Password
    
    \brief 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.
    
    \return 0 Returned on successfully deriving a key from the input password
    \return 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
    \return MEMORY_E Returned if there is an error allocating memory for a 
    SHA or MD5 object
    
    \param output pointer to the buffer in which to store the generated key. 
    Should be at least kLen long
    \param passwd pointer to the buffer containing the password to use for 
    the key derivation
    \param pLen length of the password to use for key derivation
    \param salt pointer to the buffer containing the salt to use for 
    key derivation
    \param sLen length of the salt
    \param iterations number of times to process the hash
    \param kLen desired length of the derived key. Should not be longer 
    than the digest size of the hash chosen
    \param hashType the hashing algorithm to use. Valid choices are MD5 and SHA
    
    _Example_
    \code
    int ret;
    byte key[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), MD5);
    if ( ret != 0 ) {
    	// error deriving key from password
    }
    \endcode
    
    \sa wc_PBKDF2
    \sa wc_PKCS12_PBKDF
*/
WOLFSSL_API int wc_PBKDF1(byte* output, const byte* passwd, int pLen,
                      const byte* salt, int sLen, int iterations, int kLen,
                      int typeH);

/*!
    \ingroup Password
    
    \brief 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: MD5, SHA, 
    SHA256, SHA384, SHA512, and BLAKE2B
    
    \return 0 Returned on successfully deriving a key from the input password
    \return BAD_FUNC_ARG Returned if there is an invalid hash type given or 
    iterations is less than 1
    \return MEMORY_E Returned if there is an allocating memory for 
    the HMAC object

    \param output pointer to the buffer in which to store the generated key. 
    Should be kLen long
    \param passwd pointer to the buffer containing the password to use for 
    the key derivation
    \param pLen length of the password to use for key derivation
    \param salt pointer to the buffer containing the salt to use for 
    key derivation
    \param sLen length of the salt
    \param iterations number of times to process the hash
    \param kLen desired length of the derived key
    \param hashType the hashing algorithm to use. Valid choices are: MD5, 
    SHA, SHA256, SHA384, SHA512, and BLAKE2B
    
    _Example_
    \code
    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), 
    SHA512);
    if ( ret != 0 ) {
    	// error deriving key from password
    }
    \endcode
    
    \sa wc_PBKDF1
    \sa wc_PKCS12_PBKDF
*/
WOLFSSL_API int wc_PBKDF2(byte* output, const byte* passwd, int pLen,
                      const byte* salt, int sLen, int iterations, int kLen,
                      int typeH);

/*!
    \ingroup Password
    
    \brief 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: MD5, SHA, SHA256, SHA384, SHA512, and BLAKE2B.
    
    \return 0 Returned on successfully deriving a key from the input password
    \return 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
    \return MEMORY_E Returned if there is an allocating memory
    \return MP_INIT_E may be returned if there is an error during key generation
    \return MP_READ_E may be returned if there is an error during key generation
    \return MP_CMP_E may be returned if there is an error during key generation
    \return MP_INVMOD_E may be returned if there is an error during 
    key generation
    \return MP_EXPTMOD_E may be returned if there is an error during 
    key generation
    \return MP_MOD_E may be returned if there is an error during key generation
    \return MP_MUL_E may be returned if there is an error during key generation
    \return MP_ADD_E may be returned if there is an error during key generation
    \return MP_MULMOD_E may be returned if there is an error during 
    key generation
    \return MP_TO_E may be returned if there is an error during key generation
    \return MP_MEM may be returned if there is an error during key generation
    
    \param output pointer to the buffer in which to store the generated key. 
    Should be kLen long
    \param passwd pointer to the buffer containing the password to use for 
    the key derivation
    \param pLen length of the password to use for key derivation
    \param salt pointer to the buffer containing the salt to use 
    for key derivation
    \param sLen length of the salt
    \param iterations number of times to process the hash
    \param kLen desired length of the derived key
    \param hashType the hashing algorithm to use. Valid choices are: MD5, 
    SHA, SHA256, SHA384, SHA512, and BLAKE2B
    \param id this is a byte indetifier 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.
    
    _Example_
    \code
    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), SHA512, 1);
    if ( ret != 0 ) {
    	// error deriving key from password
    }
    \endcode
    
    \sa wc_PBKDF1
    \sa wc_PBKDF2
*/
WOLFSSL_API int wc_PKCS12_PBKDF(byte* output, const byte* passwd, int pLen,
                            const byte* salt, int sLen, int iterations,
                            int kLen, int typeH, int purpose);