CIPHER_StreamBytes

CryptoSys API Library Manual

CIPHER_StreamBytes

Enciphers data in array of bytes using specified stream cipher.

VBA/VB6 Syntax


Public Declare Function CIPHER_StreamBytes Lib "diCryptoSys.dll" (ByRef lpOutput As Byte, ByRef lpData As Byte, ByVal nDataLen As Long, ByRef lpKey As Byte, ByVal nKeyLen As Long, ByRef lpIV As Byte, ByVal nIvLen As Long, ByVal nCounter As Long, ByVal nOptions As Long) As Long

nRet = CIPHER_StreamBytes(lpOutput(0), abData(0), nDataLen, abKey(0), nKeyLen, abIV(0), nIvLen, nCounter, nOptions)

C/C++ Syntax


long __stdcall  CIPHER_StreamBytes(unsigned char *lpOutput, unsigned char *lpData, long nDataLen, unsigned char *lpKey, long nKeyLen, unsigned char *lpIV, long nIvLen, long nCounter, long nOptions);

Parameters

lpOutput: [out] array of sufficient length to receive the output (at least as long as the input).
lpData: [in] array containing the input data.
nDataLen: [in] specifying the length of the input data in bytes.
lpKey: [in] array containing the key.
nKeyLen: [in] specifying the length of the key in bytes.
lpIV: [in] array containing the initialization vector (IV, nonce), if required.
nIvLen: [in] specifying the length of the IV in bytes.
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 cipherStreamBytes(lpInput() As Byte, lpKey() As Byte, lpIV() As Byte, nOptions As Long, Optional nCounter As Long = 0) As Byte()

.NET Equivalent

CipherStream.Bytes Method

C++ (STL) Equivalent

static crsysapi::bvec_t crsysapi::CipherStream::Bytes (const bvec_t &data, const bvec_t &key, const bvec_t &iv, Alg alg, int counter=0)

Python Equivalent

static CipherStream.bytes(data, key, iv, alg, counter=0)

Remarks

This performs a one-off encryption over a byte array using the specified stream cipher. The key and IV are passed as byte arrays. The output will be exactly the same length as the input. The output buffer lpOutput may be the same as the input lpInput.

Arcfour: any length key; specify null 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)

Dim abKey() As Byte
Dim abInput() As Byte
Dim lpOutput() As Byte
Dim nRet As Long
Dim nDataLen As Long
Dim nKeyLen As Long
Dim strCorrect As String

' Arcfour test vector
abKey = cnvBytesFromHexStr("0123456789abcdef")
abInput = cnvBytesFromHexStr("0123456789abcdef")
strCorrect = "75b7878099e0c596"

ReDim lpOutput(UBound(abInput))
nDataLen = UBound(abInput) + 1
nKeyLen = UBound(abKey) + 1

Debug.Print "KY=" & cnvHexStrFromBytes(abKey)
Debug.Print "PT=" & cnvHexStrFromBytes(abInput)
' Encipher using Arcfour
nRet = CIPHER_StreamBytes(lpOutput(0), abInput(0), nDataLen, abKey(0), nKeyLen, ByVal 0&, 0, 0, API_SC_ARCFOUR)
Debug.Print "CT=" & cnvHexStrFromBytes(lpOutput)
Debug.Print "OK=" & strCorrect

' Now decipher just by calling again. Use same output as input.
nRet = CIPHER_StreamBytes(lpOutput(0), lpOutput(0), nDataLen, abKey(0), nKeyLen, ByVal 0&, 0, 0, API_SC_ARCFOUR)
Debug.Print "P'=" & cnvHexStrFromBytes(lpOutput)

This should result in output as follows:

KY=0123456789ABCDEF
PT=0123456789ABCDEF
CT=75B7878099E0C596
OK=75b7878099e0c596
P'=0123456789ABCDEF

' ChaCha20 test vector from "ChaCha20 and Poly1305 for IETF protocols"
Dim abKey() As Byte
Dim abInput() As Byte
Dim lpOutput() As Byte
Dim abIV() As Byte
Dim nRet As Long
Dim nDataLen As Long
Dim nKeyLen As Long
Dim nIvLen As Long
Dim strCorrect As String
Dim strData As String

' Obtain parameters in byte array format
abKey = cnvBytesFromHexStr("000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f")
abIV = cnvBytesFromHexStr("000000000000004a00000000")
strData = _
"Ladies and Gentlemen of the class of '99: If I could offer you only one tip for the future, sunscreen would be it."
abInput = StrConv(strData, vbFromUnicode)
strCorrect = _
"6E2E359A2568F98041BA0728DD0D6981E97E7AEC1D4360C20A27AFCCFD9FAE0BF91B65C5524733AB8F593DABCD62B3571639D624E65152AB8F530C359F0861D807CA0DBF500D6A6156A38E088A22B65E52BC514D16CCF806818CE91AB77937365AF90BBF74A35BE6B40B8EEDF2785E42874D"

