CryptoSys Home > PKI > Changes in CryptoSys PKI Pro v11.1

Changes in CryptoSys PKI Pro v11.1

Some notes on the changes in CryptoSys PKI Pro v11.1 released 25 March 2016.

4 June 2016: An improvement in CryptoSys PKI Pro v11.0 we forgot to mention.

Why yet another "encrypt-bytes" function?

The new functions CIPHER_EncryptBytes2 and CIPHER_DecryptBytes2 are now the recommended way to do all symmetrical encryption.

For now very-old historical reasons, the other encrypt-bytes functions all assumed that the user would pass byte arrays of the correct length for the input, key and IV. The new "Bytes2" versions do explicit checks for the lengths of all byte arrays. This is especially convenient (and safer) when used internally in the interfaces for C# and Python (did we mention we've just released a Python interface?).

We were going to use the name CIPHER_EncryptBytesEx but then realised how it looked in all lower-case.

So what's the difference between them?

TDEA_BytesMode: TDEA_BytesMode(lpOutput, lpInput, nDataLen, lpKey, fEncrypt, szMode, lpIV)
Original. Triple DES only. The output is always the same length as the input (so same nDataLen for both). Expects input for ECB and CBC mode to be an exact multiple of the block length. No padding is added or removed (user to do separately with a Padding function). Returns 0 on success. No checks on length of key or IV. @deprecated.
CIPHER_Bytes: CIPHER_Bytes(fEncrypt, lpOutput, lpInput, nDataLen, lpKey, lpIV, szAlgAndMode, nOptions)
Added v3.2. Same as TDEA_BytesMode but with option to specify encryption algorithm (Tdea/Aes). No padding. Returns 0 on success. No checks on length of key or IV. @deprecated.
CIPHER_EncryptBytesPad: CIPHER_EncryptBytesPad(lpOutput, nOutBytes, lpInput, nInputLen, lpKey, lpIV, szAlgModePad, nOptions)
Added v3.10. Adds padding when encrypting and removes when decrypting if specified. User has to compute nOutBytes. Returns length of output or a negative error code. No checks on length of key or IV. @deprecated.
CIPHER_EncryptBytes2: CIPHER_EncryptBytes2(lpOutput, nOutBytes, lpInput, nInputLen, lpKey, nKeylen, lpV, nIvLen, szAlgModePad, nOptions)
Added v11.1. The same as CIPHER_EncryptBytesPad but with explicit checks on length of key and IV.

To get the same behaviour as CIPHER_Bytes with no padding added or removed in ECB/CBC mode, use the "NoPad" option. All the following statements do exactly the same.

Dim key() As Byte
Dim iv() As Byte
Dim pt() As Byte
Dim ct() As Byte
Dim ptlen As Long
Dim ctlen As Long
Dim keylen As Long
Dim ivlen As Long
Dim r As Long
' /SNIP/ See full code below

r = TDEA_BytesMode(ct(0), pt(0), ptlen, key(0), ENCRYPT, "CBC", iv(0))
Debug.Assert(r = 0)
r = CIPHER_Bytes(ENCRYPT, ct(0), pt(0), ptlen, key(0), iv(0), "tdea/cbc", 0)
Debug.Assert(r = 0)
ctlen = CIPHER_EncryptBytesPad(ct(0), ctlen, pt(0), ptlen, key(0), iv(0), "tdea/cbc/nopad", 0)
Debug.Assert(ctlen > 0)
ctlen = CIPHER_EncryptBytes2(ct(0), ctlen, pt(0), ptlen, key(0), keylen, iv(0), ivlen, "tdea/cbc/nopad", 0)
Debug.Assert(ctlen > 0)

So it's the same for encrypting a file, right?

Yes. The new functions CIPHER_FileEncrypt and CIPHER_FileDecrypt are now the recommended functions to perform symmetrical encryption on files. They have explicit checks on the lengths of the key and IV, which is a good thing.

But wait, there's more! These two new functions also allow you to use different padding schemes in ECB and CBC mode (the deprecated functions always used PKCS5Padding). Plus they allow you prepend or prefix the IV at the beginning of the output file so there is no need to transmit it separately.

All the following statements do exactly the same, encrypting the file using Triple DES in CBC mode with (default) PKCS5Padding.

r = TDEA_File(fileout, filein, key(0), ENCRYPT, "CBC", iv(0))
r = CIPHER_File(ENCRYPT, fileout, filein, key(0), iv(0), "tdea/cbc", 0)
r = CIPHER_FileEncrypt(fileout, filein, key(0), keylen, iv(0), ivlen, "tdea/cbc", 0)

Should you want to encrypt using aes192/cbc/OneAndZeroes with the IV prefixed to the output, you can do the following (making sure you pass the correct key and IV lengths)

r = CIPHER_FileEncrypt(fileout, filein, key(0), keylen, iv(0), ivlen, "aes192/cbc/OneAndZeroes", PKI_IV_PREFIX)

Does this affect me when I use C#?

These safer encryption functions are already substituted in the C# code for the Cipher Class. The old Tdea Class methods are now deprecated.

Test code in VBA/VB6

Test code: test_cipher_comp.bas. Download source (zipped 1.4 kB). Expected output in the immediate window:

test_CIPHER_comp
ptlen=32
CT=204011F986E35647199E47AF391620C5BB9A5BCFC86DB0BB2C577D7322162509
CT=204011F986E35647199E47AF391620C5BB9A5BCFC86DB0BB2C577D7322162509
CT=204011F986E35647199E47AF391620C5BB9A5BCFC86DB0BB2C577D7322162509
CT=204011F986E35647199E47AF391620C5BB9A5BCFC86DB0BB2C577D7322162509

test_CIPHER_File_comp
PT=616263
CT=793DEC494A1FAA0A
CT=793DEC494A1FAA0A
CT=793DEC494A1FAA0A
CT=FEDCBA9876543210FEDCBA9876543210FC81FCF7AB8D89C5196D5393FB00D624

[Go to top]

Contact

For more information, or to comment on this page, please send us a message.

This page last updated 15 August 2025

[Go to top]