DeriveCipherKey

DeriveCipherKey()

Syntax

Result = DeriveCipherKey(Password$, Salt$, Iterations, *Key, KeyBits, Plugin [, PluginBits])

Description

Creates a cypher key with the specified number of bits from an input password for use in other cypher functions like encryption or decryption. This function implements the PBKDF2 key derivation algorithm.

Parameters

Password$ The password for the key generation.

Salt$ A "salt" string to make the result of the function unique even if the same password is used. This makes brute force attacks harder and prevents information disclosure in case of matching passwords.

This value does not have to be secret but it should be unique if possible.

Iterations The number of iterations of the PBKDF2 key generation loop. A larger number increases the time/computations needed to compute the key and therefore makes brute force attacks harder.

*Key A pointer to the memory location that receives the generated key. The memory area must be at least KeyBits/8 bytes in size.

KeyBits The size of the key to generate in bits.
Plugin
The plugin for the fingerprint function to use in the key computation. It can be one of the following values:
  #PB_Cipher_MD5  : uses MD5 algorithm. UseMD5Fingerprint() needs to be called before to register this plugin.
  #PB_Cipher_SHA1 : uses SHA1 algorithm. UseSHA1Fingerprint() needs to be called before to register this plugin.
  #PB_Cipher_SHA2 : uses SHA2 algorithm. UseSHA2Fingerprint() needs to be called before to register this plugin.
  #PB_Cipher_SHA3 : uses SHA3 algorithm. UseSHA3Fingerprint() needs to be called before to register this plugin.
PluginBits (optional)
The bits number to use for the fingerprint function. It is only supported for the following plugin:
  #PB_Cipher_SHA2 : can be 224, 256 (default), 384 or 512.
  #PB_Cipher_SHA3 : can be 224, 256 (default), 384 or 512.
The number of bits for the fingerprint function is independent of the key size to generate. Any combination is allowed.

Return value

Returns nonzero if the key was generated. Returns zero only if the plugin parameters were invalid.

Example

  UseSHA2Fingerprint()
  *Key = AllocateMemory(32)

  ; Create a 256bit key using SHA-512 hash function and 500000 iterations
  DeriveCipherKey("SecretPassword", "NonSecretSalt", 500000, *Key, 256, #PB_Cipher_SHA2, 512)

  ; Show the key
  ShowMemoryViewer(*Key, 32)

See Also

AESEncoder(), AESDecoder(), StartAESCipher()

Supported OS

All

<- DESFingerprint() - Cipher Index - FileFingerprint() ->

Password$	The password for the key generation.
Salt$	A "salt" string to make the result of the function unique even if the same password is used. This makes brute force attacks harder and prevents information disclosure in case of matching passwords. This value does not have to be secret but it should be unique if possible.
Iterations	The number of iterations of the PBKDF2 key generation loop. A larger number increases the time/computations needed to compute the key and therefore makes brute force attacks harder.
*Key	A pointer to the memory location that receives the generated key. The memory area must be at least KeyBits/8 bytes in size.
KeyBits	The size of the key to generate in bits.
Plugin	The plugin for the fingerprint function to use in the key computation. It can be one of the following values: #PB_Cipher_MD5 : uses MD5 algorithm. UseMD5Fingerprint() needs to be called before to register this plugin. #PB_Cipher_SHA1 : uses SHA1 algorithm. UseSHA1Fingerprint() needs to be called before to register this plugin. #PB_Cipher_SHA2 : uses SHA2 algorithm. UseSHA2Fingerprint() needs to be called before to register this plugin. #PB_Cipher_SHA3 : uses SHA3 algorithm. UseSHA3Fingerprint() needs to be called before to register this plugin.
PluginBits (optional)	The bits number to use for the fingerprint function. It is only supported for the following plugin: #PB_Cipher_SHA2 : can be 224, 256 (default), 384 or 512. #PB_Cipher_SHA3 : can be 224, 256 (default), 384 or 512. The number of bits for the fingerprint function is independent of the key size to generate. Any combination is allowed.