GAMBAS BOOK 3.19.1

The following applications of the gb.openssl component are presented:

• Generate and display overview of cipher algorithms supported on the system.
• Create and display an overview of the digest algorithms supported on the system.
• Determination of hash values of texts (class Digest)
• Determine hash values of texts (class HMac)
• Determination of the key and init vector length of selected cipher algorithms.
• Encryption of texts
• Decryption of encrypted texts
• Determination of a checksum for a freely selectable file
• Project with all classes described in → Chapter 28.3.0

In the Cipher.List property, an array is returned that contains all the cipher algorithms supported by the OpenSSL library on the system. With this source code snippet:

Dim sName As String
For Each sName In Cipher.List.Sort()
  Print sName; " | ";
Next

the following algorithm names (sorted) were output to the IDE console:

AES-128-CBC | AES-128-CBC | AES-128-CBC-HMAC-SHA1 | AES-128-CBC-HMAC-SHA1 | AES-128-CFB |
AES-128-CFB | AES-128-CFB1 | AES-128-CFB1 | AES-128-CFB8 | AES-128-CFB8 | AES-128-CTR | ...

The mapping from an algorithm name to the algorithm used is handled internally by OpenSSL. The gb.openssl component has no influence on this. Note that the list on your system may contain other elements.

In the property Digest.List a string array is returned that contains all hash algorithms supported by the OpenSSL library on the system. The following source code snippet was used to output the sorted list of algorithm names in the IDE console:

Dim sName As String
For Each sName In Digest.List.Sort()
  Print sName; " | ";
Next

DSA | DSA-SHA | MD4 | MD5 | RIPEMD160 | SHA |
SHA1 ... | SHA512 | ecdsa-with-SHA1 | whirlpool

The following short text is used for all examples:

sOriginalText = "RSA ist ein asymmetrisches kryptographisches Verfahren."

Using the “SHA256” algorithm resulted in.

Print Digest["SHA256"](sOriginalText)
Print Base64$(Digest["SHA256"](sOriginalText))			*
Print Base64$(Digest["SHA256"].Hash(sOriginalText))		**

a hash value (message digest or digest) for the text above in raw binary format and below in (readable) Base64 format:

