CryptoSys API 6.22.1

Functions | Index

basCryptoSys.bas File Reference

The VBA/VB6 interface to CryptoSys API.

Functions

aeadAddAAD: Add a chunk of additional authenticated data (in incremental mode). More...
aeadDecryptWithTag: Decrypt data using specified AEAD algorithm in one-off operation. More...
aeadDestroy: Close the AEAD context and destroy the key (in incremental mode). More...
aeadEncryptWithTag: Encrypt data using specified AEAD algorithm in one-off operation. More...
aeadFinishDecrypt: Finish the authenticated decryption (in incremental mode). More...
aeadFinishEncrypt: Finish the authenticated encryption (in incremental mode). More...
aeadInitKey: Initialize the AEAD context with the key and algorithm ready for repeated incremental operations. More...
aeadSetNonce: Set the nonce for the AEAD context (in incremental mode). More...
aeadStartDecrypt: Start authenticated decryption (in incremental mode). More...
aeadStartEncrypt: Start authenticated encryption (in incremental mode). More...
aeadUpdate: Encrypts or decrypts a chunk of input (in incremental mode). More...
apiCompileTime: Gets date and time the CryptoSys DLL module was last compiled. More...
apiErrorCode: Returns the error code of the error that occurred when calling the last function. More...
apiErrorLookup: Retrieves the error message associated with a given error code. More...
apiLicenceType: Returns the ASCII value of the licence type. More...
apiModuleInfo: Get additional information about the core DLL module. More...
apiModuleName: Retrieves the name of the current process's module. More...
apiPlatform: Get platform the core DLL was compiled for. More...
apiVersion: Get version number of native core DLL. More...
blfBytesBlock: Encrypt or decrypt a block of data using Blowfish algorithm. More...
cipherDecryptBytes: Decrypts data in a byte array using the specified block cipher algorithm, mode and padding. More...
cipherDecryptHex: Decrypt hex-encoded data using the specified block cipher algorithm, mode and padding. More...
cipherEncryptBytes: Encrypts data in a byte array using the specified block cipher algorithm, mode and padding. More...
cipherEncryptHex: Encrypt hex-encoded data using the specified block cipher algorithm, mode and padding. More...
cipherFileDecrypt: Decrypt a file with block cipher. More...
cipherFileEncrypt: Encrypt a file with block cipher. More...
cipherFinal: Closes and clears the CIPHER context. More...
cipherInit: Initializes the CIPHER context with the key, algorithm and mode ready for repeated incremental operations. More...
cipherInitHex: Initializes the CIPHER context with hex-encoded key, algorithm and mode ready for repeated incremental operations. More...
cipherKeyUnwrap: Unwraps (decrypts) key material with a key-encryption key. More...
cipherKeyWrap: Wraps (encrypts) key material with a key-encryption key. More...
cipherStreamBytes: Encipher data in array of bytes using specified stream cipher. More...
cipherStreamFile: Encipher data in a file using specified stream cipher. More...
cipherStreamFinal: Close the CIPHERSTREAM context and destroy the key. More...
cipherStreamHex: Encipher data in a hex-encoded string using specified stream cipher. More...
cipherStreamInit: Initialize the CIPHERSTREAM context ready for repeated operations of cipherStreamUpdate. More...
cipherStreamUpdate: Encrypt input using current CIPHERSTREAM context (in incremental mode). More...
cipherUpdate: Encrypts or decrypts a chunk of input (in incremental mode). More...
cipherUpdateHex: Encrypts or decrypts a chunk of hex-encoded input (in incremental mode). More...
cnvB64Filter: Strips any invalid base64 characters from a string. More...
cnvB64StrFromBytes: Encodes an array of bytes as a base64-encoded string. More...
cnvB64StrFromHexStr: Re-encodes a hexadecimal-encoded binary value as base64. More...
cnvB64StrFromString: Encodes an ANSI string as a base64-encoded string. More...
cnvBytesFromB64Str: Decodes a base64-encoded string as an array of Bytes. More...
cnvBytesFromHexStr: Decodes a hexadecimal-encoded string as an array of Bytes. More...
cnvBytesLen: Find length of byte array. More...
cnvBytesMid: Return a substring of bytes of specified length from within a given byte array More...
cnvFromBase64: Decodes a base64-encoded string as an array of bytes. More...
cnvFromHex: Decodes a hexadecimal-encoded string as an array of bytes. More...
cnvHexFilter: Strips any invalid hex characters from a hex string. More...
cnvHexFromBytesMid: Encodes a substring of an array of bytes as a hexadecimal-encoded string. More...
cnvHexStrFromB64Str: Re-encodes a base64-encoded binary value as hexadecimal. More...
cnvHexStrFromBytes: Encodes an array of bytes as a hexadecimal-encoded string. More...
cnvHexStrFromString: Encodes an ANSI string as a hexadecimal-encoded string. More...
cnvStringFromHexStr: Decodes a hexadecimal-encoded string as an ANSI string. More...
cnvToBase64: Encodes an array of bytes as a base64-encoded string. More...
cnvToHex: Encodes an array of bytes as a hexadecimal-encoded string. More...
comprCompress: Compress data using compression algorithm. More...
comprUncompress: Uncompress data using compression algorithm. More...
crcBytes: Compute the CRC-32 checksum of an array of bytes. More...
crcFile: Compute the CRC-32 checksum of a file. More...
crcString: Compute the CRC-32 checksum of an ANSI string. More...
errFormatErrorMessage: Return an error message string for the last error. More...
hashAddBytes: Add an array of bytes to be digested. More...
hashAddString: Add a string to be digested. More...
hashBytes: Compute hash digest in byte format of byte input. More...
hashFile: Compute hash digest in byte format of a file. More...
hashFinal: Return the final message digest value. More...
hashHexFromBits: Compute hash digest in hex format from bit-oriented input. More...
hashHexFromBytes: Compute hash digest in hex format of byte input. More...
hashHexFromFile: Compute hash digest in hex format of a file. More...
hashHexFromHex: Compute hash digest in hex-encoded format from hex-encoded input. More...
hashHexFromString: Compute hash digest in hex-encoded format from hex-encoded input. More...
hashInit: Initialise the HASH context ready for incremental operations. More...
hashLength: Return length of message digest output in bytes. More...
macAddBytes: Adds an array of bytes to be authenticated. More...
macAddString: Adds a string to be authenticated. More...
macBytes: Computes a keyed MAC in byte format from byte input. More...
macFinal: Returns the final MAC value. More...
macHexFromBytes: Computes a keyed MAC in hex-encoded format from byte input. More...
macHexFromHex: Computes a keyed MAC in hex-encoded format from hex-encoded input. More...
macInit: Initialises the MAC context ready to receive data to authenticate. More...
padBytesBlock: Creates an input block suitably padded for encryption by a block cipher in ECB or CBC mode. More...
padHexBlock: Creates a hex-encoded input block suitably padded for encryption by a block cipher in ECB or CBC mode. More...
padHexString: Add PKCS5 padding to a hex string up to next multiple of block length [DEPRECATED]. More...
padUnpadBytes: Removes the padding from an encryption block. More...
padUnpadHex: Removes the padding from a hex-encoded encryption block. More...
pbeKdf2: Derives a key of any length from a password using the PBKDF2 algorithm from PKCS#5 v2.1. More...
pbeKdf2Hex: Derives a hex-encoded key of any length from a password using the PBKDF2 algorithm from PKCS#5 v2.1. More...
pbeScrypt: Derives a key of any length from a password using the SCRYPT algorithm from RFC7914. More...
pbeScryptHex: Derives a hex-encoded key of any length from a password using the SCRYPT algorithm from RFC7914. More...
prfBytes: Generate output bytes using a pseudorandom function (PRF). More...
rngInitialize: Initialize the RNG generator using a seed file. More...
rngInitializeEx: Query and initialize the RNG generator using Intel(R) DRNG, if available. More...
rngKeyBytes: Generate a random key value. More...
rngKeyHex: Generate a random key in hex format. More...
rngNonce: Generate a random nonce. More...
rngNonceHex: Generate a hex-encoded sequence of bytes. More...
unpadHexString: Strips PKCS5 padding from a hex string [DEPRECATED]. More...
wipeBytes: Zeroise data in memory. More...
wipeFile: Securely wipes and deletes a file using 7-pass DOD standards. More...
wipeString: Zeroise a string. More...
xofBytes: Generate bytes using an extendable-output function (XOF). More...
zlibDeflate: Compress data using the ZLIB deflate algorithm. More...
zlibInflate: Inflate compressed data using the ZLIB algorithm. More...

Function Descriptions

