Working with cryptography in EurekaLog

[DP News-Robot]

EurekaLog is an exception tracer, i.e. a tool that installs hooks and catches exceptions being thrown, allowing you to generate a report on unhandled exceptions. However, it does provide various kinds of additional functionality that you can use in your apps. And one of those features is cryptography functions.

EurekaLog offers 3 units:

1. EEncoding - contains data encoding and transformation functions;
2. EHash - contains hash functions;
3. EEncrypt - contains symmetric and asymmetric encryption functions.

Although the functions from these units will not be able to fully replace a proper cryptographic support library, it may be enough for you in some special cases.

Important Note: please update EurekaLog to the most recent version. Not all features described here are available in previous versions, because some features were published specifically for this article.

Encoding

Before talking about cryptography, you need to take decicion about data representation. For example, suppose you want to get the MD5 hash of the '??????' string (means "Hello" in Russian, reads as "Privet", stress on the second syllable). What exactly are you gonna feed into hash function? $CF$F0$E8$E2$E5$F2 bytes? (which is '??????' encoded via ANSI/Windows-1251) Or $1F$04$40$04$38$04$32$04$35$04$42$04 bytes? ('??????' in Unicode/UTF-16) Or may be $D0$9F$D1$80$D0$B8 bytes ('??????' in UTF-8)? Depending on how you answer this question, you will get different results. For example, the MD5 hash for the '??????' in UTF-16 would be 8EFA2364EE560EE1B862ECC8D430C9AD, for '??????' in ANSI - 43A3F987A7AF93811B7682E43ED0752A, and for '??????' in UTF-8 - 8A669E9418750C81AB90AE159A8EC410.

Questions like this probably don't matter if you use cryptography functions exclusively inside your own apps. But as soon as you need to interact with other code - you immediately would have problems with the exact definition of the data.

Therefore, when you want exact result, you should operate on bytes, not strings. In Delphi, to operate on bytes, you can:

• Use pointer + size of data: (const ABuffer: Pointer; const ABufferSize: Cardinal);
• Use TBytes (array of Byte - dynamic byte array);
• Use RawByteString;
• Use TStream (its sub-classes).

Specifically, EurekaLog functions accepts pointer+size, as well as overloaded option for RawByteString.

For example, if you try to obtain MD5-hash from "just" string '??????' in PHP - you would get 8a669e9418750c81ab90ae159a8ec410 - i.e. MD5-hash of UTF-8 encoded '??????'.

From where you can also conclude that strings in PHP are stored in UTF-8; for comparison: Delphi stores strings as UTF-16 (since Delphi 2009) or ANSI (Delphi 2007 and earlier).

If you want to change the encoding in PHP, you will need to call something like mb_convert_encoding. And if you want to change the encoding in Delphi, you need Delphi encoding functions. Specifically, to convert to/from UTF-8, TEncoding. In Delphi 2009 and up, you can also just declare the string type of the desired encoding and string data conversion will be done automatically when assigned.

The same is true in the opposite direction: the result of calling cryptographic functions is a set of bytes (hash, encrypted data, etc.). If you want to display these bytes to a human, you have to convert it to a string. It can be done, again, in different ways. For example, you can use the built-in function BinToHex or its more convenient equivalents: HexEncodeString/HexEncodeToString from EurekaLog. You can use Base64EncodeString/Base64EncodeToString from EurekaLog. If, suddenly, you need to convert data from/to RawByteString, then EurekaLog has RAWToString/RAWFromString helpers. Also you may want to load/save small data directly to files - there is FileToString/StringToFile for that (from the ECompatibility unit).

Examples of using the mentioned functions can be found below.


Hashing

EurekaLog has functions for calculating the following hashes:

• CRC16
• CRC32
• MD5
• SHA-1
• SHA-256
• SDBM is a good general purpose hash function with uniform distribution, convenient for use as a key/index in a database

