CIPHER

CryptoSys PKI Pro Manual

CIPHER_Hex

Encrypt or decrypt data represented as a hexadecimal string. The key and initialization vector are represented as a hexadecimal string.

VBA/VB6 Syntax


Public Declare Function CIPHER_Hex Lib "diCrPKI.dll" 
(ByVal fEncrypt As Long, ByVal strOutput As String, ByVal nOutChars As Long, ByVal strData As String, 
ByVal strKey As String, ByVal strIV As String, ByVal strAlgAndMode As String, ByVal nOptions As Long) As Long

nRet = CIPHER_Hex(fEncrypt, strOutput, nOutChars, strInput, strKey, strIV, strAlgAndMode, nOptions)

C/C++ Syntax


long __stdcall CIPHER_Hex(long fEncrypt, char *szOutput, long nOutChars, const char *szData, const char *szKey, const char *szIV, const char *szAlgAndMode, long nOptions);

Parameters

fEncrypt: [in] direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
szOutput: [out] of sufficient length to receive the output.
nOutChars: [in] specifying the maximum number of characters to be received.
szData: [in] containing the input data in hex format.
szKey: [in] containing the key in hex format.
szIV: [in] containing the initialization vector (IV) in hex format, or the empty string "" for ECB mode.
szAlgAndMode: [in] containing the block cipher algorithm and mode (see Specifying the algorithm and mode for generic block cipher functions).
nOptions: [in] option flags.

Returns (VBA/C)

If successful, the return value is zero; otherwise it returns a nonzero error code.

.NET Equivalent

Cipher.Encrypt Method (String, String, String, CipherAlgorithm, Mode)
Cipher.Decrypt Method (String, String, String, CipherAlgorithm, Mode)

Remarks

The algorithm and mode must be specified using either the szAlgAndMode or nOptions parameter (see Specifying the algorithm and mode for generic block cipher functions). All data parameters are expected to be in hexadecimal-encoded format and to be of valid lengths. Valid hexadecimal characters are [0-9A-Fa-f]. The hex-encoded key string szKey must represent a value with a length of exactly the required key size. The hex-encoded initialization vector string szIV, if required, must represent a value with a length of exactly the block size. See Valid key and block sizes. Important: The output string szOutput must be dimensioned with at least the same number of characters as the input string before calling. The variables szOutput and szInput should be different.

For ECB and CBC modes, the length of the input string szInput must be an exact multiple of the block size encoded in hex characters otherwise a BAD_LENGTH_ERROR error will occur. It is the responsibility of the user to provide suitable padding before encrypting in those modes and to remove any padding after decrypting.

[New in v20.0] Consider using the newer functions CIPHER_EncryptHex and CIPHER_DecryptHex. These functions take a variable length input and add (or remove) the required padding, and provide the option to prepend the IV to the ciphertext.

Example

This example is from Section 8.1 of [SMIME-EX].

Dim nRet As Long
Dim sPlain As String
Dim sCipher As String
Dim sCheck As String
Dim sKey As String
Dim sInitV As String
Dim sCorrect As String

sPlain = "5468697320736F6D652073616D706520636F6E74656E742E0808080808080808"
'         T h i s _ s o m e _ s a m p e _ c o n t e n t .(+padding 8 x 08)
sKey = "737C791F25EAD0E04629254352F7DC6291E5CB26917ADA32"
sInitV = "B36B6BFB6231084E"
sCorrect = "d76fd1178fbd02f84231f5c1d2a2f74a4159482964f675248254223daf9af8e4"
' Set output to be same length as input
sCipher = String(Len(sPlain), " ")

Debug.Print "KY=" & sKey
Debug.Print "PT=" & sPlain
' Encrypt using strAlgAndMode
nRet = CIPHER_Hex(ENCRYPT, sCipher, Len(sCipher), sPlain, sKey, sInitV, "tdea-cbc", 0)
Debug.Print "CT=" & sCipher & nRet
Debug.Print "OK=" & sCorrect
' Alternative using nOptions
nRet = CIPHER_Hex(ENCRYPT, sCipher, Len(sCipher), sPlain, sKey, sInitV, "", PKI_BC_TDEA + PKI_MODE_CBC)
Debug.Print "CT=" & sCipher & nRet
Debug.Print "OK=" & sCorrect

' Decrypt using strAlgAndMode
sCheck = String(Len(sCipher), " ")
nRet = CIPHER_Hex(DECRYPT, sCheck, Len(sCheck), sCipher, sKey, sInitV, "tdea-cbc", 0)
Debug.Print "P'=" & sCheck & nRet
' Alternative using nOptions
sCheck = String(Len(sCipher), " ")
nRet = CIPHER_Hex(DECRYPT, sCheck, Len(sCheck), sCipher, sKey, sInitV, "", PKI_BC_TDEA + PKI_MODE_CBC)
Debug.Print "P'=" & sCheck & nRet

This should result in output as follows:

KY=737C791F25EAD0E04629254352F7DC6291E5CB26917ADA32
PT=5468697320736F6D652073616D706520636F6E74656E742E0808080808080808
CT=D76FD1178FBD02F84231F5C1D2A2F74A4159482964F675248254223DAF9AF8E4 0 
OK=d76fd1178fbd02f84231f5c1d2a2f74a4159482964f675248254223daf9af8e4
CT=D76FD1178FBD02F84231F5C1D2A2F74A4159482964F675248254223DAF9AF8E4 0 
OK=d76fd1178fbd02f84231f5c1d2a2f74a4159482964f675248254223daf9af8e4
P'=5468697320736F6D652073616D706520636F6E74656E742E0808080808080808 0 
P'=5468697320736F6D652073616D706520636F6E74656E742E0808080808080808 0