aeadAddAAD

Add a chunk of additional authenticated data (in incremental mode).

Syntax

[VBA]

Public Function aeadAddAAD ( _
    hContext As Long, _
    lpAAD() As Byte _
) As Long

Parameters

hContext: Handle to the AEAD context set up by an earlier call to aeadInitKey.
lpAAD: Chunk of Additional Authenticated Data (AAD) to add.

Return Value

Long: Zero (0) on success, or a nonzero error code (use apiErrorLookup to check).

Remarks

May be repeated to add additional data in chunks. Must eventually be followed by either aeadStartEncrypt or aeadStartDecrypt. Returns MISUSE_ERROR if called out of sequence.

aeadDecryptWithTag

Decrypt data using specified AEAD algorithm in one-off operation. The authentication tag is expected to be appended to the input ciphertext.

Syntax

[VBA]

Public Function aeadDecryptWithTag ( _
    lpData() As Byte, _
    lpKey() As Byte, _
    lpNonce() As Byte, _
    lpAAD() As Byte, _
    nOptions As Long _
) As Byte()

Parameters

lpData

Input data to be decrypted.

lpKey

Key of exact length for algorithm (16 or 32 bytes).

lpNonce

Initialization Vector (IV) (aka nonce) exactly 16 bytes for ASCON else exactly 12 bytes long.

lpAAD

Additional authenticated data (optional) - set variable as vbNullString to ignore.

nOptions

Algorithm to be used. Select one from

API_AEAD_AES_128_GCM
API_AEAD_AES_256_GCM
API_AEAD_CHACHA20_POLY1305
API_AEAD_ASCON_128
API_AEAD_ASCON_128A

Add API_IV_PREFIX to expect the IV to be prepended at the start of the input (use the Or operator).

Return Value

Byte(): Plaintext in a byte array, or empty array on error (an empty array may also be the correct result).

Remarks

The input must include the 16-byte tag appended to the ciphertext.

aeadDestroy

Close the AEAD context and destroy the key (in incremental mode).

Syntax

[VBA]

Public Function aeadDestroy ( _
    hContext As Long _
) As Long

Parameters

hContext: Handle to the AEAD context set up by an earlier call to aeadInitKey.

Return Value

Long: Zero (0) on success, or a nonzero error code (use apiErrorLookup to check).

aeadEncryptWithTag

Encrypt data using specified AEAD algorithm in one-off operation. The authentication tag is appended to the output.

Syntax

[VBA]

Public Function aeadEncryptWithTag ( _
    lpData() As Byte, _
    lpKey() As Byte, _
    lpNonce() As Byte, _
    lpAAD() As Byte, _
    nOptions As Long _
) As Byte()

Parameters

lpData

Input data to be encrypted.

lpKey

Key of exact length for algorithm (16 or 32 bytes).

lpNonce

Initialization Vector (IV) (aka nonce) exactly 16 bytes for ASCON else exactly 12 bytes long.

lpAAD

Additional authenticated data (optional) - set variable as vbNullString to ignore.

nOptions

Algorithm to be used. Select one from

API_AEAD_AES_128_GCM
API_AEAD_AES_256_GCM
API_AEAD_CHACHA20_POLY1305
API_AEAD_ASCON_128
API_AEAD_ASCON_128A

Add API_IV_PREFIX to prepend the IV (nonce) before the ciphertext in the output (use the Or operator).

Return Value

Byte(): Ciphertext with tag appended in a byte array, or empty array on error.

Remarks

The output will either be exactly taglen (16) bytes longer than the input, or exactly taglen + ivlen (28/32) bytes longer if API_IV_PREFIX is used.

aeadFinishDecrypt

Finish the authenticated decryption (in incremental mode).

Syntax

[VBA]

Public Function aeadFinishDecrypt ( _
    hContext As Long _
) As Long

Parameters

hContext: Handle to the AEAD context set up by an earlier call to aeadInitKey.

Return Value

Long: Zero (0) on success, or a nonzero error code (use apiErrorLookup to check).

Remarks

Returns the nonzero error code AUTH_FAILED_ERROR (-40) if the inputs are not authentic. Must be preceded by aeadStartDecrypt and zero or more calls to aeadUpdate. May be followed by aeadSetNonce to begin processing another packet with the same key and algorithm; otherwise should be followed by aeadDestroy. Returns MISUSE_ERROR if called out of sequence.

aeadFinishEncrypt

Finish the authenticated encryption (in incremental mode).

Syntax

[VBA]

Public Function aeadFinishEncrypt ( _
    hContext As Long _
) As Byte()

Parameters

hContext: Handle to the AEAD context set up by an earlier call to aeadInitKey.

Return Value

Byte(): Authentication tag value.

Remarks

Must be preceded by aeadStartEncrypt and zero or more calls to aeadUpdate. May be followed by aeadSetNonce to begin processing another packet with the same key and algorithm; otherwise should be followed by aeadDestroy.

aeadInitKey

Initialize the AEAD context with the key and algorithm ready for repeated incremental operations.

Syntax

[VBA]

Public Function aeadInitKey ( _
    lpKey() As Byte, _
    nOptions As Long _
) As Long

Parameters

lpKey

Key of exact length for algorithm (16 or 32 bytes).

nOptions

Algorithm to be used. Select one from

API_AEAD_AES_128_GCM
API_AEAD_AES_256_GCM
API_AEAD_CHACHA20_POLY1305

Return Value

Long: Nonzero handle of the AEAD context, or zero if an error occurs.

aeadSetNonce

Set the nonce for the AEAD context (in incremental mode).

Syntax

[VBA]

Public Function aeadSetNonce ( _
    hContext As Long, _
    lpNonce() As Byte _
) As Long

Parameters

hContext: Handle to the AEAD context set up by an earlier call to aeadInitKey.
lpNonce: Nonce of exact length required for given algorithm (currently always 12 bytes).

Return Value

Long: Zero (0) on success, or a nonzero error code (use apiErrorLookup to check).

aeadStartDecrypt

Start authenticated decryption (in incremental mode).

Syntax

[VBA]

Public Function aeadStartDecrypt ( _
    hContext As Long, _
    lpTagToCheck() As Byte _
) As Long

Parameters

hContext: Handle to the AEAD context set up by an earlier call to aeadInitKey.
lpTagToCheck: Byte array containing the tag to be checked.

Return Value

Long: Zero (0) on success, or a nonzero error code (use apiErrorLookup to check).

Remarks

May be followed by zero or more calls to aeadUpdate to decrypt data in chunks. Must eventually be followed by aeadFinishDecrypt. Returns MISUSE_ERROR if called out of sequence. Caution: do not trust decrypted data until final authentication.

aeadStartEncrypt

Start authenticated encryption (in incremental mode).

Syntax

[VBA]

Public Function aeadStartEncrypt ( _
    hContext As Long _
) As Long

Parameters

hContext: Handle to the AEAD context set up by an earlier call to aeadInitKey.

Return Value

Long: Zero (0) on success, or a nonzero error code (use apiErrorLookup to check).

Remarks

May be followed by zero or more calls to aeadUpdate to encrypt data in chunks. Must eventually be followed by aeadFinishEncrypt. Returns MISUSE_ERROR if called out of sequence.

aeadUpdate

Encrypts or decrypts a chunk of input (in incremental mode).

Syntax

[VBA]

Public Function aeadUpdate ( _
    hContext As Long, _
    lpData() As Byte _
) As Byte()

Parameters

hContext: Handle to the AEAD context set up by an earlier call to aeadInitKey.
lpData: Data to be encrypted or decrypted.

Return Value

Byte(): Encrypted or decrypted data in array of exactly the same length as input; or an empty array on error

Remarks

This function may be repeated to add data in chunks. The input data is encrypted or decrypted depending on the start mode set by a preceding call to aeadStartEncrypt or aeadStartDecrypt, respectively. It must eventually be followed by either aeadFinishEncrypt or aeadFinishDecrypt, which must match the start mode.

apiCompileTime

Gets date and time the CryptoSys DLL module was last compiled.

Syntax

[VBA]

Public Function apiCompileTime() As String

Return Value

String: Date and time string.

apiErrorCode

Returns the error code of the error that occurred when calling the last function.

Syntax

[VBA]

Public Function apiErrorCode() As Long

Return Value

Long: Error code (see apiErrorLookup).

Remarks

Not all functions set this value.

apiErrorLookup

Retrieves the error message associated with a given error code.

Syntax

[VBA]

Public Function apiErrorLookup ( _
    nCode As Long _
) As String

Parameters

nCode: Error code for which the message is required.

Return Value

String: Error message, or empty string if no corresponding error code.