ReDim lpOutput(UBound(abInput))
nDataLen = UBound(abInput) + 1
nKeyLen = UBound(abKey) + 1
nIvLen = UBound(abIV) + 1

Debug.Print "KY=" & cnvHexStrFromBytes(abKey)
Debug.Print "IV=" & cnvHexStrFromBytes(abIV)
Debug.Print "PT=" & cnvHexStrFromBytes(abInput)
' Encipher using ChaCha20 with counter=1
nRet = CIPHER_StreamBytes(lpOutput(0), abInput(0), nDataLen, abKey(0), nKeyLen, abIV(0), nIvLen, 1, API_SC_CHACHA20)
Debug.Print "CIPHER_StreamBytes returns " & nRet & " (expecting 0)"
Debug.Print "CT=" & cnvHexStrFromBytes(lpOutput)
Debug.Print "OK=" & strCorrect

' Now decipher just by calling again. Use same output as input.
nRet = CIPHER_StreamBytes(lpOutput(0), lpOutput(0), nDataLen, abKey(0), nKeyLen, abIV(0), nIvLen, 1, API_SC_CHACHA20)
Debug.Print "P'=" & cnvHexStrFromBytes(lpOutput)
Debug.Print "P'=" & StrConv(lpOutput, vbUnicode)

This should result in output as follows:

KY=000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F
IV=000000000000004A00000000
PT=4C616469657320616E642047656E746C656D656E206F662074686520636C617373206F66202739393A204966204920636F756C64206F6666657220796F75206F6E6C79206F6E652074697020666F7220746865206675747572652C2073756E73637265656E20776F756C642062652069742E
CIPHER_StreamBytes returns 0 (expecting 0)
CT=6E2E359A2568F98041BA0728DD0D6981E97E7AEC1D4360C20A27AFCCFD9FAE0BF91B65C5524733AB8F593DABCD62B3571639D624E65152AB8F530C359F0861D807CA0DBF500D6A6156A38E088A22B65E52BC514D16CCF806818CE91AB77937365AF90BBF74A35BE6B40B8EEDF2785E42874D
OK=6E2E359A2568F98041BA0728DD0D6981E97E7AEC1D4360C20A27AFCCFD9FAE0BF91B65C5524733AB8F593DABCD62B3571639D624E65152AB8F530C359F0861D807CA0DBF500D6A6156A38E088A22B65E52BC514D16CCF806818CE91AB77937365AF90BBF74A35BE6B40B8EEDF2785E42874D
P'=4C616469657320616E642047656E746C656D656E206F662074686520636C617373206F66202739393A204966204920636F756C64206F6666657220796F75206F6E6C79206F6E652074697020666F7220746865206675747572652C2073756E73637265656E20776F756C642062652069742E
P'=Ladies and Gentlemen of the class of '99: If I could offer you only one tip for the future, sunscreen would be it.

Example (VBA wrapper function)

Dim lpCipher() As Byte
Dim lpPlain() As Byte
Dim lpKey() As Byte
Dim lpIV() As Byte
Dim strData As String
lpKey = cnvBytesFromHexStr("000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f")
lpIV = cnvBytesFromHexStr("000000000000004a00000000")
strData = _
"Ladies and Gentlemen of the class of '99: If I could offer you only one tip for the future, sunscreen would be it."
lpPlain = StrConv(strData, vbFromUnicode)   ' Encode as bytes

' Encipher using ChaCha20 with counter=1
lpCipher = cipherStreamBytes(lpPlain, lpKey, lpIV, API_SC_CHACHA20, 1)
Debug.Print "CT=" & cnvHexStrFromBytes(lpCipher)
Debug.Print "OK=6E2E359A2568F98041BA0728DD0D6981E97E7AEC1D4360C20A27AFCCFD9FAE0BF91B65C5524733AB8F593DABCD62B3571639D624E65152AB8F" _
	& "530C359F0861D807CA0DBF500D6A6156A38E088A22B65E52BC514D16CCF806818CE91AB77937365AF90BBF74A35BE6B40B8EEDF2785E42874D"
' Now decipher just by calling again. ...
lpPlain = cipherStreamBytes(lpCipher, lpKey, lpIV, API_SC_CHACHA20, 1)
Debug.Print "PT=" & StrConv(lpPlain, vbUnicode) ' Decode bytes to string

' Arcfour test vector
lpKey = cnvBytesFromHexStr("0123456789abcdef")
lpPlain = cnvBytesFromHexStr("0123456789abcdef")
lpIV = vbNullString     ' Empty (null) array
' Encipher using Arcfour
lpCipher = cipherStreamBytes(lpPlain, lpKey, lpIV, API_SC_ARCFOUR)
Debug.Print "CT=" & cnvHexStrFromBytes(lpCipher)
Debug.Print "OK=75b7878099e0c596"