���a���R^X5����6���~������^T�[�r�
vrKYYbfp41IYNeDd2to2s6DIfpObn6SuhBSRW95y8wo=

In both cases * and ** the same function is called internally. The syntax is absolutely equivalent.

The following source code excerpt was used to determine the checksum (Message Authentication Code (MAC)) for the sample text:

Dim sKey, sData, iMethod As String

sKey = "a1Bc+d2D*"
sData = sOriginalText
iMethod = HMac.RipeMD160 ' Constant of the class HMac (Typ Integer)

Print Base64$(HMac(sKey, sData, iMethod))

A readable MAC in Base64 format was displayed in the console:

1IK0gQGM976LoRt0L7BME2ipdLU=

The exact knowledge of the key length and the length of the InitVectors for selected cipher algorithms is a necessary prerequisite for both encryption and decryption with the Encrypt() and Decrypt() methods.

The commented source code excerpt for determining and displaying the key length as well as the length of the InitVectors is taken from a project for demonstrating the work with the classes of the component gb.openssl. The project archive can be found in the download area.

[1] Public aCipherList As String[]
[2] Public Sub btnShowCipherKeyAndIVLength_Click()
[3]    Dim i As Integer
[4]
[5]    txaText.Clear
[6]    Wait
[7]    If Not aCipherList Then
[8]       aCipherList = RemoveMultiple(Cipher.List)
[9]    Endif
[10]    For i = 0 To aCipherList.Max
[11]      txaText.Text &= aCipherList[i] & " : IvLength = " & Cipher[aCipherList[i]].IvLength
[12]      txaText.Text &= "  |  KeyLength = " & Cipher[aCipherList[i]].KeyLength & gb.NewLine
[13]    Next
[14]  End ' btnShowCipherKeyAndIVLength_Click()

Comment:

• In line 8, the aCipherList array - if it does not exist - is filled with the elements of Cipher.List (data type string array) after removing possible duplicates. As of Gambas revision 6684, the lists are sorted and output without redundancy. The RemoveMultiple() function can then be omitted.
• In a TextArea, the cipher algorithms available on the system are displayed with the corresponding lengths for InitVector (IvLength) and Key (KeyLength) [lines 11 to 14].

Here you can see an excerpt from the display as it was seen by the author on his system:

AES-256-CTR   : IvLength = 16  |  KeyLength = 32
AES-256-ECB   : IvLength = 0   |  KeyLength = 32
AES-256-XTS   : IvLength = 16  |  KeyLength = 64
BF-CBC : IvLength = 8  |  KeyLength = 16
BF-CFB : IvLength = 8  |  KeyLength = 16
BF-ECB : IvLength = 0  |  KeyLength = 16
BF-OFB : IvLength = 8  |  KeyLength = 16
CAMELLIA-128-CBC : IvLength = 16  |  KeyLength = 16

The Cipher class can be used to encrypt texts using two different approaches:

(A1) Use of password and optional salt (method: EncryptSalted()).
(A2) Use of a key and an initialisation vector (method: Encrypt())

• For both methods, you must choose to use a cipher algorithm that is available on the system.
• You can freely define the password and the value of Salt in approach A1. However, the salt must have a length of exactly 8 bytes. Otherwise, this length is forced by appending zero bytes or by truncation. If no salt is passed, a random sequence is used.

• For the key and the initialisation vector in approach A2, you must observe the lengths prescribed for the selected cipher algorithm - but are otherwise free to choose the characters used. The initialisation vector has a significant influence on the quality of the encryption.

Approach A1 - Use of password and optional salt

[1] Public Sub btnCipherSalt_TextToFile_Click()
[2]   Dim sPlainText, sCipherText, sPassword, sSalt As String
[3]
[4]   Reset()
[5]   sAlgorithmus = "aes-256-cfb" ' Determination of the cipher algorithm
[6]   sPlainText = sOriginalText
[7]   sPassword = GetPassword() ' Password from a password form
[8]   sSalt = "123abc#*"    ' Freely defined string (8Byte)
[9]
[10]   sCipherText = Cipher[sAlgorithmus].EncryptSalted(sPlainText, sPassword, sSalt)
[11]
[12]   File.Save(csPath, sCipherText)
[13]
[14]   ' Print Cipher["aes-256-cfb"].EncryptSalted(sPlainText, sPassword, sSalt)
[15]   ' Print Base64(Cipher["aes-256-cfb"].EncryptSalted(sPlainText, sPassword, sSalt))
[16]
[17] End ' btnCipherSalt_TextToFile_Click()

Comment:

• In line 10, the plaintext is ciphered specifying the EncryptSalted() method of the Cipher class as well as the cipher algorithm, the password and the value of Salt.
• The ciphertext is stored in a file [line 12] whose path was stored in the variable csPath.
• Lines 14 and 15 were used for control purposes when testing the project.
• Under this link: http://de.wikipedia.org/wiki/Salt_(cryptology) you will find a good description on Salt.

The necessary password is entered interactively via a password form:

Figure 28.3.1.6.1: Password Dialogue

Approach A2 - Use of a key and an initialisation vector

Encrypting a text using approach A2 requires more effort compared to A1, because after deciding on the encryption algorithm you have to take care of determining the length of the key belonging to this algorithm and the length of the corresponding initialisation vector (→ chapter 28.3.1.5).Furthermore, you have to work explicitly with the three properties (Cipher, Key and InitVector) class CipherText, which is not necessary with approach A1!

[1] Public Sub btnCipherKIV_TextToFile_Click()
[2]   Dim hCipherText As CipherText
[3]   Dim sPlain, sKey, sInitVector, sAlgorithmus As String
[4]   Dim iInitVector, iKey As Integer
[5]
[6]   Reset()
[7]   sAlgorithmus = "AES-128-XTS" ' Cipher-Algorithmus
[8] ' iInitVector = Cipher[sAlgorithmus].IvLength
[9] ' iKey = Cipher[sAlgorithmus].KeyLength
[10] ' Print iInitVector, iKey
[11]
[12]   sPlain = sOriginalText ' Plain text
[13]   sInitVector = "0123456789vector" ' Length = 16 for "AES-128-XTS"
[14]   sKey = "0123456789abcdef0123456789abcdef" ' Length = 32 for "AES-128-XTS"
[15]
[16]   hCipherText = Cipher[sAlgorithmus].Encrypt(sPlain, sKey, sInitVector)
[17]   File.Save(ckivPath, hCipherText.Cipher) ' Saving the (binary) ciphertext in a file
[18] txaText.Text = "SECRET TEXT IN BASE64 FORMAT =\n" & Base64$(hCipherText.Cipher) ' Readable ciphertext
[19]
[20] End ' btnCipherKIV_TextToFile_Click()

Comment:

• Note the data type 'CipherText' of the variable hCipherText!
• Line 7 specifies the cipher algorithm, for which you need to know the corresponding lengths of InitVector and key.
• Line 13 shows how to define an InitVector of length 16.
• Of double length is the key, which is defined in line 14.
• In line 16, a CipherText object is generated as the return value of Cipher[…].Encrypt(..).
• Only the value of the property hCipherText.Cipher in line 17 is stored from this object, because only this contains the encrypted ciphertext. The file path is stored in the variable ckivPath.
• In a TextArea you can view the ciphertext in Base64 format in readable form.

The decryption of texts that have been stored as ciphertext in a file is performed by the two methods Cipher[…].Decrypt(..) and Cipher[…].DecryptSalted(..). Decryption also follows two different approaches:

(B1) Use password
(B2) Use key and initialisation vector.

Approach B1

It is assumed that a file with a ciphertext is present and the file path as well as the necessary password and the used cipher algorithm are known.

[1] Public Sub btnCipherSalt_FileToText_Click()
[2]   Dim sPassword, sPlainText, sAlgorithmus As String
[3]
[4]   If Not Exist(csPath) Then Return
[5]   txaText.Clear
[6]   sAlgorithmus = "aes-256-cfb"
[7]   sPassword = GetPassword() ' Password from a password form like A1
[8]
[9]   sPlainText = Cipher[sAlgorithmus].DecryptSalted(File.Load(csPath), sPassword)
[10]   txaText.Text = sPlainText ' Display plain text
[11]
[12] End ' btnCipherSalt_FileToText_Click()

Comment:

• The cipher algorithm used must be the same as that used for encryption.
• The required password [line 7] is read in via a password form.
• The method Cipher[algorithm].DecryptSalted(secrettext, password) returns a string as function value that can be processed or displayed immediately.

Approach B2

For decrypting via the method Cipher[..].Decrypt(..) similar considerations apply to the algorithm, the InitVector and the key. It is required that a file with a ciphertext is present and that the file path as well as the cipher algorithm used and the InitVector and key to be used are known.

[1] Public Sub btnCipherKIV_FileToText_Click()
[2]   Dim hCipherText As CipherText
[3]   Dim sCipher, sKey, sInitVector As String
[4]
[5]   If Not Exist(ckivPath) Then Return
[6]   txaText.Clear
[7]   Wait 1
[8]
[9]   sCipher = File.Load(ckivPath)
[10]   sKey = "0123456789abcdef0123456789abcdef" ' Length = 32
[11]   sInitVector = "0123456789vector" ' Length = 16
[12]
[13]   hCipherText = New CipherText(sCipher, sKey, sInitVector)
[14]   txaText.Text = Cipher["AES-128-XTS"].Decrypt(hCipherText)
[15]
[16] End ' btnCipherKIV_FileToText_Click()

Comment:

• The variable sCipher holds the ciphertext that comes from the ciphertext file.
• In line 13, a CipherText object is generated, which is passed the ciphertext, the key and the InitVector as ininialisation values.
• In the new CipherText object, all data needed for decryption are bundled in one object.
• The method Cipher[algorithm].Decrypt(ciphertext) returns as function value in line 14 a string with the plaintext, which is immediately displayed in a TextArea.

Notes:

For a demonstration of the class Cipher it may be uncritical in connection with the two methods Cipher[…].Encrypt(..) and Cipher[…].Decrypt(..) to store the InitVector and the key in the source code.In general, the recommendation must be taken seriously not to store the InitVector and the key in the source code in practical use, but to read them in interactively in a suitable way at runtime!

The source code for the determination of the MD5 checksum for a freely selectable file contains

• a dialogue for file selection,
• the calculation of the checksum according to a predefined hash algorithm and
• the display of the checksum in three different formats → Figure 28.3.1.9.1.

[1] Public Sub btnDigestFromFile_Click()
[2]   Dim sPath As String
[3]   Dim vRawData As Variant
[4]
[5]   Dialog.Title = "Select a file!"
[6]   Dialog.Path = sFilePath
[7]   If Dialog.OpenFile() Then Return
[8]
[9]   sPath = Dialog.Path
[10]
[11]   vRawData = Digest["MD5"].Hash(File.Load(sPath))
[12]
[13]   txaText.Clear
[14]   txaText.Text = "MD5-Checksum for the file '" & File.Name(Dialog.Path) & "'\n\n"
[15]   txaText.Text &= "Base64-Format:" & gb.NewLine
[16]   txaText.Text &= Base64$(vRawData) & gb.NewLine & gb.NewLine
[17]   txaText.Text &= "Format: hexadecimal:" & gb.NewLine
[18]   txaText.Text &= StringToHex(vRawData) & gb.NewLine & gb.NewLine ' Function StringToHex(..)
[19]   txaText.Text &= "Format: binär:" & gb.NewLine
[20]   txaText.Text &= vRawData
[21]
[22] End ' btnDigestFromFile_Click()

===== 28.3.1.9 Project demonstrating the gb.openssl ===== component.

In the project, all classes of the component gb.openssl as well as their methods and properties are used. Only the GUI is presented here:

Figure 28.3.1.9.1: Project GUI - MD5 checksum

The well-documented project archive can be found in the download section.