apiLicenceType

Returns the ASCII value of the licence type.

Syntax

[VBA]

Public Function apiLicenceType ( _
    Optional nOptions As Long = 0 _
) As String

Parameters

nOptions: For future use.

Return Value

String: D=Developer T=Trial.

apiModuleInfo

Get additional information about the core DLL module.

Syntax

[VBA]

Public Function apiModuleInfo ( _
    Optional nOptions As Long = 0 _
) As String

Parameters

nOptions: For future use.

Return Value

String: Additional information, e.g. "Licensed Developer Edition".

apiModuleName

Retrieves the name of the current process's module.

Syntax

[VBA]

Public Function apiModuleName ( _
    Optional nOptions As Long = 0 _
) As String

Parameters

nOptions: For future use.

Return Value

String: File path to current DLL module.

apiPlatform

Get platform the core DLL was compiled for.

Syntax

[VBA]

Public Function apiPlatform() As String

Return Value

String: "Win32" or "X64".

apiVersion

Get version number of native core DLL.

Syntax

[VBA]

Public Function apiVersion() As Long

Return Value

Long: Version number as an integer in form Major*100*100 + Minor*100 + Revision. For example, version 6.1.2 would return 60102.

blfBytesBlock

Encrypt or decrypt a block of data using Blowfish algorithm.

Syntax

[VBA]

Public Function blfBytesBlock ( _
    fEncrypt As Integer, _
    lpInput() As Byte, _
    lpKey() As Byte, _
    lpIV() As Byte, _
    Optional szMode As String = "ECB" _
) As Byte()

Parameters

fEncrypt

ENCRYPT (True) to encrypt, DECRYPT (False) to decrypt

lpInput

Input data, length must be an exact multiple of 8.

lpKey

Key of length between 1 and 56 bytes (448 bits)

lpIV

Initialization vector of exactly 8 bytes

szMode

Encryption mode. Select one from:

"ECB" "CBC" "CTR" "OFB" "CFB"

Return Value

Byte(): Output data, the same length as the input, or an empty array on error.

cipherDecryptBytes

Decrypts data in a byte array using the specified block cipher algorithm, mode and padding. The key and initialization vector are passed as byte arrays.

Syntax

[VBA]

Public Function cipherDecryptBytes ( _
    lpInput() As Byte, _
    lpKey() As Byte, _
    lpIV() As Byte, _
    szAlgModePad As String, _
    Optional nOptions As Long = 0 _
) As Byte()

Parameters

lpInput

Input data to be decrypted.

lpKey

Key of exact length for block cipher algorithm.

lpIV

Initialization Vector (IV) of exactly the block size (if not provided in input) or empty array for ECB mode.

szAlgModePad

String with block cipher algorithm, mode and padding, e.g. "aes128/cbc/pkcs5"

Alg:  aes128|aes192|aes256|tdea|3des|desede3
Mode: ecb|cbc|ofb|cfb|ctr
Pad:  pkcs5|nopad|oneandzeroes|ansix923|w3c

nOptions

Add API_IV_PREFIX to expect the IV to be prepended at the start of the input (ignored for ECB mode).

Return Value

Byte(): Decrypted plaintext in byte array or empty array on error.

Remarks

Default padding is Pkcs5 for ECB and CBC mode and NoPad for all other modes.

cipherDecryptHex

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

Syntax

[VBA]

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

Parameters

szInputHex

Hex-encoded input data.

szKeyHex

Hex-encoded key of exact key length.

szIvHex

Hex-encoded IV of exact block length, ignored for ECB mode or if API_IV_PREFIX is used (use "").

szAlgModePad

String with block cipher algorithm, mode and padding, e.g. "aes128/cbc/pkcs5"

Alg:  aes128|aes192|aes256|tdea|3des|desede3
Mode: ecb|cbc|ofb|cfb|ctr
Pad:  pkcs5|nopad|oneandzeroes|ansix923|w3c

nOptions

Add API_IV_PREFIX to expect the IV to be prepended before the ciphertext in the input (not applicable for ECB mode).

Return Value

String: Decrypted plaintext in hex-encoded string or empty string on error.

Remarks

Input data may be any even number of hex characters, but not zero. Default padding is Pkcs5 for ECB and CBC mode and NoPad for all other modes.

cipherEncryptBytes

Encrypts data in a byte array using the specified block cipher algorithm, mode and padding. The key and initialization vector are passed as byte arrays.

Syntax

[VBA]

Public Function cipherEncryptBytes ( _
    lpInput() As Byte, _
    lpKey() As Byte, _
    lpIV() As Byte, _
    szAlgModePad As String, _
    Optional nOptions As Long = 0 _
) As Byte()

Parameters

lpInput

Input data to be encrypted.

lpKey

Key of exact length for block cipher algorithm.

lpIV

Initialization Vector (IV) of exactly the block size or empty array for ECB mode.

szAlgModePad

String with block cipher algorithm, mode and padding, e.g. "aes128/cbc/pkcs5"

Alg:  aes128|aes192|aes256|tdea|3des|desede3
Mode: ecb|cbc|ofb|cfb|ctr
Pad:  pkcs5|nopad|oneandzeroes|ansix923|w3c

nOptions

Add API_IV_PREFIX to prepend the IV before the ciphertext in the output (ignored for ECB mode).

Return Value

Byte(): Ciphertext in byte array or empty array on error.

Remarks

Default padding is Pkcs5 for ECB and CBC mode and NoPad for all other modes.

cipherEncryptHex

Encrypt hex-encoded data using the specified block cipher algorithm, mode and padding. The key and initialization vector are passed as hex-encoded strings.

Syntax

[VBA]

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

Parameters

szInputHex

Input data to be encrypted.

szKeyHex

Hex-encoded key of exact key length.

szIvHex

Hex-encoded IV of exact block length or "" for ECB mode.

szAlgModePad

String with block cipher algorithm, mode and padding, e.g. "aes128/cbc/pkcs5"

Alg:  aes128|aes192|aes256|tdea|3des|desede3
Mode: ecb|cbc|ofb|cfb|ctr
Pad:  pkcs5|nopad|oneandzeroes|ansix923|w3c

nOptions

Add API_IV_PREFIX to prepend the IV before the ciphertext in the output (ignored for ECB mode).

Return Value

String: Encrypted ciphertext in hex-encoded string or empty string on error.

Remarks

Input data may be any even number of hex characters, but not zero. Default padding is Pkcs5 for ECB and CBC mode and NoPad for all other modes.

cipherFileDecrypt

Decrypt a file with block cipher.

Syntax

[VBA]

Public Function cipherFileDecrypt ( _
    szFileOut As String, _
    szFileIn As String, _
    lpKey() As Byte, _
    lpIV() As Byte, _
    szAlgModePad As String, _
    Optional nOptions As Long = 0 _
) As Long

Parameters

szFileOut

Name of output file to be created or overwritten.

szFileIn

Name of input file.

lpKey

Key of exact length for block cipher algorithm.

lpIV

Initialization Vector (IV) of exactly the block size, or empty array for ECB mode or if IV already prefixed to input.

szAlgModePad

String with block cipher algorithm, mode and padding, e.g. "aes128/cbc/pkcs5"

Alg:  aes128|aes192|aes256|tdea|3des|desede3
Mode: ecb|cbc|ofb|cfb|ctr
Pad:  pkcs5|nopad|oneandzeroes|ansix923|w3c

nOptions

Add API_IV_PREFIX to expect the IV to be prepended before the ciphertext in the input (ignored for ECB mode).

Return Value

Long: Zero (0) on success, or a nonzero error code (use apiErrorLookup to check).

Remarks

szFileOut and szFileIn must not be the same.

cipherFileEncrypt

Encrypt a file with block cipher.

Syntax

[VBA]

Public Function cipherFileEncrypt ( _
    szFileOut As String, _
    szFileIn As String, _
    lpKey() As Byte, _
    lpIV() As Byte, _
    szAlgModePad As String, _
    Optional nOptions As Long = 0 _
) As Long

Parameters

szFileOut

Name of output file to be created or overwritten.

szFileIn

Name of input file.

lpKey

Key of exact length for block cipher algorithm.

lpIV

Initialization Vector (IV) of exactly the block size or empty array for ECB mode.

szAlgModePad

String with block cipher algorithm, mode and padding, e.g. "aes128/cbc/pkcs5"

Alg:  aes128|aes192|aes256|tdea|3des|desede3
Mode: ecb|cbc|ofb|cfb|ctr
Pad:  pkcs5|nopad|oneandzeroes|ansix923|w3c

nOptions

