Function TEADeriveKey

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;

Warning

TEADeriveKey and TEADeriveKeyHMAC use different algorithms to derive the key. E.g. key created by the TEADeriveKey will be different from the key created by the TEADeriveKeyHMAC function. In other words, if you use some function on sending side - then you must use the same function on receiving side. If you do not have compatibility requirements with external code - we recommend to use TEADeriveKeyHMAC function.

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.

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.

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;