CIPHER_StreamHex

CryptoSys API Library Manual

CIPHER_StreamHex

Enciphers data in a hex-encoded string using specified stream cipher.

VBA/VB6 Syntax


Public Declare Function CIPHER_StreamHex Lib "diCryptoSys.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strInputHex As String, ByVal strKeyHex As String, ByVal strIvHex As String, ByVal nCounter As Long, ByVal nOptions As Long) As Long

nRet = CIPHER_StreamHex(strOutput, nOutChars, strInputHex, strKeyHex, strIvHex, nCounter, nOptions)

C/C++ Syntax


long __stdcall  CIPHER_StreamHex(char *szOutput, long nOutChars, const char *szInputHex, const char *szKeyHex, const char *szIvHex, long nCounter, long nOptions);

Parameters

szOutput: [out] string of sufficient length to receive the output (at least as long as the input).
nOutChars: [in] specifying the length of the output buffer in bytes.
szInputHex: [in] string containing the hex-encoded input data.
szKeyHex: [in] string containing the hex-encoded key.
szIvHex: [in] string containing the hex-encoded initialization vector (IV, nonce). Specify "" for Arcfour.
nCounter: [in] the value of the counter (ChaCha20 only).
nOptions: [in] option flags:
Select one of the following:
API_SC_ARCFOUR to use ARCFOUR (RC4)
API_SC_SALSA20 to use Salsa20
API_SC_CHACHA20 to use ChaCha20

Returns (VBA/C)

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

VBA Wrapper Syntax


Public Function cipherStreamHex(lpInput() As Byte, lpKey() As Byte, lpIV() As Byte, nOptions As Long, Optional nCounter As Long = 0) As String

.NET Equivalent

CipherStream.Hex Method

Remarks

This performs a one-off encryption of data in a hex-encoded string using the specified stream cipher. The key and IV are passed as hex-encoded strings. The output will be exactly the same length as the input. C/C++ users must add one to this value when allocating memory.

Arcfour: any length key; specify "" for IV.
Salsa20: key must be exactly 16 or 32 bytes and IV exactly 8 bytes long.
ChaCha20: key must be exactly 16 or 32 bytes and IV exactly 8, 12, or 16 bytes long. Counter is ignored if IV is 16 bytes.
See Stream Ciphers for more details

Example (VBA core function)

' Ref: eSTREAM `verified.test-vectors.txt` Set 3, vector#  0:
Dim nRet As Long
Dim strKey As String
Dim strIV As String
Dim strInput As String
Dim strOutput As String
Dim strCorrect As String
Dim strCheck As String

' Parameters are hex-encoded strings
strKey = "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F"
strIV = "0000000000000000"
' Key stream is generated by encrypting 32 zero bytes (=64 hex chars)
strInput = "0000000000000000000000000000000000000000000000000000000000000000"
strCorrect = "B580F7671C76E5F7441AF87C146D6B513910DC8B4146EF1B3211CF12AF4A4B49"
Debug.Print "KY=" & strKey
Debug.Print "IV=" & strIV
Debug.Print "PT=" & strInput
' Encipher using Salsa20 in hex mode
strOutput = String(Len(strInput), " ")
nRet = CIPHER_StreamHex(strOutput, Len(strOutput), strInput, strKey, strIV, 0, API_SC_SALSA20)
Debug.Print "CT=" & strOutput
Debug.Print "OK=" & strCorrect

This should result in output as follows:

KY=000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F
IV=0000000000000000
PT=0000000000000000000000000000000000000000000000000000000000000000
CT=B580F7671C76E5F7441AF87C146D6B513910DC8B4146EF1B3211CF12AF4A4B49
OK=B580F7671C76E5F7441AF87C146D6B513910DC8B4146EF1B3211CF12AF4A4B49

Example (VBA wrapper function)

Dim strCipher As String
Dim strPlain As String
strCipher = cipherStreamHex("0000000000000000000000000000000000000000000000000000000000000000", _
    "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F", _
    "0000000000000000", API_SC_SALSA20)
Debug.Print "CT=" & strCipher
Debug.Print "OK=B580F7671C76E5F7441AF87C146D6B513910DC8B4146EF1B3211CF12AF4A4B49"
' Decrypt by calling again...
strPlain = cipherStreamHex(strCipher, _
    "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F", _
    "0000000000000000", API_SC_SALSA20)
Debug.Print "PT=" & strPlain

strCipher = cipherStreamHex("00000000000000000000", _
    "ef012345", "", API_SC_ARCFOUR)
Debug.Print "CT=" & strCipher
Debug.Print "OK=d6a141a7ec3c38dfbd61"
' Decrypt by calling again...
strPlain = cipherStreamHex(strCipher, _
    "ef012345", "", API_SC_ARCFOUR)
Debug.Print "PT=" & strPlain