CryptoSys PKI 22.1.0

Functions

asn1TextDumpToString

Dump details of ASN.1 formatted data to a string. More...

asn1Type

Describe the type of ASN.1 data. More...

cipherDecryptAEAD

Decrypt data using Authenticated Encryption with Associated Data (AEAD). 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...

cipherEncryptAEAD

Encrypt data using Authenticated Encryption with Associated Data (AEAD). More...

cipherEncryptBytes

Encrypt 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. More...

cipherFileEncrypt

Encrypt a file. More...

cipherKeyUnwrap

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

cipherKeyWrap

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

cmsGetSigDataDigest

Extract the message digest from a signed-data CMS object file and verify the signature. More...

cmsMakeEnvData

Create a CMS enveloped-data object for one or more recipients. More...

cmsMakeEnvDataFromBytes

Create a CMS enveloped-data object from data in a byte array. More...

cmsMakeEnvDataFromString

Create a CMS enveloped-data object from an ASCII string. More...

cmsMakeSigDataFromBytes

Create a CMS signed-data object from data in a byte array. More...

cmsMakeSigDataFromSigValue

Create a CMS signed-data object using a pre-computed signature value. More...

cmsQueryEnvData

Query a CMS enveloped-data object file for selected information. More...

cmsQuerySigData

Query a CMS signed-data object file for selected information. More...

cmsReadEnvDataToBytes

Read and decrypt a CMS enveloped-data object to a byte array. More...

cmsReadEnvDataToString

Read and decrypt a CMS enveloped-data object to a string. More...

cmsReadSigDataToBytes

Read the content from a CMS signed-data object directly into a byte array. More...

cmsReadSigDataToString

Read the content from a CMS signed-data object directly into a string. More...

cmsVerifySigData

Verify the signature and content of a signed-data CMS object file. More...

cnvB64Filter

Strip any invalid base64 characters from a string. More...

cnvB64StrFromBytes

Encode an array of bytes as a base64-encoded string. More...

cnvB64StrFromHexStr

Re-encode a hexadecimal-encoded binary value as base64. More...

cnvB64StrFromString

Encode an ANSI string as a base64-encoded string. More...

cnvBase58FromBytes

Convert 8-bit binary data to equivalent base58-encoded string format. More...

cnvBase58ToBytes

Convert a base58-encoded string to an equivalent array of 8-bit unsigned integers. More...

cnvByteEncoding

Convert encoding of byte array between UTF-8 and Latin-1. More...

cnvBytesFromB64Str

Decode a base64-encoded string as an array of Bytes. More...

cnvBytesFromHexStr

Decode 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...

cnvCheckUTF8Bytes

Check if a byte array contains valid UTF-8 characters. 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

Strip any invalid hex characters from a hex string. More...

cnvHexFromBytesMid

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

cnvHexStrFromB64Str

Re-encode a base64-encoded binary value as hexadecimal. More...

cnvHexStrFromBytes

Encode an array of bytes as a hexadecimal-encoded string. More...

cnvHexStrFromString

Encode an ANSI string as a hexadecimal-encoded string. More...

cnvLatin1FromUTF8Bytes

Convert UTF-8 encoded array of bytes into a Latin-1 string, if possible. More...

cnvNumFromBytes

Convert the leftmost four bytes of an array to a 32-bit integer. More...

cnvNumToBytes

Convert a 32-bit integer to an array of 4 bytes. More...

cnvReverseBytes

Reverse the order of a byte array. More...

cnvStringFromHexStr

Decode 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...

cnvUTF8BytesFromLatin1

Convert a string of 8-bit Latin-1 (ISO-8859-1) characters into a UTF-8 encoded array of bytes. More...

comprCompress

Compress data using zlib compression. More...

comprUncompress

Uncompress data using zlib compression. More...

eccDHSharedSecret

Compute EC Diffie-Hellman (ECDH) shared secret. More...

eccKeyHashCode

Compute the hash code of an "internal" ECC public or private key string. More...

eccMakeKeys

Generate an EC public/private key pair and save as two key files. More...

eccPublicKeyFromPrivate

Convert an internal EC private key string into an internal EC public key string. More...

eccQueryKey

Query an EC key string for selected information. More...

eccReadKeyByCurve

Read an EC key from its hexadecimal representation. More...

eccReadPrivateKey

Read an EC private key from a file into an internal key string. More...

eccReadPublicKey

Read an EC private key from a file into an internal key string. More...

eccSaveEncKey

Save an internal EC private key string to an encrypted key file. More...

eccSaveKey

Save an internal EC key string to a key file. More...

errFormatErrorMessage

Return an error message string for the last error. More...

hashBytes

Compute hash digest in byte format of byte input. More...

hashFile

Compute hash digest in byte format of a file. 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...

hashLength

Return length of message digest output in bytes. More...

hmacBytes

Compute hash-based message authentication code (HMAC) as a byte array from byte data. More...

hmacHexFromBytes

Compute hash-based message authentication code (HMAC) in hexadecimal format from byte data. More...

hmacHexFromHex

Compute hash-based message authentication code (HMAC) in hexadecimal format from data in hexadecimal-encoded strings. More...

hpkeDerivePrivateKey

Derive an EC private key in a deterministic manner from input keying material using the DeriveKeyPair algorithm in RFC9180. More...

hpkeLabeledExpand

Compute the output of the LabeledExpand function as defined in RFC9180. More...

hpkeLabeledExtract

Compute the output of the LabeledExtract function as defined in RFC9180. More...

kdfBytes

Generate a key-encryption key (KEK) from input keying material (IKM) using a key derivation function (KDF). More...

kdfForCms

Generate a key-encryption key (KEK) for ECDH key exchange in a CMS EnvelopedData object. More...

ocspMakeRequest

Create an Online Certification Status Protocol (OCSP) request as a base64 string. More...

ocspReadResponse

Read a response to an Online Certification Status Protocol (OCSP) request and outputs the main results in text form. 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...

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...

pfxMakeFile

Create a PFX (PKCS-12) file from an X.509 certificate and (optional) encrypted private key file. More...

pkiCompileTime

Get date and time the CryptoSys PKI DLL module was last compiled. More...

pkiErrorCode

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

pkiErrorLookup

Get error message associated with a given error code. More...

pkiLastError

Get last error message set by previous function. More...

pkiLicenceType

Returns the ASCII value of the licence type. More...

pkiModuleInfo

Get additional information about the core DLL module. More...

pkiModuleName

Get path name of the current process's module. More...

pkiPlatform

Get platform the core DLL was compiled for. More...

pkiVersion

Get version number of native core DLL. More...

prfBytes

Generate output bytes using a pseudorandom function (PRF). More...

pwdPrompt

Prompt for a password in a dialog box. More...

rngBytes

Generate random bytes. More...

rngGuid

Generate a random 36-character Global Unique IDentifier (GUID) string. 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...

rsaDecodeMsg

Decode an EME or EMSA encoded message block according to PKCS#1. More...

rsaDecrypt

Decrypt a message encrypted using an RSA encryption scheme. More...

rsaEncodeMsg

Encode an EME or EMSA encoded message block according to PKCS#1. More...

rsaEncrypt

Encrypt a short message using RSA encryption. More...

rsaFromXMLString

Create an RSA key string in internal format from an XML string. More...

rsaKeyBits

Get number of significant bits in RSA key modulus. More...

rsaKeyBytes

Get number of bytes (octets) in RSA key modulus. More...

rsaKeyValue

Extract a base64-encoded RSA key value from internal key string. More...

rsaMakeKeys

Generate an RSA public/private key pair and save as two key files. More...

rsaPublicKeyFromPrivate

Convert an internal RSA private key string into an internal public key string. More...

rsaRawPrivate

Carry out RSA transformation on raw data using private key. More...

rsaRawPublic

Carry out RSA transformation on raw data using public key. More...

rsaReadAnyPrivateKey

Read private key from a file or string containing a key into an "internal" public key string. More...

rsaReadAnyPublicKey

Read public key from a file or string containing a key into an "internal" public key string. More...

rsaReadPrivateKey

Read private key from a file or string containing a key into an "internal" public key string. More...

rsaReadPublicKey

Read public key from a file or string containing a key into an "internal" public key string. More...

rsaSaveEncKey

Save an internal RSA key string to an encrypted key file. More...

rsaSaveKey

Save an internal RSA key string to a key file. More...

rsaToXMLString

Create an XML string representation of an RSA internal key string. More...

rsaToXMLStringEx

Create an XML string representation of an RSA internal key string with option to add a namespace prefix. More...

sigSignData

Compute a signature value over data in a byte array. More...

sigSignFile

Compute a signature value over data in a file. More...

sigVerifyData

Verify a signature value over data in a byte array. More...

smimeQuery

Query an S/MIME entity for selected information. More...

wipeBytes

Wipe a byte array securely. More...

wipeString

Wipe a string securely and return an empty string. More...

x509CertThumb

Calculate the thumbprint (message digest value) of an X.509 certificate. More...

x509HashIssuerAndSN

Calculate the message digest hash of the PKCS #7 issuerAndSerialNumber value of an X.509 certificate. More...

x509QueryCert

Query an X.509 certificate file for selected information. More...

x509ReadCertStringFromP7Chain

Read an X.509 certificate into a base64-encoded string from PKCS-7 "certs-only" data. More...

x509ReadCertStringFromPFX

Read an X.509 certificate into a base64-encoded string from PKCS-12 PFX/.p12 data. More...

x509ReadStringFromFile

Read an X.509 certificate into a base64-encoded string. More...

x509TextDumpToString

Dump details of an X.509 certificate or a X.509 certificate revocation list (CRL) or a PKCS-10 certificate signing request (CSR) to a string. More...

xofBytes

Generate bytes using an eXtendable-Output Function (XOF). More...

Function Descriptions

asn1TextDumpToString

Dump details of ASN.1 formatted data to a string.

Syntax

Public Function asn1TextDumpToString ( _
    szFileOrPEMString As String, _
    Optional nOptions As Long = 0, _
    Optional szDirName As String = "" _
) As String

Parameters

szFileOrPEMString

Filename of ASN.1 formatted data file to be analyzed (or its base64 representation or PEM string).

nOptions

Use 0 for default or add any of:

PKI_ASN1_NOCOMMENTS
PKI_ASN1_ADDLEVELS

szDirName

Directory in which to create a temporary file. Specify "" for default = system TEMP directory.

Return Value

Remarks

asn1Type

Describe the type of ASN.1 data.

Syntax

