CIPHER_DecryptHex

CryptoSys PKI Pro Manual

CIPHER_DecryptHex

Decrypt 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


Public Declare Function CIPHER_DecryptHex Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strInputHex As String, ByVal strKeyHex As String, ByVal strIvHex As String, ByVal strAlgModePad As String, ByVal nOptions As Long) As Long

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

C/C++ Syntax


long __stdcall CIPHER_DecryptHex(char *szOutput, long nOutChars, const char *szInputHex, const char *szKeyHex, const char *szIvHex, const char *szAlgModePad, long nOptions);

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 or if PKI_IV_PREFIX is used (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 expect the IV to be prepended before the ciphertext in the input (not applicable 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

Public Function cipherDecryptHex (szInputHex As String, szKeyHex As String, szIvHex As String, szAlgModePad As String, Optional nOptions As Long = 0) As String

.NET Equivalent

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

Python Equivalent

static Cipher.decrypt_hex(datahex, keyhex, ivhex='', algmodepad='', alg=None, mode=Mode.ECB, pad=Pad.DEFAULT, opts=Opts.DEFAULT)

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_DecryptBytes 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 copes with padding if required, as well as the option to prepend the IV to the ciphertext.

Any padding will be removed after decryption. If the PKI_IV_PREFIX option is used, the IV will be expected prepended to the ciphertext in the input.

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.

CAUTION: be aware of the special case where the output is the empty string "" of length zero.

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
strCipher = "C3153108A8DD340C0BCB1DFE8D25D2320EE0E66BD2BB4A313FB75C5638E9E1771D4CDA34FBFB7E74B321F9A2CF4EA61B"
Debug.Print "CT=" & strCipher
' Correct result
strOK = "4E6F77206973207468652074696D6520666F7220616C6C20676F6F64206D656E20746F"

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

Debug.Print "PT=" & strPlain
Debug.Print "OK=" & strOK

' PART 2 - CT includes IV prefix
strCipher = "FEDCBA9876543210FEDCBA9876543210C3153108A8DD340C0BCB1DFE8D25D2320EE0E66BD2BB4A313FB75C5638E9E1771D4CDA34FBFB7E74B321F9A2CF4EA61B"
Debug.Print "IV||CT=" & strCipher
nChars = CIPHER_DecryptHex(vbNullString, 0, strCipher, strKey, strIV, strAlg, PKI_IV_PREFIX)
Debug.Print "CIPHER_DecryptHex(PKI_IV_PREFIX) returns " & nChars
Debug.Assert nChars > 0
strPlain = String(nChars, " ")
nChars = CIPHER_DecryptHex(strPlain, nChars, strCipher, strKey, strIV, strAlg, PKI_IV_PREFIX)

Debug.Print "PT=" & strPlain
Debug.Print "PT='" & cnvStringFromHexStr(strPlain) & "'"

This should result in output as follows:

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

Example (VBA wrapper function)

Dim strKeyHex As String
Dim strIvHex As String
Dim strPlainHex As String
Dim strCipherHex As String
strKeyHex = "0123456789ABCDEFF0E1D2C3B4A59687"
strIvHex = "FEDCBA9876543210FEDCBA9876543210"
strCipherHex = "C3153108A8DD340C0BCB1DFE8D25D2320EE0E66BD2BB4A313FB75C5638E9E1771D4CDA34FBFB7E74B321F9A2CF4EA61B"
strPlainHex = cipherDecryptHex(strCipherHex, strKeyHex, strIvHex, "Aes128/CBC/OneAndZeroes")
Debug.Print "PT=" & strPlainHex
Debug.Print "PT='" & cnvStringFromHexStr(strPlainHex) & "'"