Add API_IV_PREFIX to prepend the IV before the ciphertext in the output (ignored for ECB mode).

Return Value

Long: Zero (0) on success, or a nonzero error code (use apiErrorLookup to check).

Remarks

szFileOut and szFileIn must not be the same.

cipherFinal

Closes and clears the CIPHER context.

Syntax

[VBA]

Public Function cipherFinal ( _
    hContext As Long _
) As Long

Parameters

hContext: Handle to the CIPHER context.

Return Value

Long: Zero (0) on success, or a nonzero error code (use apiErrorLookup to check)

cipherInit

Initializes the CIPHER context with the key, algorithm and mode ready for repeated incremental operations.

Syntax

[VBA]

Public Function cipherInit ( _
    fEncrypt As Integer, _
    szAlgAndMode As String, _
    lpKey() As Byte, _
    lpIV() As Byte, _
    Optional nOptions As Long = 0 _
) As Long

Parameters

fEncrypt: Direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
szAlgAndMode: String with block cipher algorithm and mode, e.g. "aes128/cbc"
lpKey: Key of exact length for block cipher algorithm.
lpIV: Initialization Vector (IV) of exactly the block size or empty array for ECB mode.
nOptions: Option flags, set as zero for defaults.

Return Value

Long: Nonzero handle of the CIPHER context, or zero if an error occurs.

cipherInitHex

Initializes the CIPHER context with hex-encoded key, algorithm and mode ready for repeated incremental operations.

Syntax

[VBA]

Public Function cipherInitHex ( _
    fEncrypt As Integer, _
    szAlgAndMode As String, _
    szKeyHex As String, _
    szIvHex As String, _
    Optional nOptions As Long = 0 _
) As Long

Parameters

fEncrypt: Direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
szAlgAndMode: String with block cipher algorithm and mode, e.g. "aes128/cbc"
szKeyHex: Hex-encoded key of exact length for block cipher algorithm.
szIvHex: Hex-encoded initialization vector (IV) of exactly the block size or "" for ECB mode.
nOptions: Option flags, set as zero for defaults.

Return Value

Long: Nonzero handle of the CIPHER context, or zero if an error occurs.

cipherKeyUnwrap

Unwraps (decrypts) key material with a key-encryption key.

Syntax

[VBA]

Public Function cipherKeyUnwrap ( _
    lpData() As Byte, _
    lpKek() As Byte, _
    nOptions As Long _
) As Byte()

Parameters

lpData

Wrapped key.

lpKek

Key encryption key.

nOptions

Algorithm to be used. Select one from:

API_BC_AES128
API_BC_AES192
API_BC_AES256
API_BC_3DES

Return Value

Byte(): Unwrapped key material (or empty array on error).

cipherKeyWrap

Wraps (encrypts) key material with a key-encryption key.

Syntax

[VBA]

Public Function cipherKeyWrap ( _
    lpData() As Byte, _
    lpKek() As Byte, _
    nOptions As Long _
) As Byte()

Parameters

lpData

Key material to be wrapped.

lpKek

Key encryption key.

nOptions

Algorithm to be used. Select one from:

API_BC_AES128
API_BC_AES192
API_BC_AES256
API_BC_3DES

Return Value

Byte(): Wrapped key (or empty array on error).

cipherStreamBytes

Encipher data in array of bytes using specified stream cipher.

Syntax

[VBA]

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

Parameters

lpInput

Input data.

lpKey

Key.

lpIV

Initialization Vector (IV, nonce). Use an empty array for Arcfour.

nOptions

Algorithm to be used. Select one from:

API_SC_ARCFOUR
API_SC_SALSA20
API_SC_CHACHA20

nCounter

Counter value for ChaCha20 only, otherwise ignored.

Return Value

Byte(): Ciphertext in byte array, or empty array on error.

Remarks

Arcfour: any length key; use an empty array 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.
Note different order of parameters from core function.

cipherStreamFile

Encipher data in a file using specified stream cipher.

Syntax

[VBA]

Public Function cipherStreamFile ( _
    szFileOut As String, _
    szFileIn As String, _
    lpKey() As Byte, _
    lpIV() As Byte, _
    nOptions As Long, _
    Optional nCounter As Long = 0 _
) As Long

Parameters

szFileOut

Output file to be created.

szFileIn

Input file to be processed.

lpKey

Key.

lpIV

Initialization Vector (IV, nonce). Use an empty array for Arcfour.

nOptions

Algorithm to be used. Select one from:

API_SC_ARCFOUR
API_SC_SALSA20
API_SC_CHACHA20

nCounter

Counter value for ChaCha20 only, otherwise ignored.

Return Value

Long: Zero (0) on success, or a nonzero error code (use apiErrorLookup to check)

Remarks

cipherStreamFinal

Close the CIPHERSTREAM context and destroy the key.

Syntax

[VBA]

Public Function cipherStreamFinal ( _
    hContext As Long _
) As Long

Parameters

hContext: Handle to the CIPHERSTREAM context.

Return Value

Long:

cipherStreamHex

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

Syntax

[VBA]

Public Function cipherStreamHex ( _
    szInputHex As String, _
    szKeyHex As String, _
    szIvHex As String, _
    nOptions As Long, _
    Optional nCounter As Long = 0 _
) As String

Parameters

szInputHex

Hex-encoded input data.

szKeyHex

Hex-encoded key.

szIvHex

Hex-encoded Initialization Vector (IV, nonce). Use "" for Arcfour.

nOptions

Algorithm to be used. Select one from:

API_SC_ARCFOUR
API_SC_SALSA20
API_SC_CHACHA20

nCounter

Counter value for ChaCha20 only, otherwise ignored.

Return Value

String: Ciphertext in hex-encoded string or empty string on error.

Remarks

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.
Note different order of parameters from core function.

Example

' Test vector 3
Debug.Print cipherStreamHex("00000000000000000000", "ef012345", "", API_SC_ARCFOUR)
' OK=D6A141A7EC3C38DFBD61

cipherStreamInit

Initialize the CIPHERSTREAM context ready for repeated operations of cipherStreamUpdate.

Syntax

[VBA]

Public Function cipherStreamInit ( _
    lpKey() As Byte, _
    lpIV() As Byte, _
    nOptions As Long, _
    Optional nCounter As Long = 0 _
) As Long

Parameters

lpKey

Key.

lpIV

Initialization Vector (IV, nonce). Use an empty array for Arcfour.

nOptions

Algorithm to be used. Select one from:

API_SC_ARCFOUR
API_SC_SALSA20
API_SC_CHACHA20

nCounter

Counter value for ChaCha20 only, otherwise ignored.

Return Value

Long: Nonzero handle of the CIPHERSTREAM context, or zero if an error occurs.

Remarks

cipherStreamUpdate

Encrypt input using current CIPHERSTREAM context (in incremental mode).

Syntax

[VBA]

Public Function cipherStreamUpdate ( _
    hContext As Long, _
    lpData() As Byte _
) As Byte()

Parameters

hContext: Handle to the CIPHERSTREAM context.
lpData: Data to be encrypted.

Return Value

Byte(): Encrypted array of exactly the same length as input; or an empty array on error

cipherUpdate

Encrypts or decrypts a chunk of input (in incremental mode).

Syntax

[VBA]

Public Function cipherUpdate ( _
    hContext As Long, _
    lpData() As Byte _
) As Byte()

Parameters

hContext: Handle to the CIPHER context.
lpData: Input data to be processed.

Return Value

Byte(): Encrypted/decrypted block the same length as the input, or an empty array on error.

Remarks

The input byte array must be a length exactly a multiple of the block size, except for the last chunk in CTR/OFB/CFB mode. Input in ECB/CBC mode must be suitably padded to the correct length.

cipherUpdateHex

Encrypts or decrypts a chunk of hex-encoded input (in incremental mode).

Syntax

[VBA]

Public Function cipherUpdateHex ( _
    hContext As Long, _
    szInputHex As String _
) As String

Parameters

hContext: Handle to the CIPHER context.
szInputHex: Hex-encoded input data.

Return Value

String: Hex-encoded encrypted/decrypted chunk the same length as the input, or empty string "" on error.

Remarks

The input must represent data of a length exactly a multiple of the block size, except for the last chunk in CTR/OFB/CFB mode. Input in ECB/CBC mode must be suitably padded to the correct length.

cnvB64Filter

Strips any invalid base64 characters from a string.

Syntax

[VBA]

Public Function cnvB64Filter ( _
    strB64 As String _
) As String

Parameters

strB64: String to be filtered.

Return Value

String: Filtered string.

cnvB64StrFromBytes

Encodes an array of bytes as a base64-encoded string.

Syntax