Public Function asn1Type ( _
    szFileOrPEMString As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szFileOrPEMString

Filename of ASN.1 formatted data file to be analyzed (or a string containing its base64 or PEM representation).

nOptions

For future use.

Return Value

Remarks

"EC PRIVATE KEY"
"OCSP REQUEST"
"OCSP RESPONSE"
"PKCS1 RSA PRIVATE KEY"
"PKCS1 RSA PUBLIC KEY"
"PKCS10 CERTIFICATE REQUEST"
"PKCS12 PFX"
"PKCS7 CERTIFICATE CHAIN"
"PKCS7/CMS COMPRESSED DATA"
"PKCS7/CMS DATA"
"PKCS7/CMS ENVELOPED DATA"
"PKCS7/CMS SIGNED DATA"
"PKCS8 ENCRYPTED PRIVATE KEY"
"PKCS8 PRIVATE KEY INFO"
"PUBLIC KEY INFO"
"X509 CERTIFICATE"
"X509 CRL"

cipherDecryptAEAD

Decrypt data using Authenticated Encryption with Associated Data (AEAD). The authentication tag is expected to be appended to the input ciphertext.

Syntax

Public Function cipherDecryptAEAD ( _
    lpInput() As Byte, _
    lpKey() As Byte, _
    lpIV() As Byte, _
    lpAAD() As Byte, _
    nOptions As Long _
) As Byte()

Parameters

lpInput

Input data to be decrypted.

lpKey

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

lpIV

Initialization Vector (IV) (aka nonce) exactly 12 bytes long.

lpAAD

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

nOptions

Algorithm to be used. Select one from

PKI_AEAD_AES_128_GCM
PKI_AEAD_AES_192_GCM
PKI_AEAD_AES_256_GCM
PKI_AEAD_CHACHA20_POLY1305

Add PKI_IV_PREFIX to expect the IV to be prepended at the start of the input.

Return Value

Remarks

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

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 required 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|gcm
Pad:  pkcs5|nopad|oneandzeroes|ansix923|w3c

nOptions

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

Return Value

Remarks

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

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 PKI_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|gcm
Pad:  pkcs5|nopad|oneandzeroes|ansix923|w3c

nOptions

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

Return Value

Remarks

cipherEncryptAEAD

Encrypt data using Authenticated Encryption with Associated Data (AEAD).

Syntax

Public Function cipherEncryptAEAD ( _
    lpInput() As Byte, _
    lpKey() As Byte, _
    lpIV() As Byte, _
    lpAAD() As Byte, _
    nOptions As Long _
) As Byte()

Parameters

lpInput

Byte array containing the input data.

lpKey

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

lpIV

Initialization Vector (IV) (aka nonce) exactly 12 bytes long.

lpAAD

Additional authenticated data (optional) - set as empty array to ignore.

nOptions

Algorithm to be used. Select one from

PKI_AEAD_AES_128_GCM
PKI_AEAD_AES_192_GCM
PKI_AEAD_AES_256_GCM
PKI_AEAD_CHACHA20_POLY1305

and optionally add PKI_IV_PREFIX to prepend the IV (nonce) before the ciphertext in the output.

Return Value

Remarks

cipherEncryptBytes

Encrypt 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

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, empty array for ECB mode, or 12 bytes for AES-GCM.

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|gcm
Pad:  pkcs5|nopad|oneandzeroes|ansix923|w3c

nOptions

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

Return Value

Remarks

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

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 required 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|gcm
Pad:  pkcs5|nopad|oneandzeroes|ansix923|w3c

nOptions

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

Return Value

Remarks

cipherFileDecrypt

Decrypt a file.

Syntax

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 required length, or empty array for ECB mode or if IV is prefixed.

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|gcm
Pad:  pkcs5|nopad|oneandzeroes|ansix923|w3c

nOptions

Add PKI_IV_PREFIX to expect the IV before the ciphertext in the input.

Return Value

Remarks

cipherFileEncrypt

Encrypt a file.

Syntax

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, empty array for ECB mode, or 12 bytes for AES-GCM.

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|gcm
Pad:  pkcs5|nopad|oneandzeroes|ansix923|w3c

nOptions

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

Return Value

Remarks

cipherKeyUnwrap

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

Syntax

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:

PKI_BC_AES128
PKI_BC_AES192
PKI_BC_AES256
PKI_BC_3DES

Return Value

cipherKeyWrap

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

Syntax

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:

PKI_BC_AES128
PKI_BC_AES192
PKI_BC_AES256
PKI_BC_3DES

Return Value

cmsGetSigDataDigest

Extract the message digest from a signed-data CMS object file and verify the signature.

Syntax

Public Function cmsGetSigDataDigest ( _
    szFileIn As String, _
    Optional szCertFile As String = "", _
    Optional nOptions As Long = 0 _
) As String

Parameters

szFileIn

Name of signed-data CMS object file or the data as a base64 or PEM string.

szCertFile

An (optional) X.509 certificate file to be used to identify the signer.

nOptions

For future use.

Return Value

Remarks

cmsMakeEnvData

Create a CMS enveloped-data object for one or more recipients.

Syntax

Public Function cmsMakeEnvData ( _
    szFileOut As String, _
    szFileIn As String, _
    szCertList As String, _
    Optional szKeyString As String = "", _
    Optional nOptions As Long = 0, _
    Optional nCount As Long = 0 _
) As Long

Parameters

szFileOut

Name of output file to be created.

szFileIn

Name of file containing input data.

szCertList

List of one or more recipient X.509 certificate filenames, separated by semicolons (;). A certificate's representation in base64 or as a PEM string may be used instead of a filename. Alternatively, specify a single PKCS#7 certificate chain file (.p7c/.p7b).
Special cases: Set as "type=@pwri" to create a single recipientInfo of the PasswordRecipientInfo (pwri) type; or set as "type=@kekri,keyid=<string>" to create a single recipientInfo of the KEKRecipientInfo (kekri) type. See Remarks.

szKeyString

(formerly szSeed) Use to pass optional additional user key material (ukm) for KDF where KeyAgreement (kari) type is used. Or use to pass the password for a pwri type or the key encryption key (KEK) for a kekri type. Either pass a plain ASCII string, e.g. "abc" or use the format "#x<hex-digits>" to pass a string of arbitrary octet values, e.g. "#xdeadbeef01" to pass the 5 bytes 0xde,0xad,0xbe,0xef,0x01. Required for pwri and kekri types.

nOptions

Select the content encryption algorithm from:

PKI_BC_3DES (default)
PKI_BC_AES128
PKI_BC_AES192
PKI_BC_AES256
PKI_AEAD_AES_128_GCM
PKI_AEAD_AES_192_GCM
PKI_AEAD_AES_256_GCM
PKI_AEAD_CHACHA20_POLY1305

To set the key transport scheme (where applicable), use one of

PKI_KT_RSAES_PKCS (default)
PKI_KT_RSAES_OAEP

If you have selected PKI_KT_RSAES_OAEP then, optionally, add

PKI_MGF_MGF1SHA1

Select one hash algorithm for RSAES-OAEP or ECDH KDF or pwri PBKDF2:

PKI_HASH_SHA1 (default)
PKI_HASH_SHA224
PKI_HASH_SHA256
PKI_HASH_SHA384
PKI_HASH_SHA512

To set the key derivation function (KDF) for the ECDH key agreement scheme (where applicable), add one of:

PKI_KDF_X963 (default)
PKI_KDF_HKDF

add one key wrap algorithm for the ECDH key agreement scheme or the kekri key encryption algorithm (default=match content encryption algorithm):

PKI_KWRAP_3DES (allowed only if Triple DES is used for content encryption)
PKI_KWRAP_AES128
PKI_KWRAP_AES192
PKI_KWRAP_AES256

Optionally, add any of the bitflags:

PKI_CMS_FORMAT_BASE64 (default=binary)
PKI_CMS_ALT_ALGID
PKI_CMS_BIGFILE (binary file to binary file only)

nCount

Use to pass the iteration count for a pwri type (default=4096) or tag length for AuthEnvelopedData (in range 12-16, default=16). Otherwise ignored.

Return Value

Remarks

Example

' Create an enveloped CMS object (ktri type) to Bob using Bob's RSA key...
n = cmsMakeEnvData("cms2bob_aes128.p7m", "excontent.txt", "BobRSASignByCarl.cer", "", PKI_BC_AES128 Or PKI_KT_RSAES_OAEP)
' Same but using authenticated encryption and creating an authEnvelopedData object...
n = cmsMakeEnvData("cms2bob_aes128auth.p7m", "excontent.txt", "BobRSASignByCarl.cer", "", PKI_AEAD_AES_128_GCM Or PKI_KT_RSAES_OAEP)
' Create an enveloped CMS object (kari type) to Dana using Dana's ECC key...
n = cmsMakeEnvData("cms2dana_hkdf.p7m", "excontent.txt", "lamps-dana.encrypt.crt", "", PKI_BC_AES256 Or PKI_HASH_SHA256 Or PKI_KDF_HKDF Or PKI_KWRAP_AES256)
' Create an enveloped CMS object (kekri type) using a previously distributed symmetric key-encryption key (KEK)...
n = cmsMakeEnvData("cms_envdata_kekri.p7m", "excontent.txt", "type=@kekri,keyid=ourcommonkey", "#x0123456789ABCDEFF0E1D2C3B4A59687", PKI_BC_AES256 Or PKI_HASH_SHA256 Or PKI_KWRAP_AES128)
' Create an enveloped CMS object (pwri type) using password-based key management...
n = cmsMakeEnvData("cms_envdata_pwri.p7m", "excontent.txt", "type=@pwri", "password12345", PKI_BC_AES192)

cmsMakeEnvDataFromBytes

Create a CMS enveloped-data object from data in a byte array.

Syntax

Public Function cmsMakeEnvDataFromBytes ( _
    szFileOut As String, _
    lpInput() As Byte, _
    szCertList As String, _
    Optional szKeyString As String = "", _
    Optional nOptions As Long = 0, _
    Optional nCount As Long = 0 _
) As Long

Parameters

szFileOut

Name of output file to be created.

lpInput

Input data.

szCertList

List of one or more recipient X.509 certificate filenames, separated by semicolons (;). A certificate's representation in base64 or as a PEM string may be used instead of a filename. Alternatively, specify a single PKCS#7 certificate chain file (.p7c/.p7b).
Special cases: Set as "type=@pwri" to create a single recipientInfo of the PasswordRecipientInfo (pwri) type; or set as "type=@kekri,keyid=<string>" to create a single recipientInfo of the KEKRecipientInfo (kekri) type. See Remarks.

szKeyString

(formerly szSeed) Use to pass optional additional user key material (ukm) for KDF where KeyAgreement (kari) type is used. Or use to pass the password for a pwri type or the key encryption key (KEK) for a kekri type. Either pass a plain ASCII string, e.g. "abc" or use the format "#x<hex-digits>" to pass a string of arbitrary octet values, e.g. "#xdeadbeef01" to pass the 5 bytes 0xde,0xad,0xbe,0xef,0x01. Required for pwri and kekri types.

nOptions

See the options in cmsMakeEnvData.

nCount

Use to pass the iteration count for a pwri type (default=4096) or tag length for AuthEnvelopedData (in range 12-16, default=16). Otherwise ignored.

Return Value

Remarks

cmsMakeEnvDataFromString

Create a CMS enveloped-data object from an ASCII string.

Syntax

Public Function cmsMakeEnvDataFromString ( _
    szFileOut As String, _
    szInput As String, _
    szCertList As String, _
    Optional szKeyString As String = "", _
    Optional nOptions As Long = 0, _
    Optional nCount As Long = 0 _
) As Long

Parameters

szFileOut

Name of output file to be created.

szInput

Input data.

szCertList

List of one or more recipient X.509 certificate filenames, separated by semicolons (;). A certificate's representation in base64 or as a PEM string may be used instead of a filename. Alternatively, specify a single PKCS#7 certificate chain file (.p7c/.p7b).
Special cases: Set as "type=@pwri" to create a single recipientInfo of the PasswordRecipientInfo (pwri) type; or set as "type=@kekri,keyid=<string>" to create a single recipientInfo of the KEKRecipientInfo (kekri) type. See Remarks.

szKeyString

(formerly szSeed) Use to pass optional additional user key material (ukm) for KDF where KeyAgreement (kari) type is used. Or use to pass the password for a pwri type or the key encryption key (KEK) for a kekri type. Either pass a plain ASCII string, e.g. "abc" or use the format "#x<hex-digits>" to pass a string of arbitrary octet values, e.g. "#xdeadbeef01" to pass the 5 bytes 0xde,0xad,0xbe,0xef,0x01. Required for pwri and kekri types.

nOptions

See the options in cmsMakeEnvData.

nCount

Use to pass the iteration count for a pwri type (default=4096) or tag length for AuthEnvelopedData (in range 12-16, default=16). Otherwise ignored.

Return Value

Remarks

cmsMakeSigDataFromBytes

Create a CMS signed-data object from data in a byte array.

Syntax

Public Function cmsMakeSigDataFromBytes ( _
    szFileOut As String, _
    lpInput() As Byte, _
    szCertList As String, _
    szPrivateKey As String, _
    Optional nOptions As Long = 0 _
) As Long

Parameters

szFileOut

Name of output file to be created.

lpInput

Input data.

szCertList

Filename of the signer's certificate (or a string with its base64 or PEM representation) and (optionally) a list of other certificates to be included in the output, separated by semi-colons (;) Alternatively, specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate.

szPrivateKey

Internal representation of private key for the sender.

nOptions

Select the signature algorithm from one of:

PKI_SIG_RSA_SHA1
PKI_SIG_RSA_SHA224
PKI_SIG_RSA_SHA256
PKI_SIG_RSA_SHA384
PKI_SIG_RSA_SHA512
PKI_SIG_RSA_MD5
PKI_SIG_RSA_PSS_SHA1
PKI_SIG_RSA_PSS_SHA224
PKI_SIG_RSA_PSS_SHA256
PKI_SIG_RSA_PSS_SHA384
PKI_SIG_RSA_PSS_SHA512
PKI_SIG_ECDSA_SHA1
PKI_SIG_ECDSA_SHA224
PKI_SIG_ECDSA_SHA256
PKI_SIG_ECDSA_SHA384
PKI_SIG_ECDSA_SHA512
PKI_SIG_ED25519

and optionally add any of the following:

PKI_CMS_EXCLUDE_CERTS
PKI_CMS_EXCLUDE_DATA
PKI_CMS_CERTS_ONLY
PKI_CMS_INCLUDE_ATTRS
PKI_CMS_FORMAT_BASE64
PKI_CMS_NO_OUTER
PKI_CMS_ALT_ALGID
PKI_CMS_BIGFILE
PKI_PSS_SALTLEN_ZERO
PKI_MGF_MGF1SHA1

If the PKI_CMS_INCLUDE_ATTRS option flag is included, optionally add any of the following:

PKI_CMS_ADD_SIGNTIME
PKI_CMS_ADD_SMIMECAP
PKI_CMS_ADD_SIGNINGCERT
PKI_CMS_ADD_ALGPROTECT

Return Value

cmsMakeSigDataFromSigValue

Create a CMS signed-data object using a pre-computed signature value.

Syntax

Public Function cmsMakeSigDataFromSigValue ( _
    szFileOut As String, _
    lpSigValue() As Byte, _
    lpInput() As Byte, _
    szCertList As String, _
    Optional nOptions As Long = 0 _
) As Long

Parameters

szFileOut

Name of output file to be created.

lpSigValue

Pre-computed signature value in byte array.

lpInput

Input data.

szCertList

Filename of the signer's certificate (or a string with its base64 or PEM representation) and (optionally) a list of other certificates to be included in the output, separated by semi-colons (;) Alternatively, specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate.

nOptions

Select the signature algorithm from one of:

PKI_SIG_RSA_SHA1
PKI_SIG_RSA_SHA224
PKI_SIG_RSA_SHA256
PKI_SIG_RSA_SHA384
PKI_SIG_RSA_SHA512
PKI_SIG_RSA_MD5

and optionally add any of the following:

PKI_CMS_EXCLUDE_CERTS
PKI_CMS_FORMAT_BASE64
PKI_CMS_NO_OUTER
PKI_CMS_ALT_ALGID
PKI_CMS_PSEUDOSIG

Return Value

Remarks

cmsQueryEnvData

Query a CMS enveloped-data object file for selected information.

Syntax

Public Function cmsQueryEnvData ( _
    szFileIn As String, _
    szQuery As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szFileIn

Name of file containing CMS enveloped-data object (binary or base64-encoded) or the data as a base64 or PEM string.

szQuery

Query string (case insensitive). Valid queries are:

"version"
"recipientInfoVersion"
"recipientInfoType"
"CountOfRecipientInfos"
"recipientIssuerName"
"recipientSerialNumber"
"keyEncryptionAlgorithm"
"keyEncryptionFlags"
"SizeofEncryptedKey"
"encryptedKey"
"oaepParams"
"keyWrapAlgorithm"
"originatorKeyAlgorithm"
"originatorPublicKey"
"keyid"
"contentEncryptionAlgorithm"
"SizeofEncryptedContent"
"encryptedContent"
"iv"

nOptions

For future use.

Return Value

Remarks

cmsQuerySigData

Query a CMS signed-data object file for selected information.

Syntax

Public Function cmsQuerySigData ( _
    szFileIn As String, _
    szQuery As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szFileIn

Name of file containing CMS signed-data object (binary or base64-encoded) or the data as a base64 or PEM string.

szQuery

Query string (case insensitive). Valid queries are:

"version"
"eContentType"
"HASeContent"
"CountOfCertificates"
"CountOfSignerInfos"
"signerInfoVersion"
"digestAlgorithm"
"signatureAlgorithm"
"HASsignedAttributes"
"signingTime"
"messageDigest"
"pssParams"
"HASsigningCertificate"
"HASalgorithmProtection"

nOptions

For future use.

Return Value

Remarks

cmsReadEnvDataToBytes

Read and decrypt a CMS enveloped-data object to a byte array.

Syntax

Public Function cmsReadEnvDataToBytes ( _
    szFileIn As String, _
    szCertFile As String, _
    szPrivateKey As String, _
    Optional nOptions As Long = 0 _
) As Byte()

Parameters

szFileIn

Name of file containing CMS enveloped-data object (binary or base64-encoded) or the data as a base64 or PEM string.

szCertFile

Filename of the recipient's X.509 certificate (optional).

szPrivateKey

Internal representation of private key.

nOptions

For future use.

Return Value

Remarks

cmsReadEnvDataToString

Read and decrypt a CMS enveloped-data object to a string.

Syntax

Public Function cmsReadEnvDataToString ( _
    szFileIn As String, _
    szCertFile As String, _
    szPrivateKey As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szFileIn

Name of file containing CMS enveloped-data object (binary or base64-encoded) or the data as a base64 or PEM string.

szCertFile

Filename of the recipient's X.509 certificate (optional).

szPrivateKey

Internal representation of private key.

nOptions

For future use.

Return Value

Remarks

cmsReadSigDataToBytes

Read the content from a CMS signed-data object directly into a byte array.

Syntax

Public Function cmsReadSigDataToBytes ( _
    szFileIn As String, _
    Optional nOptions As Long = 0 _
) As Byte()

Parameters

szFileIn

Name of file containing CMS signed-data object (binary or base64-encoded) or the data as a base64 or PEM string.

nOptions

For future use.

Return Value

Remarks

cmsReadSigDataToString

Read the content from a CMS signed-data object directly into a string.

Syntax

Public Function cmsReadSigDataToString ( _
    szFileIn As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szFileIn

Name of file containing CMS signed-data object (binary or base64-encoded) or the data as a base64 or PEM string.

nOptions

For future use.

Return Value

Remarks

cmsVerifySigData

Verify the signature and content of a signed-data CMS object file.

Syntax

Public Function cmsVerifySigData ( _
    szFileIn As String, _
    Optional szCertFile As String = "", _
    Optional szHexDigest As String = "", _
    Optional nOptions As Long = 0 _
) As Long

Parameters

szFileIn

Name of file containing CMS signed-data object (binary or base64-encoded) or the data as a base64 or PEM string.

szCertFile

(optional) X.509 certificate file of the signer.

szHexDigest

(optional) digest of eContent to be verified (use for "detached-signature" form)

nOptions

Add to speed up the processing of large files (binary input only).

PKI_CMS_BIGFILE

Return Value

cnvB64Filter

Strip any invalid base64 characters from a string.

Syntax

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

Parameters

szB64

String to be filtered.

Return Value

cnvB64StrFromBytes

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

Syntax

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

Parameters

lpData

Input byte array.

Return Value

Remarks

cnvB64StrFromHexStr

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

Syntax

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

Parameters

szHex

Hex string representing a binary value.

Return Value

cnvB64StrFromString

Encode an ANSI string as a base64-encoded string.

Syntax

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

Parameters

szData

String to be encoded.

Return Value

Remarks

cnvBase58FromBytes

Convert 8-bit binary data to equivalent base58-encoded string format.

Syntax

Public Function cnvBase58FromBytes ( _
    lpInput() As Byte _
) As String

Parameters

lpInput

Binary data.

Return Value

Remarks

cnvBase58ToBytes

Convert a base58-encoded string to an equivalent array of 8-bit unsigned integers.

Syntax

Public Function cnvBase58ToBytes ( _
    szInput As String _
) As Byte()

Parameters

szInput

Base58-encoded data.

Return Value

Remarks

cnvByteEncoding

Convert encoding of byte array between UTF-8 and Latin-1.

Syntax

Public Function cnvByteEncoding ( _
    lpInput() As Byte, _
    nOptions As Long _
) As Byte()

Parameters

lpInput

Base58-encoded data.

nOptions

Option flags. Select one of:

PKI_CNV_UTF8_FROM_LATIN1
PKI_CNV_LATIN1_FROM_UTF8

Return Value

cnvBytesFromB64Str

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

Syntax

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

Parameters

szB64

Base64 data to be decoded.

Return Value

Remarks

cnvBytesFromHexStr

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

Syntax

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

Parameters

szHex

Hexadecimal data to be decoded.

Return Value

Remarks

cnvBytesLen

Find length of byte array.

Syntax

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

Parameters

ab

Input byte array.

Return Value

Remarks

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

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

cnvCheckUTF8Bytes

Check if a byte array contains valid UTF-8 characters.

Syntax

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

Parameters

lpInput

data to be checked

Return Value

Remarks

0 = Not valid UTF-8
1 = Valid UTF-8, all chars are 7-bit ASCII
2 = Valid UTF-8, contains at least one multi-byte character equivalent to 8-bit ANSI
3 = Valid UTF-8, contains at least one multi-byte character that cannot be represented in a single-byte character set

cnvFromBase64

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

Syntax

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

Parameters

strBase64

Base64 data to be decoded.

Return Value

Remarks

cnvFromHex

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

Syntax

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

Parameters

strHex

Hexadecimal-encoded data to be decoded.

Return Value

Remarks

cnvHexFilter

Strip any invalid hex characters from a hex string.

Syntax

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

Parameters

szHex

String to be filtered.

Return Value

cnvHexFromBytesMid

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

Syntax

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

Example

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

cnvHexStrFromB64Str

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

Syntax

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

Parameters

szB64

Base64 string representing a binary value.

Return Value

cnvHexStrFromBytes

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

Syntax

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

Parameters

lpData

Input byte array.

Return Value

Remarks

cnvHexStrFromString

Encode an ANSI string as a hexadecimal-encoded string.

Syntax

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

Parameters

szData

String to be encoded.

Return Value

Remarks

cnvLatin1FromUTF8Bytes

Convert UTF-8 encoded array of bytes into a Latin-1 string, if possible.

Syntax

Public Function cnvLatin1FromUTF8Bytes ( _
    lpInput() As Byte _
) As String

Parameters

lpInput

Array containing UTF-8 encoded data.

Return Value

cnvNumFromBytes

Convert the leftmost four bytes of an array to a 32-bit integer.

Syntax

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

Parameters

lpInput

Byte array to be converted.

nOptions

Option flags. Use 0 for default big-endian order or one of:

PKI_CNV_BIG_ENDIAN (0)
PKI_CNV_LITTLE_ENDIAN

Return Value

Remarks

Example

Debug.Print Hex(cnvNumFromBytes(cnvFromHex("DEADBEEF")))
'DEADBEEF
Debug.Print cnvNumFromBytes(cnvFromHex("DEADBEEF"))
'-559038737

cnvNumToBytes

Convert a 32-bit integer to an array of 4 bytes.

Syntax

Public Function cnvNumToBytes ( _
    nNumber As Long, _
    Optional nOptions As Long = 0 _
) As Byte()

Parameters

nNumber

Integer to be converted.

nOptions

Option flags. Use 0 for default big-endian order or one of:

PKI_CNV_BIG_ENDIAN (0)
PKI_CNV_LITTLE_ENDIAN

Return Value

Example

Debug.Print cnvToHex(cnvNumToBytes(&HDEADBEEF, PKI_CNV_LITTLE_ENDIAN))
'EFBEADDE

cnvReverseBytes

Reverse the order of a byte array.

Syntax

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

Parameters

lpInput

Input data to be reversed.

Return Value

Example

Debug.Print cnvToHex(cnvReverseBytes(cnvFromHex("DEADBEEF")))
'EFBEADDE

cnvStringFromHexStr

Decode a hexadecimal-encoded string as an ANSI string.

Syntax

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

Parameters

szHex

Hexadecimal data to be decoded.

Return Value

Remarks

cnvToBase64

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

Syntax

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

Parameters

lpData

Input byte array

Return Value

Remarks

cnvToHex

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

Syntax

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

Parameters

lpData

Input byte array

Return Value

Remarks

cnvUTF8BytesFromLatin1

Convert a string of 8-bit Latin-1 (ISO-8859-1) characters into a UTF-8 encoded array of bytes.

Syntax

Public Function cnvUTF8BytesFromLatin1 ( _
    szInput As String _
) As Byte()

Parameters

szInput

String of Latin-1 characters to be converted.

Return Value

comprCompress

Compress data using zlib compression.

Syntax

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

Parameters

lpInput

Data to be compressed.

nOptions

For future use.

Return Value

comprUncompress

Uncompress data using zlib compression.

Syntax

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

Parameters

lpInput

Data to be uncompressed.

nOptions

For future use.

Return Value

eccDHSharedSecret

Compute EC Diffie-Hellman (ECDH) shared secret.

Syntax

Public Function eccDHSharedSecret ( _
    szIntPrivateKey As String, _
    szIntPublicKey As String, _
    Optional nOptions As Long = 0 _
) As Byte()

Parameters

szIntPrivateKey

String containing our own private key in ephemeral "internal" form.

szIntPublicKey

String containing other party's public key in "internal" form.

nOptions

For future use.

Return Value

eccKeyHashCode

Compute the hash code of an "internal" ECC public or private key string.

Syntax

Public Function eccKeyHashCode ( _
    szIntKeyString As String _
) As Long

Parameters

szIntKeyString

Key in ephemeral "internal" representation.

Return Value

Remarks

eccMakeKeys

Generate an EC public/private key pair and save as two key files.

Syntax

Public Function eccMakeKeys ( _
    szPubKeyFile As String, _
    szPriKeyFile As String, _
    szCurveName As String, _
    szPassword As String, _
    Optional szParams As String = "", _
    Optional nOptions As Long = 0 _
) As Long

Parameters

szPubKeyFile

Output filename for public key.

szPriKeyFile

Output filename for (encrypted) private key.

szCurveName

Name of elliptic curve

szPassword

Password for encrypted private key (required).

szParams

Optional parameters. A set of attribute name=value pairs separated by a semicolon ";" (see remarks).

nOptions

Use 0 for defaults.
A flag to indicate the password-based encryption scheme to be used to encrypt the private key file. Select from:

PKI_PBE_SHA_3DES (0) for "pbeWithSHAAnd3-KeyTripleDES-CBC" from PKCS12 (default)
PKI_PBE_PBKDF2_DESEDE3 for PBKDF2 using des-EDE3-CBC
PKI_PBE_PBKDF2_AES128 for PBKDF2 using aes128-CBC
PKI_PBE_PBKDF2_AES192 for PBKDF2 using aes192-CBC
PKI_PBE_PBKDF2_AES256 for PBKDF2 using aes256-CBC

plus optionally to output in textual PEM format [default format=DER binary]

PKI_KEY_FORMAT_PEM

Return Value

Remarks

Example

' Create an ECC key pair using defaults
r = eccMakeKeys("myeccP256.pub", "myeccP256.p8e", "Secp256r1", "password")
' Same but using different curve, stronger security and in PEM format
r = eccMakeKeys("myeccBP256r1.pub", "myeccBP256r1.p8e", "brainpoolP256r1", "password1", "count=6000;prf=hmacWithSHA256", PKI_PBE_PBKDF2_AES128 Or PKI_KEY_FORMAT_PEM)

eccPublicKeyFromPrivate

Convert an internal EC private key string into an internal EC public key string.

Syntax

Public Function eccPublicKeyFromPrivate ( _
    szIntKeyString As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szIntKeyString

Private key in ephemeral "internal" representation.

nOptions

For future use.

Return Value

eccQueryKey

Query an EC key string for selected information.

Syntax

Public Function eccQueryKey ( _
    szIntKeyString As String, _
    szQuery As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szIntKeyString

Key in ephemeral "internal" representation.

szQuery

Query string (case insensitive). Valid queries are:

curveName
keyBits
isPrivate
privateKey
publicKey

nOptions

For future use.

Return Value

eccReadKeyByCurve

Read an EC key from its hexadecimal representation.

Syntax

Public Function eccReadKeyByCurve ( _
    szHexKey As String, _
    szCurveName As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szHexKey

Hexadecimal representation of the key, private or public.

szCurveName

Name of the elliptic curve.

nOptions

For Safe Curves specify PKI_ECC_PRIVATE_KEY or PKI_ECC_PUBLIC_KEY to indicate that the key value represents a private or public key, respectively. Otherwise, nOptions is ignored.

Return Value

eccReadPrivateKey

Read an EC private key from a file into an internal key string.

Syntax

Public Function eccReadPrivateKey ( _
    szKeyFileOrString As String, _
    Optional szPassword As String = "", _
    Optional nOptions As Long = 0 _
) As String

Parameters

szKeyFileOrString

Either the name of file containing the key or a string containing the key in PEM format.

szPassword

Password for the key file, if encrypted; otherwise set as "".

nOptions

For future use.

Return Value

eccReadPublicKey

Read an EC private key from a file into an internal key string.

Syntax

Public Function eccReadPublicKey ( _
    szKeyFileOrString As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szKeyFileOrString

Either the name of file containing the key or a string containing the key in PEM format.

nOptions

For future use.

Return Value

eccSaveEncKey

Save an internal EC private key string to an encrypted key file.

Syntax

Public Function eccSaveEncKey ( _
    szOutputFile As String, _
    szKeyStr As String, _
    szPassword As String, _
    Optional szParams As String = "", _
    Optional nOptions As Long = 0 _
) As Long

Parameters

szOutputFile

Name of output file to be created.

szKeyStr

The private key in an internal key string.

szPassword

Password for encrypted private key (required).

szParams

Optional parameters. A set of attribute name=value pairs separated by a semicolon ";" (see remarks).

nOptions

Use 0 for defaults.
A flag to indicate the password-based encryption scheme to be used to encrypt the private key file. Select from:

PKI_PBE_SHA_3DES (0) for "pbeWithSHAAnd3-KeyTripleDES-CBC" from PKCS12 (default)
PKI_PBE_PBKDF2_DESEDE3 for PBKDF2 using des-EDE3-CBC
PKI_PBE_PBKDF2_AES128 for PBKDF2 using aes128-CBC
PKI_PBE_PBKDF2_AES192 for PBKDF2 using aes192-CBC
PKI_PBE_PBKDF2_AES256 for PBKDF2 using aes256-CBC

plus optionally add the following to output in textual PEM format [default format=DER binary]

PKI_KEY_FORMAT_PEM

Return Value

Remarks

eccSaveKey

Save an internal EC key string to a key file.

Syntax

Public Function eccSaveKey ( _
    szOutputFile As String, _
    szKeyStr As String, _
    Optional nOptions As Long = 0 _
) As Long

Parameters

szOutputFile

Name of output file to be created.

szKeyStr

Key string (public or private) in internal format.

nOptions

Choose one of

PKI_DEFAULT (0) to save the key in the default format.
PKI_KEY_TYPE_PKCS8 to save a NIST/SEC curve private key in PKCS#8 format.

and optionally add any of

PKI_KEY_FORMAT_PEM to save the key file in PEM form (default is binary DER-encoded format).
PKI_KEY_LEGACY to save a safe key in "legacy" PKCS#8 v1 format (default is v2 OneAsymmetricKey).

Return Value

Remarks

errFormatErrorMessage

Return an error message string for the last error.

Syntax

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

Parameters

nErrCode

Error code returned by last function call (or zero if no code available).

szMsg

Optional message to add.

Return Value

Example

Debug.Print errFormatErrorMessage(11)
Error (11): Parameter out of range (OUT_OF_RANGE_ERROR)
Debug.Print errFormatErrorMessage(11, "User message!")
ERROR: User message! (11): Value out of range (OUT_OF_RANGE_ERROR)

hashBytes

Compute hash digest in byte format of byte input.

Syntax

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:

PKI_HASH_SHA1
PKI_HASH_SHA224
PKI_HASH_SHA256
PKI_HASH_SHA384
PKI_HASH_SHA512
PKI_HASH_SHA3_224
PKI_HASH_SHA3_256
PKI_HASH_SHA3_384
PKI_HASH_SHA3_512
PKI_HASH_MD5
PKI_HASH_MD2
PKI_HASH_RMD160
PKI_HASH_BTC160

and optionally add PKI_HASH_DOUBLE to compute a double hash, HASH(HASH(m)).

Return Value

hashFile

Compute hash digest in byte format of a file.

Syntax

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:

PKI_HASH_SHA1
PKI_HASH_SHA224
PKI_HASH_SHA256
PKI_HASH_SHA384
PKI_HASH_SHA512
PKI_HASH_SHA3_224
PKI_HASH_SHA3_256
PKI_HASH_SHA3_384
PKI_HASH_SHA3_512
PKI_HASH_MD5
PKI_HASH_MD2
PKI_HASH_RMD160
PKI_HASH_BTC160

and optionally add PKI_HASH_DOUBLE to compute a double hash, HASH(HASH(m)). Add PKI_HASH_MODE_TEXT to hash in "text" mode instead of default "binary" mode.

Return Value

Remarks

hashHexFromBytes

Compute hash digest in hex format of byte input.

Syntax

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:

PKI_HASH_SHA1
PKI_HASH_SHA224
PKI_HASH_SHA256
PKI_HASH_SHA384
PKI_HASH_SHA512
PKI_HASH_SHA3_224
PKI_HASH_SHA3_256
PKI_HASH_SHA3_384
PKI_HASH_SHA3_512
PKI_HASH_MD5
PKI_HASH_MD2
PKI_HASH_RMD160
PKI_HASH_BTC160

and optionally add PKI_HASH_DOUBLE to compute a double hash, HASH(HASH(m)).

Return Value

hashHexFromFile

Compute hash digest in hex format of a file.

Syntax

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:

PKI_HASH_SHA1
PKI_HASH_SHA224
PKI_HASH_SHA256
PKI_HASH_SHA384
PKI_HASH_SHA512
PKI_HASH_SHA3_224
PKI_HASH_SHA3_256
PKI_HASH_SHA3_384
PKI_HASH_SHA3_512
PKI_HASH_MD5
PKI_HASH_MD2
PKI_HASH_RMD160
PKI_HASH_BTC160

and optionally add PKI_HASH_DOUBLE to compute a double hash, HASH(HASH(m)). Add PKI_HASH_MODE_TEXT to hash in "text" mode instead of default "binary" mode.

Return Value

Remarks

hashHexFromHex

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

Syntax

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:

PKI_HASH_SHA1
PKI_HASH_SHA224
PKI_HASH_SHA256
PKI_HASH_SHA384
PKI_HASH_SHA512
PKI_HASH_SHA3_224
PKI_HASH_SHA3_256
PKI_HASH_SHA3_384
PKI_HASH_SHA3_512
PKI_HASH_MD5
PKI_HASH_MD2
PKI_HASH_RMD160
PKI_HASH_BTC160

and optionally add PKI_HASH_DOUBLE to compute a double hash, HASH(HASH(m)).

Return Value

hashLength

Return length of message digest output in bytes.

Syntax

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

Parameters

nAlgId

Algorithm Id flag. Select one of PKI_HASH_* or PKI_HMAC_*, for example:

PKI_HASH_SHA1
PKI_HASH_SHA224
PKI_HASH_SHA256
PKI_HASH_SHA384
PKI_HASH_SHA512
PKI_HASH_SHA3_224
PKI_HASH_SHA3_256
PKI_HASH_SHA3_384
PKI_HASH_SHA3_512
PKI_HASH_MD5
PKI_HASH_MD2
PKI_HASH_RMD160
PKI_HASH_BTC160

Return Value

Example

Debug.Print hashLength(PKI_HASH_SHA512)
64

hmacBytes

Compute hash-based message authentication code (HMAC) as a byte array from byte data.

Syntax

Public Function hmacBytes ( _
    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:

PKI_HMAC_SHA1
PKI_HMAC_SHA224
PKI_HMAC_SHA256
PKI_HMAC_SHA384
PKI_HMAC_SHA512
PKI_HMAC_SHA3_224
PKI_HMAC_SHA3_256
PKI_HMAC_SHA3_384
PKI_HMAC_SHA3_512
PKI_HMAC_MD5

Return Value

hmacHexFromBytes

Compute hash-based message authentication code (HMAC) in hexadecimal format from byte data.

Syntax

Public Function hmacHexFromBytes ( _
    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:

PKI_HMAC_SHA1
PKI_HMAC_SHA224
PKI_HMAC_SHA256
PKI_HMAC_SHA384
PKI_HMAC_SHA512
PKI_HMAC_SHA3_224
PKI_HMAC_SHA3_256
PKI_HMAC_SHA3_384
PKI_HMAC_SHA3_512
PKI_HMAC_MD5

Return Value

hmacHexFromHex

Compute hash-based message authentication code (HMAC) in hexadecimal format from data in hexadecimal-encoded strings.

Syntax

Public Function hmacHexFromHex ( _
    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:

PKI_HMAC_SHA1
PKI_HMAC_SHA224
PKI_HMAC_SHA256
PKI_HMAC_SHA384
PKI_HMAC_SHA512
PKI_HMAC_SHA3_224
PKI_HMAC_SHA3_256
PKI_HMAC_SHA3_384
PKI_HMAC_SHA3_512
PKI_HMAC_MD5

Return Value

hpkeDerivePrivateKey

Derive an EC private key in a deterministic manner from input keying material using the DeriveKeyPair algorithm in RFC9180.

Syntax

Public Function hpkeDerivePrivateKey ( _
    lpIkm() As Byte, _
    szCurveName As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

lpIkm

Input key material (ikm). This must have length in bytes at least as long as the key to be produced.

szCurveName

ECDH curve name. Select one from

 "P-256" | "P-384" | "P-521" | "X25519" | "X448"

nOptions

Option flags. Select one of: Zero (0) to output the private key in ephemeral "internal" key format (default); or PKI_ENCODE_HEX to output the private key in serialized hex form.

Return Value

Remarks

hpkeLabeledExpand

Compute the output of the LabeledExpand function as defined in RFC9180.

Syntax

Public Function hpkeLabeledExpand ( _
    nBytes As Long, _
    lpPrk() As Byte, _
    szLabel As String, _
    lpInfo() As Byte, _
    szCurveName As String, _
    Optional nOptions As Long = 0 _
) As Byte()

Parameters

nBytes

Required number of bytes (L) of output keying material.

lpPrk

Pseudorandom key.

szLabel

Label string.

lpInfo

Byte string info.

szCurveName

Name of ECDH curve used in scheme. Specify one of:

 "P-256" | "P-384" | "P-521" | "X25519" | "X448"

nOptions

Use to specify the AEAD encryption algorithm used in the scheme (if applicable). Specify either: Zero (0) to indicate that the KDF is being used inside a KEM algorithm or, if used in the remainder of HPKE, one of:

PKI_AEAD_AES_128_GCM
PKI_AEAD_AES_256_GCM
PKI_AEAD_CHACHA20_POLY1305

Return Value

Remarks

hpkeLabeledExtract

Compute the output of the LabeledExtract function as defined in RFC9180.

Syntax

Public Function hpkeLabeledExtract ( _
    lpSalt() As Byte, _
    szLabel As String, _
    lpIkm() As Byte, _
    szCurveName As String, _
    Optional nOptions As Long = 0 _
) As Byte()

Parameters

lpSalt

Byte string salt.

szLabel

Label string.

lpIkm

Input keying material (ikm).

szCurveName

Name of ECDH curve used in scheme. Specify one of:

 "P-256" | "P-384" | "P-521" | "X25519" | "X448"

nOptions

Use to specify the AEAD encryption algorithm used in the scheme (if applicable). Specify either: Zero (0) to indicate that the KDF is being used inside a KEM algorithm or, if used in the remainder of HPKE, one of:

PKI_AEAD_AES_128_GCM
PKI_AEAD_AES_256_GCM
PKI_AEAD_CHACHA20_POLY1305

Return Value

Remarks

kdfBytes

Generate a key-encryption key (KEK) from input keying material (IKM) using a key derivation function (KDF).

Syntax

Public Function kdfBytes ( _
    nKekBytes As Long, _
    lpIkm() As Byte, _
    lpInfo() As Byte, _
    Optional nOptions As Long = 0, _
    Optional szParams As String = "" _
) As Byte()

Parameters

nKekBytes

Required length of output key material in bytes.

lpIkm

Input key material/shared secret.

lpInfo

SharedInfo (optional, but a properly dimensioned variable must be passed, even if empty).

nOptions

Algorithm to be used. Select one from:

PKI_KDF_X963 (default)
PKI_KDF_HKDF

and select one hash algorithm to use with the key derivation function:

PKI_HASH_SHA1 (default)
PKI_HASH_SHA224
PKI_HASH_SHA256
PKI_HASH_SHA384
PKI_HASH_SHA512

szParams

Optional parameters. Set as "" for defaults. Use salt=<hex-digits> to set the optional salt parameter for the HKDF algorithm encoded in hex, e.g. "salt=606162636465666768696a6b6c6d6e6f;".

Return Value

Remarks

Example

Dim lpKEK() As Byte
Dim lpZZ() As Byte
Dim lpInfo() As Byte
' ansx963_2001.rsp CAVS 12.0 'ANS X9.63-2001' information for sample
lpZZ = cnvFromHex("96c05619d56c328ab95fe84b18264b08725b85e33fd34f08")
lpKEK = kdfBytes(128 \ 8, lpZZ, lpInfo, PKI_HASH_SHA256)
Debug.Print "KEK = " & cnvToHex(lpKEK)
Debug.Print "OK  = 443024c3dae66b95e6f5670601558f71"
' [RFC 5869] A.1.  Test Case 1 Basic test case with SHA-256
lpZZ = cnvFromHex("0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b")
lpInfo = cnvFromHex("f0f1f2f3f4f5f6f7f8f9")
lpKEK = kdfBytes(42, lpZZ, lpInfo, PKI_KDF_HKDF Or PKI_HASH_SHA256, "salt=000102030405060708090a0b0c")
Debug.Print "KEK = " & cnvToHex(lpKEK)
Debug.Print "OK  = 3cb25f25faacd57a90434f64d0362f2a2d2d0a90cf1a5a4c5db02d56ecc4c5bf34007208d5b887185865"

kdfForCms

Generate a key-encryption key (KEK) for ECDH key exchange in a CMS EnvelopedData object.

Syntax

Public Function kdfForCms ( _
    lpZZ() As Byte, _
    lpUkm() As Byte, _
    Optional nOptions As Long = 0 _
) As Byte()

Parameters

lpZZ

Input key material/shared secret.

lpUkm

User key material (optional, but a properly dimensioned variable must be passed, even if empty).

nOptions

Algorithm to be used. Select one from:

PKI_KDF_X963 (default)
PKI_KDF_HKDF

and select one hash algorithm to use with the key derivation function:

PKI_HASH_SHA1 (default)
PKI_HASH_SHA224
PKI_HASH_SHA256
PKI_HASH_SHA384
PKI_HASH_SHA512

and select one key wrap algorithm (required, no default):

PKI_KWRAP_3DES
PKI_KWRAP_AES128
PKI_KWRAP_AES192
PKI_KWRAP_AES256

Return Value

Remarks

Example

Dim lpKEK() As Byte
Dim lpZZ() As Byte
Dim lpUkm() As Byte
lpZZ = cnvFromHex("160E3F5588C6FB4E9CEE8BC3C1C5000AB86396468C3D1CAEC0CB6E21536B5513")
lpKEK = kdfForCms(lpZZ, lpUkm, PKI_KWRAP_AES128 Or PKI_KDF_X963 Or PKI_HASH_SHA1)
Debug.Print "KEK = " & cnvToHex(lpKEK)
Debug.Print "OK  = 04D616C654CDF62BB186A5A088B60FB5"

ocspMakeRequest

Create an Online Certification Status Protocol (OCSP) request as a base64 string.

Syntax

Public Function ocspMakeRequest ( _
    szIssuerCert As String, _
    szCertFileOrSerialNum As String, _
    nOptions As Long, _
    Optional szExtensions As String = "" _
) As String

Parameters

szIssuerCert

Name of issuer's X.509 certificate file (or string with its base64 representation).

szCertFileOrSerialNum

Either the name of X.509 certificate file to be checked or its serial number in hexadecimal format preceded by #x.

nOptions

Algorithm to be used. Select one from:

PKI_HASH_SHA1
PKI_HASH_SHA224
PKI_HASH_SHA256
PKI_HASH_SHA384
PKI_HASH_SHA512
PKI_HASH_MD5

szExtensions

For future use.

Return Value

Remarks

ocspReadResponse

Read a response to an Online Certification Status Protocol (OCSP) request and outputs the main results in text form.

Syntax

Public Function ocspReadResponse ( _
    szResponseFile As String, _
    Optional szIssuerCert As String = "", _
    Optional nOptions As Long = 0, _
    Optional szExtensions As String = "" _
) As String

Parameters

szResponseFile

Name of the file containing the response data in BER format.

szIssuerCert

(optional) Name of issuer's X.509 certificate file (or string with its base64 representation).

nOptions

For future use.

szExtensions

For future use.

Return Value

Remarks

padBytesBlock

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

Syntax

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:

PKI_PAD_1ZERO
PKI_PAD_AX923
PKI_PAD_W3C

Return Value

padHexBlock

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

Syntax

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:

PKI_PAD_1ZERO
PKI_PAD_AX923
PKI_PAD_W3C

Return Value

padUnpadBytes

Removes the padding from an encryption block.

Syntax

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:

PKI_PAD_1ZERO
PKI_PAD_AX923
PKI_PAD_W3C

Return Value

Remarks

padUnpadHex

Removes the padding from a hex-encoded encryption block.

Syntax

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:

PKI_PAD_1ZERO
PKI_PAD_AX923
PKI_PAD_W3C

Return Value

Remarks

pbeKdf2

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

Syntax

Public Function pbeKdf2 ( _
    dkBytes As Long, _
    lpPwd() As Byte, _
    lpSalt() As Byte, _
    nCount 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.

nCount

Iteration count.

nOptions

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

PKI_HMAC_SHA1
PKI_HMAC_SHA224
PKI_HMAC_SHA256
PKI_HMAC_SHA384
PKI_HMAC_SHA512
PKI_HMAC_MD5

Return Value

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

Public Function pbeKdf2Hex ( _
    dkBytes As Long, _
    szPwd As String, _
    szSaltHex As String, _
    nCount 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.

nCount

Iteration count.

nOptions

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

PKI_HMAC_SHA1
PKI_HMAC_SHA224
PKI_HMAC_SHA256
PKI_HMAC_SHA384
PKI_HMAC_SHA512
PKI_HMAC_MD5

Return Value

pbeScrypt

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

Syntax

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

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

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

Example

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

pfxMakeFile

Create a PFX (PKCS-12) file from an X.509 certificate and (optional) encrypted private key file.

Syntax

Public Function pfxMakeFile ( _
    szFileOut As String, _
    szCertList As String, _
    Optional szKeyFile As String = "", _
    Optional szPassword As String = "", _
    Optional szFriendlyName As String = "", _
    Optional nOptions As Long = 0 _
) As Long

Parameters

szFileOut

Name of output file to be created.

szCertList

filename of the subject's X.509 certificate (or a string containing the certificate in base64 representation) followed by optional extra certificates to be included separated by a semicolon (;).

szKeyFile

Filename of the subject's encrypted private key in pkcs-8 format (optional).

szPassword

Password for private key file and new PFX file.

szFriendlyName

Friendly name identification for the subject (optional).

nOptions

Specialist options

PKI_PFX_CLONE_KEY
PKI_PFX_PLAIN_CERT
PKI_PFX_STRONG_CERT
PKI_PFX_AES256_SHA256
PKI_PFX_DOUBLE_ENCRYPT
PKI_KEY_FORMAT_PEM
PKI_PFX_ALT_FORMAT

Return Value

pkiCompileTime

Get date and time the CryptoSys PKI DLL module was last compiled.

Syntax

Public Function pkiCompileTime() As String

Return Value

pkiErrorCode

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

Syntax

Public Function pkiErrorCode() As Long

Return Value

Remarks

pkiErrorLookup

Get error message associated with a given error code.

Syntax

Public Function pkiErrorLookup ( _
    nErrCode As Long _
) As String

Parameters

nErrCode

Error code for which the message is required.

Return Value

pkiLastError

Get last error message set by previous function.

Syntax

Public Function pkiLastError() As String

Return Value

pkiLicenceType

Returns the ASCII value of the licence type.

Syntax

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

Parameters

nOptions

For future use.

Return Value

pkiModuleInfo

Get additional information about the core DLL module.

Syntax

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

Parameters

nOptions

For future use.

Return Value

pkiModuleName

Get path name of the current process's module.

Syntax

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

Parameters

nOptions

For future use.

Return Value

Example

Debug.Print pkiModuleName()
C:\WINDOWS\SYSTEM32\diCrPKI.dll

pkiPlatform

Get platform the core DLL was compiled for.

Syntax

Public Function pkiPlatform() As String

Return Value

pkiVersion

Get version number of native core DLL.

Syntax

Public Function pkiVersion() As Long

Return Value

prfBytes

Generate output bytes using a pseudorandom function (PRF).

Syntax

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:

PKI_KMAC_128
PKI_KMAC_256

szCustom

Customization string (optional).

Return Value

Remarks

pwdPrompt

Prompt for a password in a dialog box.

Syntax

Public Function pwdPrompt ( _
    Optional szCaption As String = "", _
    Optional szPrompt As String = "" _
) As String

Parameters

szCaption

Caption for the dialog box

szPrompt

Wording for prompt (optional, default="Enter Password:")

Return Value

rngBytes

Generate random bytes.

Syntax

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

Parameters

nBytes

Required number of random bytes.

Return Value

rngGuid

Generate a random 36-character Global Unique IDentifier (GUID) string.

Syntax

Public Function rngGuid() As String

Return Value

Example

Debug.Print rngGuid()
ba849198-168e-4632-a865-2761c9c8dd37

rngInitialize

Initialize the RNG generator using a seed file.

Syntax

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.

Return Value

rngInitializeEx

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

Syntax

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

Parameters

nOptions

Specify PKI_RNG_NO_INTEL_DRNG to explicitly turn off support.

Return Value

rsaDecodeMsg

Decode an EME or EMSA encoded message block according to PKCS#1.

Syntax

Public Function rsaDecodeMsg ( _
    lpInput() As Byte, _
    nOptions As Long _
) As Byte()

Parameters

lpInput

Data to be decoded.

nOptions

Include one of the following:

PKI_EME_PKCSV1_5
PKI_EME_OAEP
PKI_EMSIG_PKCSV1_5

If you have selected PKI_EMSIG_PKCSV1_5, then you can add PKI_EMSIG_DIGINFO to decode an 'Encoded Message for Signature' block and output the whole DigestInfo data instead of just the message digest.
If you have selected PKI_EME_OAEP, then add one of these options to match the hash function used for EME-OAEP encoding:

PKI_HASH_SHA1
PKI_HASH_SHA224
PKI_HASH_SHA256
PKI_HASH_SHA384
PKI_HASH_SHA512

and optionally add PKI_MGF_MGF1SHA1 to force the MGF hash function to be SHA-1 (default = same as encoding hash function set above).
Alternatively, ignore all the above and use the specialist option PKI_EMSIG_ISO9796 to use the ISO9796-1 encoding for a signature.

Return Value

Remarks

rsaDecrypt

Decrypt a message encrypted using an RSA encryption scheme.

Syntax

Public Function rsaDecrypt ( _
    lpInput() As Byte, _
    szPrivateKeyFile As String, _
    szPassword As String, _
    nOptions As Long, _
    Optional szParameters As String = "" _
) As Byte()

Parameters

lpInput

Data to be decrypted.

szPrivateKeyFile

Name of the private key file, or a string containing the key in PEM format, or a valid internal private key string.

szPassword

Password for encrypted private key, or "" if password is not required.

nOptions

Select one of the following:

PKI_EME_PKCSV1_5 (0 default)
PKI_EME_OAEP

szParameters

For future use.

Return Value

Remarks

rsaEncodeMsg

Encode an EME or EMSA encoded message block according to PKCS#1.

Syntax

Public Function rsaEncodeMsg ( _
    nBlockLen As Long, _
    lpInput() As Byte, _
    nOptions As Long _
) As Byte()

Parameters

nBlockLen

Length of output block in bytes (required).

lpInput

Data to be encoded.

nOptions

Include one of the following:

PKI_EME_PKCSV1_5
PKI_EME_OAEP
PKI_EMSIG_PKCSV1_5

If you have selected PKI_EMSIG_PKCSV1_5, then add one of these options to set the hash function for the signature message digest:

PKI_HASH_SHA1
PKI_HASH_SHA224
PKI_HASH_SHA256
PKI_HASH_SHA384
PKI_HASH_SHA512
PKI_HASH_MD5
PKI_HASH_MD2

and optionally add PKI_EMSIG_DIGESTONLY as a flag to pass the message digest only as input to-be-signed (default = pass entire message).
If you have selected PKI_EME_OAEP, then add one of these options to set the hash function used for EME-OAEP encoding:

PKI_HASH_SHA1
PKI_HASH_SHA224
PKI_HASH_SHA256
PKI_HASH_SHA384
PKI_HASH_SHA512

and optionally add PKI_MGF_MGF1SHA1 to force the MGF hash function to be SHA-1 (default = same as encoding hash function set above).
Alternatively, ignore all the above and use the specialist option PKI_EMSIG_ISO9796 to use the ISO9796-1 encoding for a signature.

Return Value

Remarks

rsaEncrypt

Encrypt a short message using RSA encryption.

Syntax

Public Function rsaEncrypt ( _
    lpInput() As Byte, _
    szPublicKeyFile As String, _
    Optional nOptions As Long = 0, _
    Optional szParameters As String = "" _
) As Byte()

Parameters

lpInput

Data to be encrypted.

szPublicKeyFile

Name of the public key file or X.509 certificate, or a string containing the key or certificate in PEM format, or a valid internal public key string.

nOptions

Select one of the following:

PKI_EME_PKCSV1_5 (0 default)
PKI_EME_OAEP

If you have selected PKI_EME_OAEP, then add one of these options to set the hash function for EME-OAEP encoding:

PKI_HASH_SHA1
PKI_HASH_SHA224
PKI_HASH_SHA256
PKI_HASH_SHA384
PKI_HASH_SHA512

and, optionally, add PKI_MGF_MGF1SHA1 to force the MGF hash function to be SHA-1 (default = same as encoding hash function set above).

szParameters

For future use.

Return Value

Remarks

rsaFromXMLString

Create an RSA key string in internal format from an XML string.

Syntax

Public Function rsaFromXMLString ( _
    szXmlString As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szXmlString

The RSA public or private key in XML format.

nOptions

Use default zero to include the private key, if present, or add one of:
PKI_XML_EXCLPRIVATE to exclude the private key even if present, or
PKI_XML_REQPRIVATE to require the private key to exist in the XML input or fail.

Return Value

rsaKeyBits

Get number of significant bits in RSA key modulus.

Syntax

Public Function rsaKeyBits ( _
    szKeyString As String _
) As Long

Parameters

szKeyString

Public or private key in internal string format.

Return Value

rsaKeyBytes

Get number of bytes (octets) in RSA key modulus.

Syntax

Public Function rsaKeyBytes ( _
    szKeyString As String _
) As Long

Parameters

szKeyString

Public or private key in internal string format.

Return Value

rsaKeyValue

Extract a base64-encoded RSA key value from internal key string.

Syntax

Public Function rsaKeyValue ( _
    szKeyString As String, _
    szFieldName As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szKeyString

Public or private key in internal string format.

szFieldName

Name of field to be extracted: "Modulus" or "Exponent".

nOptions

For future use.

Return Value

rsaMakeKeys

Generate an RSA public/private key pair and save as two key files.

Syntax

Public Function rsaMakeKeys ( _
    szPubKeyFile As String, _
    szPriKeyFile As String, _
    szPassword As String, _
    nBits As Long, _
    Optional nExpFermat As Long = PKI_RSAEXP_EQ_65537, _
    Optional szParams As String = "", _
    Optional nOptions As Long = 0 _
) As Long

Parameters

szPubKeyFile

Output filename for public key.

szPriKeyFile

Output filename for (encrypted) private key.

szPassword

Password for encrypted private key (required).

nBits

Required key modulus size in bits (min 96).

nExpFermat

Exponent [default=65537=F4]

szParams

Optional parameters. A set of attribute name=value pairs separated by a semicolon ";" (see remarks).

nOptions

Use 0 for defaults.
A flag to indicate the password-based encryption scheme to be used to encrypt the private key file. Select from:

PKI_PBE_SHA_3DES (0) for "pbeWithSHAAnd3-KeyTripleDES-CBC" from PKCS12 (default)
PKI_PBE_PBKDF2_DESEDE3 for PBKDF2 using des-EDE3-CBC
PKI_PBE_PBKDF2_AES128 for PBKDF2 using aes128-CBC
PKI_PBE_PBKDF2_AES192 for PBKDF2 using aes192-CBC
PKI_PBE_PBKDF2_AES256 for PBKDF2 using aes256-CBC

plus optionally one of the following to output in textual PEM format [default format=DER binary]

PKI_KEY_FORMAT_PEM
PKI_KEY_FORMAT_SSL

and, optionally, add PKI_KEYGEN_INDICATE to indicate progress in a console window.

Return Value

Remarks

Example

' Create a 2048-bit RSA key pair using defaults
r = rsaMakeKeys("myrsa2048.pub", "myrsa2048.p8e", "password", 2048)
' Same but using stronger security and in PEM format
r = rsaMakeKeys("myrsa2048ex.pub", "myrsa2048ex.p8e", "password1", 2048,,"count=6000;prf=hmacWithSHA256", PKI_PBE_PBKDF2_AES128 Or PKI_KEY_FORMAT_PEM)

rsaPublicKeyFromPrivate

Convert an internal RSA private key string into an internal public key string.

Syntax

Public Function rsaPublicKeyFromPrivate ( _
    szKeyString As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szKeyString

Private key in internal string format.

nOptions

For future use.

Return Value

rsaRawPrivate

Carry out RSA transformation on raw data using private key.

Syntax

Public Function rsaRawPrivate ( _
    lpData() As Byte, _
    szPrivateKey As String, _
    Optional nOptions As Long = 0 _
) As Byte()

Parameters

lpData

Data to be transformed.

szPrivateKey

Private key in internal string format.

nOptions

For future use.

Return Value

Remarks

rsaRawPublic

Carry out RSA transformation on raw data using public key.

Syntax

Public Function rsaRawPublic ( _
    lpData() As Byte, _
    szPublicKey As String, _
    Optional nOptions As Long = 0 _
) As Byte()

Parameters

lpData

Data to be transformed.

szPublicKey

Public key in internal string format.

nOptions

For future use.

Return Value

Remarks

rsaReadAnyPrivateKey

Read private key from a file or string containing a key into an "internal" public key string.

Syntax

Public Function rsaReadAnyPrivateKey ( _
    szKeyFileOrString As String, _
    Optional szPassword As String = "", _
    Optional nOptions As Long = 0 _
) As String

Parameters

szKeyFileOrString

Name of file containing the key, or a string containing the key in PEM format or XML format.

szPassword

Password, if the key is encrypted, or "" if not.

nOptions

For future use.

Return Value

Remarks

rsaReadAnyPublicKey

Read public key from a file or string containing a key into an "internal" public key string.

Syntax

Public Function rsaReadAnyPublicKey ( _
    szKeyFileOrString As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szKeyFileOrString

Name of file containing the key, or a string containing the key in PEM format or XML format.

nOptions

For future use.

Return Value

Remarks

rsaReadPrivateKey

Read private key from a file or string containing a key into an "internal" public key string.

Syntax

Public Function rsaReadPrivateKey ( _
    szKeyFileOrString As String, _
    Optional szPassword As String = "", _
    Optional nOptions As Long = 0 _
) As String

Parameters

szKeyFileOrString

Name of file containing the key, or a string containing the key in PEM format or XML format.

szPassword

Password, if the key is encrypted, or "" if not.

nOptions

For future use.

Return Value

rsaReadPublicKey

Read public key from a file or string containing a key into an "internal" public key string.

Syntax

Public Function rsaReadPublicKey ( _
    szKeyFileOrString As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szKeyFileOrString

Name of file containing the key, or a string containing the key in PEM format or XML format.

nOptions

For future use.

Return Value

rsaSaveEncKey

Save an internal RSA key string to an encrypted key file.

Syntax

Public Function rsaSaveEncKey ( _
    szOutputFile As String, _
    szKeyStr As String, _
    szPassword As String, _
    Optional szParams As String = "", _
    Optional nOptions As Long = 0 _
) As Long

Parameters

szOutputFile

Name of output file to be created.

szKeyStr

The private RSA key as an internal key string.

szPassword

Password for encrypted private key (required).

szParams

Optional parameters. A set of attribute name=value pairs separated by a semicolon ";" (see remarks).

nOptions

Use 0 for defaults.
A flag to indicate the password-based encryption scheme to be used to encrypt the private key file. Select from:

PKI_PBE_SHA_3DES (0) for "pbeWithSHAAnd3-KeyTripleDES-CBC" from PKCS12 (default)
PKI_PBE_PBKDF2_DESEDE3 for PBKDF2 using des-EDE3-CBC
PKI_PBE_PBKDF2_AES128 for PBKDF2 using aes128-CBC
PKI_PBE_PBKDF2_AES192 for PBKDF2 using aes192-CBC
PKI_PBE_PBKDF2_AES256 for PBKDF2 using aes256-CBC

plus optionally one of the following to output in textual PEM format [default format=DER binary]

PKI_KEY_FORMAT_PEM
PKI_KEY_FORMAT_SSL

Return Value

Remarks

rsaSaveKey

Save an internal RSA key string to a key file.

Syntax

Public Function rsaSaveKey ( _
    szOutputFile As String, _
    szKeyStr As String, _
    Optional nOptions As Long = 0 _
) As Long

Parameters

szOutputFile

Name of output file to be created.

szKeyStr

Key string (public or private) in internal format.

nOptions

Add one of the following to output in textual PEM format [default (0) format=DER binary]

PKI_KEY_FORMAT_PEM
PKI_KEY_FORMAT_SSL

Return Value

Remarks

rsaToXMLString

Create an XML string representation of an RSA internal key string.

Syntax

Public Function rsaToXMLString ( _
    szKeyString As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szKeyString

The RSA public or private key in internal format.

nOptions

Default (0) to output in appropriate W3C standard format (RSAKeyValue for public key and RSAKeyPair for private key), or select and combine:
PKI_XML_RSAKEYVALUE to force private key output as .NET-compatible RSAKeyValue format (instead of W3C RSAKeyPair)
PKI_XML_EXCLPRIVATE to exclude the private key (use to get a public key RSAKeyValue from a private key)
PKI_XML_HEXBINARY to output with data in non-conforming (but convenient) hexBinary format.

Return Value

rsaToXMLStringEx

Create an XML string representation of an RSA internal key string with option to add a namespace prefix.

Syntax

Public Function rsaToXMLStringEx ( _
    szKeyString As String, _
    szPrefix As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szKeyString

The RSA public or private key in internal format.

szPrefix

Namespace prefix to be added to all elements, e.g. "ds".

nOptions

Default (0) to output in appropriate W3C standard format (RSAKeyValue for public key and RSAKeyPair for private key), or select and combine:
PKI_XML_RSAKEYVALUE to force private key output as .NET-compatible RSAKeyValue format (instead of W3C RSAKeyPair)
PKI_XML_EXCLPRIVATE to exclude the private key (use to get a public key RSAKeyValue from a private key)
PKI_XML_HEXBINARY to output with data in non-conforming (but convenient) hexBinary format.

Return Value

Remarks

sigSignData

Compute a signature value over data in a byte array.

Syntax

Public Function sigSignData ( _
    lpData() As Byte, _
    szKeyFile As String, _
    szPassword As String, _
    szAlgName As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

lpData

Data to be signed.

szKeyFile

name of the private key file or a string containing the key in PEM format, or a valid internal private key string.

szPassword

Password for the private key, or "" if not required.

szAlgName

Signature algorithm to be used:

"sha1WithRSAEncryption"
"sha224WithRSAEncryption"
"sha256WithRSAEncryption"
"sha384WithRSAEncryption"
"sha512WithRSAEncryption"
"md5WithRSAEncryption"
"ecdsaWithSHA1"
"ecdsaWithSHA224"
"ecdsaWithSHA256"
"ecdsaWithSHA384"
"ecdsaWithSHA512"
"RSA-PSS-SHA1"
"RSA-PSS-SHA224"
"RSA-PSS-SHA256"
"RSA-PSS-SHA384"
"RSA-PSS-SHA512"
"Ed25519"

nOptions

Use 0 for defaults.
Add the bitflag PKI_SIG_USEDIGEST to pass the digest value of the data-to-be-signed as the lpData argument.
To change the format of the output (default base64 encoded), add one of:

PKI_ENCODE_BASE64URL
PKI_ENCODE_HEX

Options for ECDSA signatures only:

PKI_SIG_DETERMINISTIC
PKI_SIG_ASN1DER

Options for RSA-PSS signatures only to set the salt length (default = hLen):

PKI_PSS_SALTLEN_HLEN
PKI_PSS_SALTLEN_MAX
PKI_PSS_SALTLEN_20
PKI_PSS_SALTLEN_ZERO

and, optionally, add PKI_MGF_MGF1SHA1 (RSA-PSS only) to force the MGF hash function to be SHA-1 (default = same as signature hash algorithm).

Return Value

sigSignFile

Compute a signature value over data in a file.

Syntax

Public Function sigSignFile ( _
    szDataFile As String, _
    szKeyFile As String, _
    szPassword As String, _
    szAlgName As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szDataFile

Name of file to be signed.

szKeyFile

name of the private key file or a string containing the key in PEM format, or a valid internal private key string.

szPassword

Password for the private key, or "" if not required.

szAlgName

Signature algorithm to be used:

"sha1WithRSAEncryption"
"sha224WithRSAEncryption"
"sha256WithRSAEncryption"
"sha384WithRSAEncryption"
"sha512WithRSAEncryption"
"md5WithRSAEncryption"
"ecdsaWithSHA1"
"ecdsaWithSHA224"
"ecdsaWithSHA256"
"ecdsaWithSHA384"
"ecdsaWithSHA512"
"RSA-PSS-SHA1"
"RSA-PSS-SHA224"
"RSA-PSS-SHA256"
"RSA-PSS-SHA384"
"RSA-PSS-SHA512"

nOptions

Use 0 for defaults.
To change the format of the output (default base64 encoded), add one of:

PKI_ENCODE_BASE64URL
PKI_ENCODE_HEX

Options for ECDSA signatures only:

PKI_SIG_DETERMINISTIC
PKI_SIG_ASN1DER

Options for RSA-PSS signatures only to set the salt length (default = hLen):

PKI_PSS_SALTLEN_HLEN
PKI_PSS_SALTLEN_MAX
PKI_PSS_SALTLEN_20
PKI_PSS_SALTLEN_ZERO

and, optionally, add PKI_MGF_MGF1SHA1 (RSA-PSS only) to force the MGF hash function to be SHA-1 (default = same as signature hash algorithm).

Return Value

Remarks

sigVerifyData

Verify a signature value over data in a byte array.

Syntax

Public Function sigVerifyData ( _
    szSignature As String, _
    lpData() As Byte, _
    szCertOrKey As String, _
    szAlgName As String, _
    Optional nOptions As Long = 0 _
) As Long

Parameters

szSignature

Encoded signature value

lpData

Data to be verified.

szCertOrKey

Name of X.509 certificate or public key file, or a string containing the certificate in base64 representation, or the public key in PEM format, or a valid internal public key string.

szAlgName

Signature algorithm to be used:

"sha1WithRSAEncryption"
"sha224WithRSAEncryption"
"sha256WithRSAEncryption"
"sha384WithRSAEncryption"
"sha512WithRSAEncryption"
"md5WithRSAEncryption"
"ecdsaWithSHA1"
"ecdsaWithSHA224"
"ecdsaWithSHA256"
"ecdsaWithSHA384"
"ecdsaWithSHA512"
"RSA-PSS-SHA1"
"RSA-PSS-SHA224"
"RSA-PSS-SHA256"
"RSA-PSS-SHA384"
"RSA-PSS-SHA512"
"Ed25519"

nOptions

Use 0 for defaults. Add the bitflag PKI_SIG_USEDIGEST to pass the digest value of the data-to-be-signed as the lpData argument instead of the data itself. Add PKI_MGF_MGF1SHA1 (RSA-PSS only) to force the MGF hash function to be SHA-1 (default = same as signature hash algorithm).

Return Value

smimeQuery

Query an S/MIME entity for selected information.

Syntax

Public Function smimeQuery ( _
    szFileIn As String, _
    szQuery As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szFileIn

Name of input file.

szQuery

Query string (case insensitive). Valid queries are:

"content-type"
"smime-type"
"encoding"
"name"
"filename"

nOptions

For future use.

Return Value

Example

Debug.Print smimeQuery("cmsalice2bob-smime-env.txt", "smime-type")
enveloped-data

wipeBytes

Wipe a byte array securely.

Syntax

Public Function wipeBytes ( _
    ByRef lpToWipe() As Byte _
) As Byte()

Parameters

lpToWipe

Byte array to be wiped.

Return Value

Example

Dim lpData() As Byte
lpData = cnvFromHex("DEADBEEF")
Debug.Print "BEFORE: 0x(" & cnvToHex(lpData) & ")" ' BEFORE: 0x(DEADBEEF)
Call wipeBytes(lpData)
Debug.Print "AFTER: 0x(" & cnvToHex(lpData) & ")" ' AFTER: 0x()

wipeString

Wipe a string securely and return an empty string.

Syntax

Public Function wipeString ( _
    ByRef szToWipe As String _
) As String

Parameters

szToWipe

String to be wiped.

Return Value

Remarks

Example

Dim strData As String
strData = "my deepest secrets"
strData = wipeString(strData)

x509CertThumb

Calculate the thumbprint (message digest value) of an X.509 certificate.

Syntax

Public Function x509CertThumb ( _
    szCertFile As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szCertFile

Name of input file.

nOptions

Algorithm to be used. Select one from:

PKI_HASH_SHA1 (0 = default)
PKI_HASH_SHA224
PKI_HASH_SHA256
PKI_HASH_SHA384
PKI_HASH_SHA512
PKI_HASH_MD5

Return Value

x509HashIssuerAndSN

Calculate the message digest hash of the PKCS #7 issuerAndSerialNumber value of an X.509 certificate.

Syntax

Public Function x509HashIssuerAndSN ( _
    szCertFile As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szCertFile

Name of input file.

nOptions

Algorithm to be used. Select one from:

PKI_HASH_SHA1 (0 = default)
PKI_HASH_SHA224
PKI_HASH_SHA256
PKI_HASH_SHA384
PKI_HASH_SHA512
PKI_HASH_MD5

Return Value

x509QueryCert

Query an X.509 certificate file for selected information.

Syntax

Public Function x509QueryCert ( _
    szCertFile As String, _
    szQuery As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szCertFile

Name of X.509 certificate file (or base64 representation).

szQuery

Query string (case insensitive). Valid queries are:

"version"
"serialNumber"
"signatureAlgorithm"
"sigAlgId"
"signatureValue"
"notBefore"
"notAfter"
"issuerName"
"subjectName"
"subjectPublicKeyAlgorithm"
"subjectKeyIdentifier"
"authorityKeyIdentifier"
"rfc822Name"
"isCA"
"keyUsageString"
"extKeyUsageString"
"cRLDistributionPointsURI"
"authorityInfoAccessURI"
"subjectAltName"
"hashAlgorithm"
"pssParams"

nOptions

Use 0 for default or add any of:

PKI_X509_LATIN1 or PKI_X509_UTF8
PKI_X509_LDAP
PKI_X509_DECIMAL

Return Value

Remarks

Example

Debug.Print x509QueryCert("AliceRSASignByCarl.cer", "subjectName")
CN=AliceRSA

x509ReadCertStringFromP7Chain

Read an X.509 certificate into a base64-encoded string from PKCS-7 "certs-only" data.

Syntax

Public Function x509ReadCertStringFromP7Chain ( _
    szP7cFile As String, _
    nIndex As Long, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szP7cFile

Filename of a PKCS-7 "certs-only" file, or a string containing its PEM textual representation.

nIndex

Index of certificate (1,2,...) in the chain to extract.

nOptions

For future use.

Return Value

Remarks

x509ReadCertStringFromPFX

Read an X.509 certificate into a base64-encoded string from PKCS-12 PFX/.p12 data.

Syntax

Public Function x509ReadCertStringFromPFX ( _
    szPfxFile As String, _
    szPassword As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szPfxFile

Filename of a PFX file, or a string containing its PEM textual representation.

szPassword

Password or "" if certificate is not encrypted.

nOptions

For future use.

Return Value

x509ReadStringFromFile

Read an X.509 certificate into a base64-encoded string.

Syntax

Public Function x509ReadStringFromFile ( _
    szCertFile As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szCertFile

Name of X.509 certificate file.

nOptions

For future use.

Return Value

x509TextDumpToString

Dump details of an X.509 certificate or a X.509 certificate revocation list (CRL) or a PKCS-10 certificate signing request (CSR) to a string.

Syntax

Public Function x509TextDumpToString ( _
    szCertFile As String, _
    Optional nOptions As Long = 0 _
) As String

Parameters

szCertFile

Name of input file (or its base64 or PEM string representation).

nOptions

Use 0 for default or add any of:

PKI_X509_LATIN1
PKI_X509_LDAP
PKI_X509_DECIMAL

Return Value

xofBytes

Generate bytes using an eXtendable-Output Function (XOF).

Syntax

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:

PKI_XOF_SHAKE128
PKI_XOF_SHAKE256
PKI_XOF_MGF1_SHA1
PKI_XOF_MGF1_SHA256
PKI_XOF_MGF1_SHA512

Return Value

Remarks

Index