Specifying the algorithm, mode and padding for generic block cipher functions

The generic block cipher functions CIPHER_Byte, CIPHER_Hex and CIPHER_File allow the block cipher algorithm and mode to specified either by a szAlgAndMode string or by using the nOptions flags, but not both. The algorithm-and-mode parameter string combines the name of the block cipher algorithm and the mode, e.g. "tdea/ecb". The output from the CIPHER_Byte and CIPHER_Hex functions is always the same length as the input, and any padding required for ECB and CBC modes must be dealt with separately using the PAD_* functions.

The functions CIPHER_EncryptBytes and CIPHER_DecryptBytes use the string parameter szAlgModePad to specify the method of padding as well, e.g. "aes128/cbc/pkcs5padding". With CIPHER_EncryptBytes the output will be longer than the input if padding is to be added. The user must query the function first to find the correct padded length and then allocate a buffer before encrypting.

Valid algorithm names are:

We have used "TDEA" consistently in CryptoSys products to refer to the Triple DES algorithm (as in its official name "Triple Data Encryption Algorithm"). In this case, you can use any one of "tdea", "3des" or "desede3" (or "desede"). These are all equivalent and all yield identical results.

Valid mode names are:

† Only 64-bit CFB mode is provided for Triple DES and only 128-bit CFB mode is provided for AES.

‡ GCM is only available for AES, and only for some functions.

Some examples of valid string values for the szAlgAndMode parameter are:

Punctuation and space characters and upper- and lower-case are ignored in the szAlgAndMode string, so "tdea-cbc", "TDeA---cBc", "tdea cbc", and "TDEACBC" are equivalent (as indeed is "t*D$e^A c@b!C!!")

It is an error to use both the szAlgAndMode and nOptions parameters to specify the algorithm and mode. The algorithm must be explicitly specified. There is no default algorithm. The default cipher mode is ECB mode, which is not recommended because of security issues. It is recommended to use either CBC or CTR mode with a IV value that is unique each time it is used with a given key.

Padding

For the functions CIPHER_EncryptBytes, CIPHER_DecryptBytes, CIPHER_EncryptHex, CIPHER_DecryptHex, CIPHER_FileEncrypt and CIPHER_FileDecrypt, you can specify padding as well as the algorithm and mode. The given padding will be added before encryption and removed after decryption according to the relevant rules. If the padding is not given, default padding will be assumed which depends on the cipher mode.

Valid padding names are:

So, for example, both nopad and nopadding are accepted, and so are pkcs5 and pkcs5padding. Remember that punctuation characters and case in the szAlgModePad string are ignored. The keywords must be in the correct order algorithm-mode-padding. Some valid examples:

[Contents] [Index]