[VBA]

Public Function cnvB64StrFromBytes ( _
    abData() As Byte _
) As String

Parameters

abData: Input byte array.

Return Value

String: Base64-encoded string.

Remarks

Same as cnvToBase64.

cnvB64StrFromHexStr

Re-encodes a hexadecimal-encoded binary value as base64.

Syntax

[VBA]

Public Function cnvB64StrFromHexStr ( _
    strHex As String _
) As String

Parameters

strHex: Hex string representing a binary value.

Return Value

String: Binary value encoded in base64

cnvB64StrFromString

Encodes an ANSI string as a base64-encoded string.

Syntax

[VBA]

Public Function cnvB64StrFromString ( _
    strData As String _
) As String

Parameters

strData: String to be encoded.

Return Value

String: Base64-encoded string.

Remarks

Expecting a string of 8-bit "ANSI" characters.

cnvBytesFromB64Str

Decodes a base64-encoded string as an array of Bytes.

Syntax

[VBA]

Public Function cnvBytesFromB64Str ( _
    strB64 As String _
) As Byte()

Parameters

strB64: Base64 data to be decoded.

Return Value

Byte(): Array of bytes.

Remarks

Same as cnvFromBase64.

cnvBytesFromHexStr

Decodes a hexadecimal-encoded string as an array of Bytes.

Syntax

[VBA]

Public Function cnvBytesFromHexStr ( _
    strHex As String _
) As Byte()

Parameters

strHex: Hexadecimal data to be decoded.

Return Value

Byte(): Array of bytes.

Remarks

Same as cnvFromHex.

cnvBytesLen

Find length of byte array.

Syntax

[VBA]

Public Function cnvBytesLen ( _
    ab() As Byte _
) As Long

Parameters

ab: Input byte array.

Return Value

Long: Number of bytes in array.

Remarks

Safe to use even if array is empty.

Example

Dim ab() As Byte
Debug.Print cnvBytesLen(ab) ' Expecting 0
ReDim ab(10)    ' NB actually 11 elements (0..10)
Debug.Print cnvBytesLen(ab) ' 11
ab = vbNullString   ' Set to empty array
Debug.Print cnvBytesLen(ab) ' 0

cnvBytesMid

Return a substring of bytes of specified length from within a given byte array

Syntax

[VBA]

Public Function cnvBytesMid ( _
    Bytes() As Byte, _
    nOffset As Long, _
    Optional nBytes As Long = -1 _
) As Byte()

Parameters

Bytes: Byte array from which to return a substring (of bytes)
nOffset: Offset at which substring begins. First byte is at offset zero.
nBytes: Number of bytes in substring (optional). If negative, copy to end of input.

Return Value

Byte():

cnvFromBase64

Decodes a base64-encoded string as an array of bytes.

Syntax

[VBA]

Public Function cnvFromBase64 ( _
    strBase64 As String _
) As Byte()

Parameters

strBase64: Base64 data to be decoded.

Return Value

Byte(): Array of bytes.

Remarks

A shorter synonym for cnvBytesFromB64Str

cnvFromHex

Decodes a hexadecimal-encoded string as an array of bytes.

Syntax

[VBA]

Public Function cnvFromHex ( _
    strHex As String _
) As Byte()

Parameters

strHex: Hexadecimal-encoded data to be decoded.

Return Value

Byte(): Array of bytes.

Remarks

A shorter synonym for cnvBytesFromHexStr

cnvHexFilter

Strips any invalid hex characters from a hex string.

Syntax

[VBA]

Public Function cnvHexFilter ( _
    strHex As String _
) As String

Parameters

strHex: String to be filtered.

Return Value

String: Filtered string.

cnvHexFromBytesMid

Encodes a substring of an array of bytes as a hexadecimal-encoded string.

Syntax

[VBA]

Public Function cnvHexFromBytesMid ( _
    abData() As Byte, _
    nOffset As Long, _
    nBytes As Long _
) As String

Parameters

abData: Input byte array.
nOffset: Offset at which substring begins. First byte is at offset zero.
nBytes: Number of bytes in substring to encode.

Return Value

String: Hexadecimal-encoded string.

Example

Debug.Print cnvHexFromBytesMid(cnvBytesFromHexStr("00112233445566"), 3, 2) ' 3344

cnvHexStrFromB64Str

Re-encodes a base64-encoded binary value as hexadecimal.

Syntax

[VBA]

Public Function cnvHexStrFromB64Str ( _
    strB64 As String _
) As String

Parameters

strB64: Base64 string representing a binary value.

Return Value

String: Binary value encoded in hexadecimal

cnvHexStrFromBytes

Encodes an array of bytes as a hexadecimal-encoded string.

Syntax

[VBA]

Public Function cnvHexStrFromBytes ( _
    abData() As Byte _
) As String

Parameters

abData: Input byte array.

Return Value

String: Hexadecimal-encoded string.

Remarks

Same as cnvToHex.

cnvHexStrFromString

Encodes an ANSI string as a hexadecimal-encoded string.

Syntax

[VBA]

Public Function cnvHexStrFromString ( _
    strData As String _
) As String

Parameters

strData: String to be encoded.

Return Value

String: Hexadecimal-encoded string.

Remarks

Expecting a string of 8-bit "ANSI" characters.

cnvStringFromHexStr

Decodes a hexadecimal-encoded string as an ANSI string.

Syntax

[VBA]

Public Function cnvStringFromHexStr ( _
    ByVal strHex As String _
) As String

Parameters

strHex: Hexadecimal data to be decoded.

Return Value

String: Decoded string. For example, "6162632E" will be converted to "abc."

Remarks

Output is a string of "ANSI" characters of value between 0 and 255.

cnvToBase64

Encodes an array of bytes as a base64-encoded string.

Syntax

[VBA]

Public Function cnvToBase64 ( _
    lpData() As Byte _
) As String

Parameters

lpData: Input byte array

Return Value

String: Base64-encoded string

Remarks

A shorter synonym for cnvB64StrFromBytes

cnvToHex

Encodes an array of bytes as a hexadecimal-encoded string.

Syntax

[VBA]

Public Function cnvToHex ( _
    lpData() As Byte _
) As String

Parameters

lpData: Input byte array

Return Value

String: Hexadecimal-encoded string

Remarks

A shorter synonym for cnvHexStrFromBytes

comprCompress

Compress data using compression algorithm.

Syntax

[VBA]

Public Function comprCompress ( _
    lpInput() As Byte, _
    Optional nOptions As Long = API_COMPR_ZLIB _
) As Byte()

Parameters

lpInput

Data to be compressed.

nOptions

Compression algorithm to be used. Select one from:

API_COMPR_ZLIB (0)
API_COMPR_ZSTD

Return Value

Byte(): Compressed data, or an empty array on error.

comprUncompress

Uncompress data using compression algorithm.

Syntax

[VBA]

Public Function comprUncompress ( _
    lpInput() As Byte, _
    Optional nOptions As Long = API_COMPR_ZLIB _
) As Byte()

Parameters

lpInput

Data to be uncompressed.

nOptions

Compression algorithm to be used. Select one from:

API_COMPR_ZLIB (0)
API_COMPR_ZSTD

Return Value

Byte(): Uncompressed data, or an empty array on error.

crcBytes

Compute the CRC-32 checksum of an array of bytes.

Syntax

[VBA]

Public Function crcBytes ( _
    lpInput() As Byte _
) As Long

Parameters

lpInput: Input data.

Return Value

Long: CRC-32 checksum as a 32-bit integer value.

crcFile

Compute the CRC-32 checksum of a file.

Syntax

[VBA]

Public Function crcFile ( _
    szFileName As String _
) As Long

Parameters

szFileName: Name of input file.

Return Value

Long: CRC-32 checksum as a 32-bit integer value.

crcString

Compute the CRC-32 checksum of an ANSI string.

Syntax

[VBA]

Public Function crcString ( _
    szInput As String _
) As Long

Parameters

szInput: Input data.

Return Value

Long: CRC-32 checksum as a 32-bit integer value.

errFormatErrorMessage

Return an error message string for the last error.

Syntax

[VBA]

Public Function errFormatErrorMessage ( _
    Optional nErrCode As Long = 0, _
    Optional szMsg As String = "" _
) As String

Parameters

nErrCode: Error code returned by last call.
szMsg: Optional message to add.

Return Value

String: Error message as a string including previous ErrorCode, if available.

Example

Error (11): Parameter out of range (RANGE_ERROR)

hashAddBytes

Add an array of bytes to be digested.

Syntax

[VBA]

Public Function hashAddBytes ( _
    hContext As Long, _
    lpData() As Byte _
) As Long