All hashing functions have name like HashNameHash (for example, MD5Hash()), returns result of THashNameHash type (for example, TSHA1Hash), and accepts RawByteString on input, as well as pointer+size (overloaded option).

Additionally, EurekaLog has HMAC implementation for some hashes. One way to use HMAC is to authenticate a user by combining a salt and a password to obtain hash via HMAC. HMAC functions have names like HashNameHMAC (for example, MD5HMAC()) and accepts password and salt on input.

Here are some practical examples:

1. Calculate hash of a string:
uses EEncoding, // for HexEncodeToString EHash; // for MD5Hash procedure TForm1.Button1Click(Sender: TObject); var S: String; // Source string UTF8Str: UTF8String; // Byte representation of a string Hash: TMD5Hash; // Result begin // Define source data S := '??????'; // Define exact representation as bytes // We use UTF-8 in this example UTF8Str := UTF8Encode(S); // (you can also just do UTF8Str := S; in Delphi 2009 and up) // Calculate hash from bytes Hash := MD5Hash(UTF8Str); // Show hash to a human Label1.Caption := HexEncodeToString(@Hash, SizeOf(Hash)); // Should display '8A669E9418750C81AB90AE159A8EC410' end;
2. Calculate hash of a file:
uses EEncoding, // for HexEncodeToString EHash, // for SHA256Hash ECompatibility; // for FileToString procedure TForm1.Button1Click(Sender: TObject); var Content: RawByteString; // File's bytes Hash: TSHA256Hash; // Result begin // Loads entire file into memory Content := FileToString(ParamStr(0)); // Content will be something like 'MZP'#0#2#0#0#0... // Calculate hash from bytes Hash := SHA256Hash(Content); Finalize(Content); // optional // Show hash to a human Label1.Caption := HexEncodeToString(@Hash, SizeOf(Hash)); // Should be something like 'FCF52FDC753E3797FE5EE4B5A7680E656D044D6BF7D97C408 F0F7874492E43C2' end;
3. Calculate hash of a string in an arbitrary encoding:
uses EEncoding, // for HexEncodeToString (also for TEncoding for older Delphi) EHash; // for CRC32Hash procedure TForm21.Button1Click(Sender: TObject); var S: String; // Source string Encoding: TEncoding; // Encoding to encode the string Content: TBytes; // String's bytes Hash: TCRC32Hash; // Result begin // Define source data S := '??????'; // Define the encoding Encoding := TEncoding.GetEncoding(866); // You can also do: // Encoding := TEncoding.UTF8; // Encoding := TEncoding.Unicode; // Encoding := TEncoding.ANSI; try // Convert string (characters) to bytes Content := Encoding.GetBytes(S); finally FreeAndNil(Encoding); end; // Calculate hash from bytes Hash := CRC32Hash(Pointer(Content), Length(Content)); Finalize(Content); // optional // Show hash to a human Label1.Caption := HexEncodeToString(@Hash, SizeOf(Hash)); // Should be '6DB3A7B9' // You can also do IntToStr(Hash) - which will be 3114775405 end;
4. Check hash in PHP:
uses EEncoding, // for HexEncodeToString EHash, // for MD5Hash ECore; // for ShellExec procedure TForm1.Button1Click(Sender: TObject); var S: String; // Source string UTF8Str: UTF8String; // String's bytes Hash: TMD5Hash; // Hash (bytes) HashStr: String; // Hash (text) begin // Define source data S := '??????'; // Define exact representation as bytes // We use UTF-8 in this example UTF8Str := UTF8Encode(S); // (you can also just do UTF8Str := S; in Delphi 2009 and up) // Calculate hash from bytes Hash := MD5Hash(UTF8Str); // Convert bytes to text HashStr := HexEncodeToString(@Hash, SizeOf(Hash)); // Will be '8A669E9418750C81AB90AE159A8EC410' // Pass hash as text into PHP script ShellExec(Format('http://localhost/test.php?hash=%s', [HashStr])); end;