CIPHER_EncryptHex

Encrypt data using the specified block cipher algorithm, mode and padding. The input data, key and initialization vector are all represented as hexadecimal strings.

VBA/VB6 Syntax

nRet = CIPHER_EncryptHex(strOutput, nOutChars, strInputHex, strKeyHex, strIvHex, strAlgModePad, nOptions)

C/C++ Syntax

Parameters

szOutput

[out] string buffer of sufficient length to receive the output.

nOutChars

[in] maximum number of characters to be received.

szInputHex

[in] the input data in hex format.

szKeyHex

[in] the key in hex format.

szIvHex

[in] the initialization vector (IV) in hex format, ignored for ECB mode (use "").

szAlgModePad

[in] string specifying the block cipher algorithm, mode and padding (see Specifying the algorithm, mode and padding for generic block cipher functions).

nOptions

[in] option flags:
Zero (0) for default options. Optionally add:
PKI_IV_PREFIX to prepend the IV before the ciphertext in the output (ignored for ECB mode).

Returns (VBA/C)

If successful, the return value is the number of characters in or required in the output; otherwise it returns a nonzero error code.

VBA Wrapper Syntax

.NET Equivalent

Cipher.Encrypt Method (String, String, String, CipherAlgorithm, Mode, Padding, Cipher.Opts)

Python Equivalent

Remarks

For the "raw" VBA/C function, the user must allocate an output string buffer szOutput of the required length. Specify a zero nOutChars or an empty string for szOutput to find the required length. ANSI C users must add one to this value when allocating memory.

This is the equivalent of CIPHER_EncryptBytes with all parameters passed as hex-encoded strings instead of byte arrays. It is similar to the CIPHER_Hex function except this accepts variable-length input and adds padding if required, as well as the option to prepend the IV to the ciphertext.

Padding is added as specified to the input before encryption. The output will always be at least as long as the input, or longer if padding or a prefixed IV is to be added.

The algorithm/mode/padding must be specified using either the szAlgModePad string or nOptions parameter, but not both (see Specifying the algorithm, mode and padding for generic block cipher functions).

It is an error (BAD_PARAM_ERROR) to pass the empty string "" as input in szInputHex. The output buffer strOutput should not be the same as the input strInputHex.

Use the PKI_IV_PREFIX option to prepend the IV before the ciphertext in the output. This will add the IV before the ciphertext in the form IV||CT. This is the scheme used with block ciphers in XML encryption (see section 5.2 of [XMLENC]) where they use the phrase "The resulting cipher text is prefixed by the IV."

Example (VBA core function)

Dim strKey As String
Dim strIV As String
Dim strPlain As String
Dim strCipher As String
Dim strOK As String
Dim strAlg As String
Dim nChars As Long

strAlg = "Aes128/CBC/OneAndZeroes"
Debug.Print strAlg
strKey = "0123456789ABCDEFF0E1D2C3B4A59687"
strIV = "FEDCBA9876543210FEDCBA9876543210"
Debug.Print "KY=" & strKey
Debug.Print "IV=" & strIV
' "Now is the time for all good men to"
strPlain = "4E6F77206973207468652074696D6520666F7220616C6C20676F6F64206D656E20746F"
Debug.Print "PT=" & strPlain
Debug.Print "PT='" & cnvStringFromHexStr(strPlain) & "'"
' Correct result
strOK = "C3153108A8DD340C0BCB1DFE8D25D2320EE0E66BD2BB4A313FB75C5638E9E1771D4CDA34FBFB7E74B321F9A2CF4EA61B"

' 1. Find out how long an output buffer we need
nChars = CIPHER_EncryptHex(vbNullString, 0, strPlain, strKey, strIV, strAlg, 0)
Debug.Print "CIPHER_EncryptHex returns " & nChars
Debug.Assert nChars > 0
' 2. Allocate the buffer
strCipher = String(nChars, " ")
' 3. Encrypt to output buffer
nChars = CIPHER_EncryptHex(strCipher, nChars, strPlain, strKey, strIV, strAlg, 0)

Debug.Print "CT=" & strCipher
Debug.Print "OK=" & strOK

' PART 2 - prefix the IV in the output
nChars = CIPHER_EncryptHex(vbNullString, 0, strPlain, strKey, strIV, strAlg, PKI_IV_PREFIX)
Debug.Print "CIPHER_EncryptHex(PKI_IV_PREFIX) returns " & nChars
Debug.Assert nChars > 0
strCipher = String(nChars, " ")
nChars = CIPHER_EncryptHex(strCipher, nChars, strPlain, strKey, strIV, strAlg, PKI_IV_PREFIX)