Parameters

hContext: Handle to the HASH context.
lpData: Byte array containing the next part of the message.

Return Value

Long: Zero (0) on success, or a nonzero error code (use apiErrorLookup to check)

hashAddString

Add a string to be digested.

Syntax

[VBA]

Public Function hashAddString ( _
    hContext As Long, _
    szData As String _
) As Long

Parameters

hContext: Handle to the HASH context.
szData: String containing the next part of the message.

Return Value

Long: Zero (0) on success, or a nonzero error code (use apiErrorLookup to check)

hashBytes

Compute hash digest in byte format of byte input.

Syntax

[VBA]

Public Function hashBytes ( _
    lpMessage() As Byte, _
    nOptions As Long _
) As Byte()

Parameters

lpMessage

Message to be digested in byte array.

nOptions

Algorithm to be used. Select one from:

API_HASH_SHA1
API_HASH_SHA224
API_HASH_SHA256
API_HASH_SHA384
API_HASH_SHA512
API_HASH_SHA3_224
API_HASH_SHA3_256
API_HASH_SHA3_384
API_HASH_SHA3_512
API_HASH_MD5
API_HASH_MD2
API_HASH_RMD160
API_HASH_ASCON_HASH
API_HASH_ASCON_HASHA

Return Value

Byte(): Message digest in byte array.

hashFile

Compute hash digest in byte format of a file.

Syntax

[VBA]

Public Function hashFile ( _
    szFileName As String, _
    nOptions As Long _
) As Byte()

Parameters

szFileName

Name of file containing message data.

nOptions

Algorithm to be used. Select one from:

API_HASH_SHA1
API_HASH_SHA224
API_HASH_SHA256
API_HASH_SHA384
API_HASH_SHA512
API_HASH_SHA3_224
API_HASH_SHA3_256
API_HASH_SHA3_384
API_HASH_SHA3_512
API_HASH_MD5
API_HASH_MD2
API_HASH_RMD160

Add API_HASH_MODE_TEXT to hash in "text" mode instead of default "binary" mode.

Return Value

Byte(): Message digest in byte array.

Remarks

The default mode is "binary" where each byte is treated individually. In "text" mode CR-LF pairs will be treated as a single newline (LF) character.

hashFinal

Return the final message digest value.

Syntax

[VBA]

Public Function hashFinal ( _
    hContext As Long _
) As Byte()

Parameters

hContext: Handle to the HASH context.

Return Value

Byte(): Digest in byte array or empty array on error.

Remarks

Computes the result of all hashAddBytes and hashAddString calls since HASH_Init.

hashHexFromBits

Compute hash digest in hex format from bit-oriented input.

Syntax

[VBA]

Public Function hashHexFromBits ( _
    lpData() As Byte, _
    nDataBitLen As Long, _
    nOptions As Long _
) As String

Parameters

lpData

Bit-oriented message data in byte array.

nDataBitLen

length of the message data in bits.

nOptions

Algorithm to be used. Select one from:

API_HASH_SHA1
API_HASH_SHA224
API_HASH_SHA256
API_HASH_SHA384
API_HASH_SHA512
API_HASH_SHA3_224
API_HASH_SHA3_256
API_HASH_SHA3_384
API_HASH_SHA3_512

Return Value

String: Message digest in hex-encoded format.

Remarks

Only the SHA family of hash functions is supported in bit-oriented mode. Pass a bitstring as an array of bytes in lpData in big-endian order with the most-significant bit first. The bitstring will be truncated to the number of bits specified in nDataBitLen and extraneous bits on the right will be ignored.

Example

' NIST SHAVS CAVS 11.0 "SHA-1 ShortMsg" information
lpData = cnvBytesFromHexStr("5180")  ' 9-bit bitstring = 0101 0001 1
strDigest = hashHexFromBits(lpData, 9, API_HASH_SHA1)
Debug.Print "MD = " & strDigest
Debug.Print "OK = 0f582fa68b71ecdf1dcfc4946019cf5a18225bd2"

hashHexFromBytes

Compute hash digest in hex format of byte input.

Syntax

[VBA]

Public Function hashHexFromBytes ( _
    lpMessage() As Byte, _
    nOptions As Long _
) As String

Parameters

lpMessage

Message to be digested in byte array.

nOptions

Algorithm to be used. Select one from:

API_HASH_SHA1
API_HASH_SHA224
API_HASH_SHA256
API_HASH_SHA384
API_HASH_SHA512
API_HASH_SHA3_224
API_HASH_SHA3_256
API_HASH_SHA3_384
API_HASH_SHA3_512
API_HASH_MD5
API_HASH_MD2
API_HASH_RMD160
API_HASH_ASCON_HASH
API_HASH_ASCON_HASHA

Return Value

String: Message digest in hex-encoded format.

hashHexFromFile

Compute hash digest in hex format of a file.

Syntax

[VBA]

Public Function hashHexFromFile ( _
    szFileName As String, _
    nOptions As Long _
) As String

Parameters

szFileName

Name of file containing message data.

nOptions

Algorithm to be used. Select one from:

API_HASH_SHA1
API_HASH_SHA224
API_HASH_SHA256
API_HASH_SHA384
API_HASH_SHA512
API_HASH_SHA3_224
API_HASH_SHA3_256
API_HASH_SHA3_384
API_HASH_SHA3_512
API_HASH_MD5
API_HASH_MD2
API_HASH_RMD160

Add API_HASH_MODE_TEXT to hash in "text" mode instead of default "binary" mode.

Return Value

String: Message digest in hex-encoded format.

Remarks

The default mode is "binary" where each byte is treated individually. In "text" mode CR-LF pairs will be treated as a single newline (LF) character.

hashHexFromHex

Compute hash digest in hex-encoded format from hex-encoded input.

Syntax

[VBA]

Public Function hashHexFromHex ( _
    szMsgHex As String, _
    nOptions As Long _
) As String

Parameters

szMsgHex

Message to be digested in hex-encoded format.

nOptions

Algorithm to be used. Select one from:

API_HASH_SHA1
API_HASH_SHA224
API_HASH_SHA256
API_HASH_SHA384
API_HASH_SHA512
API_HASH_SHA3_224
API_HASH_SHA3_256
API_HASH_SHA3_384
API_HASH_SHA3_512
API_HASH_MD5
API_HASH_MD2
API_HASH_RMD160
API_HASH_ASCON_HASH
API_HASH_ASCON_HASHA

Return Value

String: Message digest in hex-encoded format.

hashHexFromString

Compute hash digest in hex-encoded format from hex-encoded input.

Syntax

[VBA]

Public Function hashHexFromString ( _
    szMessage As String, _
    nOptions As Long _
) As String

Parameters

szMessage

Message data string.

nOptions

Algorithm to be used. Select one from:

API_HASH_SHA1
API_HASH_SHA224
API_HASH_SHA256
API_HASH_SHA384
API_HASH_SHA512
API_HASH_SHA3_224
API_HASH_SHA3_256
API_HASH_SHA3_384
API_HASH_SHA3_512
API_HASH_MD5
API_HASH_MD2
API_HASH_RMD160
API_HASH_ASCON_HASH
API_HASH_ASCON_HASHA

Return Value

String: Message digest in hex-encoded format.

hashInit

Initialise the HASH context ready for incremental operations.

Syntax

[VBA]

Public Function hashInit ( _
    Optional nAlg As Long = 0 _
) As Long

Parameters

nAlg

Algorithm to be used. Select one from:

API_HASH_SHA1
API_HASH_SHA224
API_HASH_SHA256
API_HASH_SHA384
API_HASH_SHA512
API_HASH_SHA3_224
API_HASH_SHA3_256
API_HASH_SHA3_384
API_HASH_SHA3_512

Return Value

Long: Nonzero handle of the HASH context, or zero if an error occurs.

Remarks

Only the SHA-1, SHA-2 and SHA-3 families of hash algorithms are supported in incremental mode. While the context handle is valid, add data to be digested in blocks of any length using hashAddBytes or hashAddString.

hashLength

Return length of message digest output in bytes.

Syntax

[VBA]

Public Function hashLength ( _
    nAlgId As Long _
) As Long

Parameters

nAlgId

Algorithm Id flag. Select one of API_HASH_* or API_HMAC_*, for example:

API_HASH_SHA1
API_HASH_SHA224
API_HASH_SHA256
API_HASH_SHA384
API_HASH_SHA512
API_HASH_SHA3_224
API_HASH_SHA3_256
API_HASH_SHA3_384
API_HASH_SHA3_512
API_HASH_MD5
API_HASH_MD2
API_HASH_RMD160
API_HASH_ASCON_HASH
API_HASH_ASCON_HASHA

