Root > Reference > All Functions > TEADeriveKey

Function TEADeriveKey

Previous pageReturn to chapter overviewNext page   

Initializes TEA key from password.

 

Unit

EEncrypt

 

Syntax

 

Code (Delphi)

function TEADeriveKey(

const APassword: String;

const ASalt: PSalt = nil

): TTEAKey; overload;

 

function TEADeriveKey(

const AData: Pointer;

const ADataSize: Cardinal;

const ASalt: PSalt = nil

): TTEAKey; overload;

 

Parameters

APassword [in, opt]

User password.

 

ASalt [in, opt]

Optional salt value. It is recommended to always use/specify salt when possible - to defend against dictionary and pre-computed rainbow table attacks. Use InitSalt function to create new salt for encryption and store salt with encrypted data. Use stored salt to decrypt data.

 

AData [in]

Pointer to binary password to initialize the key.

 

ADataSize [in]

Size of AData in bytes.

 

Return value

TEA key derived from APassword and (optionally) ASalt.

 

You do not need to free/release/dispose this key - it does not contain any allocated memory. However, it is strongly recommended to call TEADestroyKey function once you have finished working with key - to erase it with zeros.

 

This value is always the same for the same APassword (and same ASalt).

 

Remarks

This function converts APassword to UTF-8, attaches ASalt (if specified), then uses the resulting RAW binary string to initialize the key. This function uses MD5 to derive key.

 

You do not need to call this function if you already have RAW binary TEA key (TTEAKey).

 

You do not need to free/release/dispose this key - it does not contain any allocated memory. However, it is strongly recommended to call TEADestroyKey function once you have finished working with key - to erase it with zeros.

 

Overloaded variant lets you initialize key from any binary password. It is usually used in conjunction with asymmetric cipher when generating random passwords for symmetric cipher.

 

Tip

APassword can also be an empty string. Encrypting data with empty password does not mean that data will be unencrypted (e.g. not changed). It will be encrypted, but anyone will be able to decrypt it back, as password is empty. It is strongly recommended not to use empty passwords. There is no need to specify salt for empty password. It is better to use TEADefaultKey function in this case.

 

Important!

Empty salt (zeroed) is not the same as no salt. Use InitSalt function to create new random salt. Once created, salt must be stored with encrypted data and then passed to TEADeriveKey for decryption.

 

Tip

Using salt means that size of encrypted/decrypted data will change - because salt must be stored with encrypted data. If you do not use salt - the data size will not change during encryption/decryption.

 

Note

In cryptography, a salt is random data that is used as an additional input to a one-way function that hashes a password. The primary function of salts is to defend against dictionary attacks versus a list of password hashes and against pre-computed rainbow table attacks.

 

Tiny Encryption Algorithm (TEA) is a block cipher notable for its simplicity of description and implementation, typically a few lines of code. TEA operates on two 32-bit unsigned integers (could be derived from a 64-bit data block) and uses a 128-bit key.

 

Important!

TEA has a few weaknesses. Most notably, it suffers from equivalent keys—each key is equivalent to three others, which means that the effective key size is only 126 bits. As a result, TEA is especially bad as a cryptographic hash function. TEA is also susceptible to a related-key attack which requires 2^23 chosen plaintexts under a related-key pair, with 2^32 time complexity.

 

Examples

 

Code (Delphi)

var

Key: TTEAKey;

EncryptedText: RawByteString;

S: String;

begin

// Create new key from password

Key := TEADeriveKey('password'); // - always the same for the same password

 

// Encrypt some text with the above key

// (meaning "encrypt some text with the above password")

EncryptedText := TEAEncrypt(Key, 'clear text');

 

// Wipe key from memory - do this as soon as possible

TEADestroyKey(Key); // - same as SecureFree(Key);

 

// EncryptedText contains encrypted RAW bytes

// Do not output EncryptedText to any place which expects human-readable text

 

// Debug output

// Encrypted text is RAW bytes, so we need to convert it to something readable

// Encrypted value will be the same for the same original text and password

Edit1.Text := HexEncodeString(EncryptedText);

 

// _____________________________________________

 

// Create new key from password

Key := TEADeriveKey('password'); // - always the same for the same password

 

// Decrypt text back

// Use encrypted RAW binary, not the hex-converted text

S := TEADecrypt(Key, EncryptedText);

 

// Wipe key from memory - do this as soon as possible

TEADestroyKey(Key); // - same as SecureFree(Key);

 

// Wipe also all data

SecureFree(EncryptedText);

 

// Now S = 'clear text'

 

// Call SecureFree for all data once you have finished working with it

SecureFree(S);

end;

 

Code (Delphi)

var

Key: TTEAKey;

Salt: TSalt;

EncryptedText: RawByteString;

S: String;

SaltEncodedLen: Integer;

begin

// Create new (random) salt

Salt := InitSalt;

 

// Create new key from password

// Key will be different each time

// Because salt is different

Key := TEADeriveKey('password', @Salt);

 

// Encrypt some text with the above key

// (meaning "encrypt some text with the above password")

EncryptedText := TEAEncrypt(Key, 'clear text');

 

// Wipe key/salt from memory - do this as soon as possible

TEADestroyKey(Key); // - same as SecureFree(Key);

 

// You must store salt with encrypted data

EncryptedText :=

RAWToString(@Salt, SizeOf(Salt)) +

EncryptedText;

 

// No longer needed, erase it

SecureFree(Salt);

 

// EncryptedText contains encrypted RAW bytes

// Do not output EncryptedText to any place which expects human-readable text

 

// Debug output

// Encrypted text is RAW bytes, so we need to convert it to something readable

// Encrypted value will always be different

Edit1.Text := HexEncodeString(EncryptedText);

 

// _____________________________________________

 

// Read stored salt

SaltEncodedLen := HexCalcEncodedSize(SizeOf(Salt)));

RAWFromString(Copy(EncryptedText, 1, SaltEncodedLen), @Salt);

// Remove salt from EncryptedText

EncryptedText := Copy(EncryptedText, SaltEncodedLen + 1, MaxInt);

 

// Create key from password

// Key will be the same as the one used for encryption above

Key := TEADeriveKey('password', @Salt);

 

// No longer needed, erase it

SecureFree(Salt);

 

// Decrypt text back

S := TEADecrypt(Key, EncryptedText);

 

// Wipe key from memory - do this as soon as possible

TEADestroyKey(Key); // - same as SecureFree(Key);

 

// Wipe also all data

SecureFree(EncryptedText);

 

// Now S = 'clear text'

 

// Call SecureFree for all data once you have finished working with it

SecureFree(S);

end;

 

See also




Send feedback... Build date: 2018-11-26
Last edited: 2018-11-26
PRIVACY STATEMENT
The documentation team uses the feedback submitted to improve the EurekaLog documentation. We do not use your e-mail address for any other purpose. We will remove your e-mail address from our system after the issue you are reporting has been resolved. While we are working to resolve this issue, we may send you an e-mail message to request more information about your feedback. After the issues have been addressed, we may send you an email message to let you know that your feedback has been addressed.


Permanent link to this article: https://www.eurekalog.com/help/eurekalog/topic_function_eencrypt_teaderivekey.php