Debug.Print "IV||CT=" & strCipher

This should result in output as follows:

Aes128/CBC/OneAndZeroes
KY=0123456789ABCDEFF0E1D2C3B4A59687
IV=FEDCBA9876543210FEDCBA9876543210
PT=4E6F77206973207468652074696D6520666F7220616C6C20676F6F64206D656E20746F
PT='Now is the time for all good men to'
CIPHER_EncryptHex returns 96
CT=C3153108A8DD340C0BCB1DFE8D25D2320EE0E66BD2BB4A313FB75C5638E9E1771D4CDA34FBFB7E74B321F9A2CF4EA61B
OK=C3153108A8DD340C0BCB1DFE8D25D2320EE0E66BD2BB4A313FB75C5638E9E1771D4CDA34FBFB7E74B321F9A2CF4EA61B
CIPHER_EncryptHex(PKI_IV_PREFIX) returns 128
IV||CT=FEDCBA9876543210FEDCBA9876543210C3153108A8DD340C0BCB1DFE8D25D2320EE0E66BD2BB4A313FB75C5638E9E1771D4CDA34FBFB7E74B321F9A2CF4EA61B

Example (VBA wrapper function)

Dim strKeyHex As String
Dim strIvHex As String
Dim strPlainHex As String
Dim strCipherHex As String
strKeyHex = "0123456789ABCDEFF0E1D2C3B4A59687"
strIvHex = "FEDCBA9876543210FEDCBA9876543210"
strPlainHex = "4E6F77206973207468652074696D6520666F7220616C6C20676F6F64206D656E20746F"

' Get encrypted output directly in hex
strCipherHex = cipherEncryptHex(strPlainHex, strKeyHex, strIvHex, "Aes128/CBC/OneAndZeroes", 0)
Debug.Print strCipherHex

' Same again with bytes
Dim lpKey() As Byte
Dim lpIV() As Byte
Dim lpPlain() As Byte
Dim lpCipher() As Byte
lpPlain = StrConv("Now is the time for all good men to", vbFromUnicode)
lpKey = cnvBytesFromHexStr("0123456789ABCDEFF0E1D2C3B4A59687")
lpIV = cnvBytesFromHexStr("FEDCBA9876543210FEDCBA9876543210")
' Get encrypted output
lpCipher = cipherEncryptBytes(lpPlain, lpKey, lpIV, "Aes128/CBC/OneAndZeroes", 0)
Debug.Print cnvHexStrFromBytes(lpCipher)

' Same again using ECB mode with default PKCS#5 padding
' To pass an empty byte array for IV, create a dummy zero-length array
Dim lpDummy() As Byte
lpCipher = cipherEncryptBytes(lpPlain, lpKey, lpDummy, "Aes128/ECB", 0)
Debug.Print cnvHexStrFromBytes(lpCipher)

' The old way - we need all the byte array lengths
Dim nBytes As Long
Dim nDataLen As Long
Dim nKeyLen As Long
Dim nIVLen As Long
nDataLen = cnvBytesLen(lpPlain)
nKeyLen = cnvBytesLen(lpKey)
nIVLen = cnvBytesLen(lpIV)
nBytes = CIPHER_EncryptBytes(ByVal 0&, 0, lpPlain(0), nDataLen, lpKey(0), nKeyLen, lpIV(0), nIVLen, "Aes128/CBC/OneAndZeroes", 0)
Debug.Assert nBytes > 0
ReDim lpCipher(nBytes - 1)
nBytes = CIPHER_EncryptBytes(lpCipher(0), nBytes, lpPlain(0), nDataLen, lpKey(0), nKeyLen, lpIV(0), nIVLen, "Aes128/CBC/OneAndZeroes", 0)
Debug.Print cnvHexStrFromBytes(lpCipher)

' Same again with hex using ECB mode with default PKCS#5 padding
' To pass a "null" IV in hex, just use the empty string
strCipherHex = cipherEncryptHex(strPlainHex, strKeyHex, "", "Aes128/ECB", 0)
Debug.Print strCipherHex

' Or vbNullString
strCipherHex = cipherEncryptHex(strPlainHex, strKeyHex, vbNullString, "Aes128/ECB", 0)
Debug.Print strCipherHex

See Also

CIPHER_DecryptHex

[Contents] [Index]