Return Value

Long: Length of the hash function output in bytes; else a negative error code.

Example

Debug.Print hashLength(API_HASH_SHA512)
64

macAddBytes

Adds an array of bytes to be authenticated.

Syntax

[VBA]

Public Function macAddBytes ( _
    hContext As Long, _
    lpData() As Byte _
) As Long

Parameters

hContext: Handle to the MAC context.
lpData: Byte array containing the next part of the message.

Return Value

Long: Zero (0) on success, or a nonzero error code (use apiErrorLookup to check)

macAddString

Adds a string to be authenticated.

Syntax

[VBA]

Public Function macAddString ( _
    hContext As Long, _
    szData As String _
) As Long

Parameters

hContext: Handle to the MAC context.
szData: String containing the next part of the message.

Return Value

Long: Zero (0) on success, or a nonzero error code (use apiErrorLookup to check)

macBytes

Computes a keyed MAC in byte format from byte input.

Syntax

[VBA]

Public Function macBytes ( _
    lpMessage() As Byte, _
    lpKey() As Byte, _
    nOptions As Long _
) As Byte()

Parameters

lpMessage

Message to be signed in byte format.

lpKey

Key in byte format.

nOptions

Algorithm to be used. Select one from:

API_HMAC_SHA1
API_HMAC_SHA224
API_HMAC_SHA256
API_HMAC_SHA384
API_HMAC_SHA512
API_HMAC_MD5
API_HMAC_RMD160
API_HMAC_SHA3_224
API_HMAC_SHA3_256
API_HMAC_SHA3_384
API_HMAC_SHA3_512
API_CMAC_TDEA
API_CMAC_AES128
API_CMAC_AES192
API_CMAC_AES256
API_MAC_POLY1305
API_KMAC_128
API_KMAC_256

Return Value

Byte(): MAC value in hex-encoded format.

macFinal

Returns the final MAC value.

Syntax

[VBA]

Public Function macFinal ( _
    hContext As Long _
) As Byte()

Parameters

hContext: Handle to the MAC context.

Return Value

Byte(): MAC in byte array or empty array on error.

Remarks

Computes the result of all macAddBytes and macAddString calls since macInit.

macHexFromBytes

Computes a keyed MAC in hex-encoded format from byte input.

Syntax

[VBA]

Public Function macHexFromBytes ( _
    lpMessage() As Byte, _
    lpKey() As Byte, _
    nOptions As Long _
) As String

Parameters

lpMessage

Message to be signed in byte format.

lpKey

Key in byte format.

nOptions

Algorithm to be used. Select one from:

API_HMAC_SHA1
API_HMAC_SHA224
API_HMAC_SHA256
API_HMAC_SHA384
API_HMAC_SHA512
API_HMAC_MD5
API_HMAC_RMD160
API_HMAC_SHA3_224
API_HMAC_SHA3_256
API_HMAC_SHA3_384
API_HMAC_SHA3_512
API_CMAC_TDEA
API_CMAC_AES128
API_CMAC_AES192
API_CMAC_AES256
API_MAC_POLY1305
API_KMAC_128
API_KMAC_256

Return Value

String: MAC value in hex-encoded format.

macHexFromHex

Computes a keyed MAC in hex-encoded format from hex-encoded input.

Syntax

[VBA]

Public Function macHexFromHex ( _
    szMsgHex As String, _
    szKeyHex As String, _
    nOptions As Long _
) As String

Parameters

szMsgHex

Message to be signed in hex-encoded format.

szKeyHex

Key in hex-encoded format.

nOptions

Algorithm to be used. Select one from:

API_HMAC_SHA1
API_HMAC_SHA224
API_HMAC_SHA256
API_HMAC_SHA384
API_HMAC_SHA512
API_HMAC_MD5
API_HMAC_RMD160
API_HMAC_SHA3_224
API_HMAC_SHA3_256
API_HMAC_SHA3_384
API_HMAC_SHA3_512
API_CMAC_TDEA
API_CMAC_AES128
API_CMAC_AES192
API_CMAC_AES256
API_MAC_POLY1305
API_KMAC_128
API_KMAC_256

Return Value

String: MAC value in hex-encoded format.

macInit

Initialises the MAC context ready to receive data to authenticate.

Syntax

[VBA]

Public Function macInit ( _
    lpKey() As Byte, _
    nAlg As Long _
) As Long

Parameters

lpKey

Key in byte format.

nAlg

Algorithm to be used. Select one from:

API_HMAC_SHA1
API_HMAC_SHA224
API_HMAC_SHA256
API_HMAC_SHA384
API_HMAC_SHA512

Return Value

Long: Nonzero handle of the MAC context, or zero if an error occurs.

Remarks

Once initialized, use the context for subsequent calls to macAddBytes, macAddString and macFinal.

padBytesBlock

Creates an input block suitably padded for encryption by a block cipher in ECB or CBC mode.

Syntax

[VBA]

Public Function padBytesBlock ( _
    lpInput() As Byte, _
    nBlkLen As Long, _
    Optional nOptions As Long = 0 _
) As Byte()

Parameters

lpInput

Plaintext bytes to be padded.

nBlkLen

Cipher block length in bytes (8 or 16).

nOptions

Use 0 for default PKCS5 padding or select one of:

API_PAD_1ZERO
API_PAD_AX923
API_PAD_W3C

Return Value

Byte(): Padded data in byte array.

padHexBlock

Creates a hex-encoded input block suitably padded for encryption by a block cipher in ECB or CBC mode.

Syntax

[VBA]

