The generic block cipher functions allow the block cipher algorithm and
mode to be 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, for example "tdea-cbc"
or "aes128-ctr". Only Triple DES (TDEA) and the three AES algorithms (AES-128, AES-192 and AES-256) are provided with
the generic cipher functions.
Valid algorithm names are:
| Value | Algorithm | Option |
|---|---|---|
| tdea | Triple DES, a.k.a. 3DES, des-ede3 | API_BC_TDEA |
| aes128 | AES-128 | API_BC_AES128 |
| aes192 | AES-192 | API_BC_AES192 |
| aes256 | AES-256 | API_BC_AES256 |
Valid mode names are:
| Value | Mode | Option |
|---|---|---|
| ecb | Electronic Code Book mode (default) | API_MODE_ECB |
| cbc | Cipher Block Chaining mode | API_MODE_CBC |
| ofb | Output Feedback mode | API_MODE_OFB |
| cfb | 64-bit Cipher Feedback mode | API_MODE_CFB |
| ctr | Counter mode | API_MODE_CTR |
Some examples of valid string values for the szAlgAndMode parameter are:
| strAlgAndMode | Description | Alternative Option value |
|---|---|---|
| tdea-cbc | Triple DES in CBC mode | API_BC_TDEA+API_MODE_CBC |
| tdea-ecb | Triple DES in ECB mode | API_BC_TDEA+API_MODE_ECB |
| tdea | ditto (ECB is default mode) | API_BC_TDEA |
| aes128/cbc | AES-128 in CBC mode | API_BC_AES128+API_MODE_CBC |
| aes256:ctr | AES-256 in Counter mode | API_BC_AES2568+API_MODE_CTR |
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!!").
You can use the synonyms "3des", "des-ede" or "des-ede3" in place of "tdea".
It is an error to use both the szAlgAndMode and nOptions parameters to specify the algorithm and mode. The cipher 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 an IV value that is unique each time it is used with a given key. Even better, use Authenticated Encryption .
For the functions
CIPHER_EncryptBytes,
CIPHER_DecryptBytes,
CIPHER_EncryptHex, and
CIPHER_DecryptHex,
you can specify padding as well as the algorithm and mode.
If the padding is not given, default padding will be assumed which depends on the cipher mode.
Valid padding names are:
| Value | Padding | Option |
|---|---|---|
| nopad[ding] | No padding is added | API_PAD_NOPAD |
| pkcs5[padding] | The padding scheme described in PKCS#5 [PKCS5] | API_PAD_PKCS5 |
| oneandzeroes[padding] | Pads with 0x80 followed by as many zero bytes necessary to fill the block | API_PAD_1ZERO |
| ansix923[padding] | The padding scheme described in ANSI X9.23 [X9-23] | API_PAD_AX923 |
| w3c[padding] | The padding scheme described in W3C Recommendation for XML encryption [XMLENC] | API_PAD_W3C |
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:
| szAlgModePad | Alternative Option value |
|---|---|
| tdea/cbc/pkcs5 | API_BC_TDEA+API_MODE_CBC+API_PAD_PKCS5 |
| tdea/cbc/pkcs5padding | API_BC_TDEA+API_MODE_CBC+API_PAD_PKCS5 |
| tdeacbcpkcs5 | API_BC_TDEA+API_MODE_CBC+API_PAD_PKCS5 |
| aes128-ecb-oneandzeroes | API_BC_AES128+API_MODE_ECB+API_PAD_1ZERO |