Public Function padHexBlock ( _
    szInput As String, _
    nBlkLen As Long, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szInput

Hexadecimal-encoded data to be padded.

nBlkLen

Cipher block length in bytes (8 or 16).

nOptions

Use 0 for default PKCS5 padding or select one of:

API_PAD_1ZERO
API_PAD_AX923
API_PAD_W3C

Return Value

String: Padded data in byte array.

padHexString

Add PKCS5 padding to a hex string up to next multiple of block length [DEPRECATED].

Syntax

[VBA]

Public Function padHexString ( _
    ByVal strInputHex As String, _
    nBlockLen As Long _
) As String

Parameters

strInputHex: Hexadecimal-encoded data to be padded.
nBlockLen: Cipher block length in bytes (8 or 16).

Return Value

String: Padded hex string or empty string on error.

Deprecated

Use padHexBlock().

padUnpadBytes

Removes the padding from an encryption block.

Syntax

[VBA]

Public Function padUnpadBytes ( _
    lpInput() As Byte, _
    nBlkLen As Long, _
    Optional nOptions As Long = 0 _
) As Byte()

Parameters

lpInput

Padded data.

nBlkLen

Cipher block length in bytes (8 or 16).

nOptions

Use 0 for default PKCS5 padding or select one of:

API_PAD_1ZERO
API_PAD_AX923
API_PAD_W3C

Return Value

Byte(): Unpadded data in byte array or unchanged data on error.

Remarks

An error is indicated by returning the original data which will always be longer than the expected unpadded result.

padUnpadHex

Removes the padding from a hex-encoded encryption block.

Syntax

[VBA]

Public Function padUnpadHex ( _
    szInput As String, _
    nBlkLen As Long, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szInput

Hex-encoded padded data.

nBlkLen

Cipher block length in bytes (8 or 16).

nOptions

Use 0 for default PKCS5 padding or select one of:

API_PAD_1ZERO
API_PAD_AX923
API_PAD_W3C

Return Value

String: Unpadded data in hex-encoded string or unchanged data on error.

Remarks

An error is indicated by returning the original data which will always be longer than the expected unpadded result.

pbeKdf2

Derives a key of any length from a password using the PBKDF2 algorithm from PKCS#5 v2.1.

Syntax

[VBA]

Public Function pbeKdf2 ( _
    dkBytes As Long, _
    lpPwd() As Byte, _
    lpSalt() As Byte, _
    nCount As Long, _
    nOptions As Long _
) As Byte()

Parameters

dkBytes

Required length of key in bytes.

lpPwd

Password encoded as byte array.

lpSalt

Salt in a byte array.

nCount

Iteration count.

nOptions

Hash algorithm to use in HMAC PRF. Select one from:

API_HMAC_SHA1
API_HMAC_SHA224
API_HMAC_SHA256
API_HMAC_SHA384
API_HMAC_SHA512
API_HMAC_MD5

Return Value

Byte(): Key in byte array.

pbeKdf2Hex

Derives a hex-encoded key of any length from a password using the PBKDF2 algorithm from PKCS#5 v2.1. The salt and derived key are encoded in hexadecimal.

Syntax

[VBA]

Public Function pbeKdf2Hex ( _
    dkBytes As Long, _
    szPwd As String, _
    szSaltHex As String, _
    nCount As Long, _
    nOptions As Long _
) As String

Parameters

dkBytes

Required length of key in bytes.

szPwd

Password (as normal text).

szSaltHex

Salt in hex-encoded format.

nCount

Iteration count.

nOptions

Hash algorithm to use in HMAC PRF. Select one from:

API_HMAC_SHA1
API_HMAC_SHA224
API_HMAC_SHA256
API_HMAC_SHA384
API_HMAC_SHA512
API_HMAC_MD5

Return Value

String: Key in hex format.

pbeScrypt

Derives a key of any length from a password using the SCRYPT algorithm from RFC7914.

Syntax

[VBA]

Public Function pbeScrypt ( _
    dkBytes As Long, _
    lpPwd() As Byte, _
    lpSalt() As Byte, _
    nParamN As Long, _
    nParamR As Long, _
    nParamP As Long, _
    Optional nOptions As Long = 0 _
) As Byte()

Parameters

dkBytes: Required length of key in bytes.
lpPwd: Password encoded as byte array.
lpSalt: Salt in a byte array.
nParamN: CPU/Memory cost parameter N ("costParameter"), a number greater than one and a power of 2.
nParamR: Block size r ("blockSize").
nParamP: Parallelization parameter p ("parallelizationParameter").
nOptions: For future use.

Return Value

Byte(): Key in byte array.

pbeScryptHex

Derives a hex-encoded key of any length from a password using the SCRYPT algorithm from RFC7914. The salt and derived key are encoded in hexadecimal.

Syntax

[VBA]

Public Function pbeScryptHex ( _
    dkBytes As Long, _
    szPwd As String, _
    szSaltHex As String, _
    nParamN As Long, _
    nParamR As Long, _
    nParamP As Long, _
    Optional nOptions As Long = 0 _
) As String

Parameters

dkBytes: Required length of key in bytes.
szPwd: Password (as normal text).
szSaltHex: Salt in hex-encoded format.
nParamN: CPU/Memory cost parameter N ("costParameter"), a number greater than one and a power of 2.
nParamR: Block size r ("blockSize").
nParamP: Parallelization parameter p ("parallelizationParameter").
nOptions: For future use.

Return Value

String: Key in hex format.

Example

Debug.Print pbeScryptHex(64, "password", "4E61436C", 1024, 8, 16)
' FDBABE1C9D3472007856E7190D01E9FE7C6AD7CBC8237830E77376634B3731622EAF30D92E22A3886FF109279D9830DAC727AFB94A83EE6D8360CBDFA2CC0640

prfBytes

Generate output bytes using a pseudorandom function (PRF).

Syntax

[VBA]

Public Function prfBytes ( _
    nBytes As Long, _
    lpMessage() As Byte, _
    lpKey() As Byte, _
    nOptions As Long, _
    Optional szCustom As String = "" _
) As Byte()

Parameters

nBytes

Required number of output bytes.

lpMessage

Input message data.

lpKey

Key (expected 128 or 256 bits long).

nOptions

PRF function to be used. Select one from:

API_KMAC_128
API_KMAC_256

szCustom

Customization string (optional).

Return Value

Byte(): Output data in byte array.

Remarks

The KMAC128 and KMAC256 PRF functions are described in NIST SP800-185 (SHA-3 Derived Functions), and use SHAKE128 and SHAKE256, respectively. Note different order of parameters from core function.

rngInitialize

Initialize the RNG generator using a seed file.

Syntax

[VBA]

Public Function rngInitialize ( _
    szSeedFile As String _
) As Long

Parameters

szSeedFile: Full path name of seed file. If the seed file does not exist, it will be created using any available entropy.

Return Value

Long: Zero if successful.

rngInitializeEx

Query and initialize the RNG generator using Intel(R) DRNG, if available.

Syntax

[VBA]

Public Function rngInitializeEx ( _
    Optional nOptions As Long = 0 _
) As Long

Parameters

nOptions: Specify API_RNG_NO_INTEL_DRNG to explicitly turn off support.

Return Value

Long: Support status for Intel(R) DRNG. If available, then returns a positive value (1,2,3); else a negative error code.

rngKeyBytes

Generate a random key value.

Syntax

[VBA]

Public Function rngKeyBytes ( _
    nBytes As Long, _
    Optional szSeed As String = "" _
) As Byte()

Parameters

nBytes: Required number of random bytes.
szSeed: User-supplied entropy in string format (optional).

Return Value

Byte(): Array of random bytes.

rngKeyHex

Generate a random key in hex format.

Syntax

[VBA]

Public Function rngKeyHex ( _
    nBytes As Long, _
    Optional szSeed As String = "" _
) As String

Parameters

nBytes: Required number of random bytes.
szSeed: User-supplied entropy in string format (optional).

Return Value

String: Random bytes in hex format.

rngNonce

Generate a random nonce.

Syntax

[VBA]

Public Function rngNonce ( _
    nBytes As Long _
) As Byte()

Parameters

nBytes: Required number of random bytes.

Return Value

Byte(): Array of random bytes.

rngNonceHex

Generate a hex-encoded sequence of bytes.

Syntax

[VBA]

Public Function rngNonceHex ( _
    nBytes As Long _
) As String

Parameters

nBytes: Required number of random bytes.

Return Value

String: Hex-encoded random bytes.

unpadHexString

Strips PKCS5 padding from a hex string [DEPRECATED].

Syntax

[VBA]

Public Function unpadHexString ( _
    strInputHex As String, _
    nBlockLen As Long _
) As String

Parameters

strInputHex: Hexadecimal-encoded padded data.
nBlockLen: Cipher block length in bytes (8 or 16).

Return Value

String: Unpadded data in hex string or unchanged data on error.

Remarks

An error is indicated by returning the original data which will always be longer than the expected unpadded result.

Deprecated

Use padUnpadHex.

wipeBytes

Zeroise data in memory.

Syntax

[VBA]

Public Function wipeBytes ( _
    lpData() As Byte _
) As Long

Parameters

lpData: Data to be wiped.

Return Value

Long: Zero (0) on success, or a nonzero error code (use apiErrorLookup to check).

Remarks

This function does not free any memory; it just zeroises it.

wipeFile

Securely wipes and deletes a file using 7-pass DOD standards.

Syntax

[VBA]

Public Function wipeFile ( _
    szFileName As String, _
    Optional nOptions As Long = 0 _
) As Long

Parameters

szFileName

File to be deleted.

nOptions

Option flags. Select one of

API_WIPEFILE_DOD7 (0)
API_WIPEFILE_SIMPLE

Return Value

Long: Zero (0) on success, or a nonzero error code (use apiErrorLookup to check).

Remarks

The default option uses the 7-pass DOD Standard according to [NISPOM] before deleting. API_WIPEFILE_SIMPLE overwrites the file with a single pass of zero bytes (quicker but less secure).

wipeString

Zeroise a string.

Syntax

[VBA]

Public Function wipeString ( _
    szData As String _
) As String

Parameters

szData: String to be wiped.

Return Value

String: An empty string.

Remarks

On its own this just zeroizes the string. To clear the string securely, do the following

strData = wipeString(strData)

xofBytes

Generate bytes using an extendable-output function (XOF).

Syntax

[VBA]

Public Function xofBytes ( _
    nBytes As Long, _
    lpMessage() As Byte, _
    nOptions As Long _
) As Byte()

Parameters

nBytes

Required number of output bytes.

lpMessage

Input message data.

nOptions

XOF algorithm to be used. Select one from:

API_XOF_SHAKE128
API_XOF_SHAKE256
API_XOF_MGF1_SHA1
API_XOF_MGF1_SHA256
API_XOF_MGF1_SHA512
API_XOF_ASCON_XOF
API_XOF_ASCON_XOFA

Return Value

Byte(): Output data in byte array.

zlibDeflate

Compress data using the ZLIB deflate algorithm.

Syntax

[VBA]

Public Function zlibDeflate ( _
    lpInput() As Byte _
) As Byte()

Parameters

lpInput: Data to be compressed.

Return Value

Byte(): Compressed data.

zlibInflate

Inflate compressed data using the ZLIB algorithm.

Syntax

[VBA]

Public Function zlibInflate ( _
    lpInput() As Byte _
) As Byte()

Parameters

lpInput: Compressed data to be inflated.

Return Value

Byte(): Uncompressed data, or an empty array on error.

Remarks

An empty array may also be returned in the trivial case where the original data was the empty array itself.

Index

Functions