Dumps details of ASN.1 formatted data to a text file.

Parameters

[in]	szFileOut	filename of text file to be created.
[in]	szFileOrPEMString	filename of ASN.1 formatted data file to be analyzed (or its base64 representation or PEM string).
[in]	nOptions	option flags: PKI_ASN1_NOCOMMENTS to hide the comments PKI_ASN1_ADDLEVELS to show level numbers

Returns

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

Remarks

The input may be a binary file in BER/DER format or a text file in PEM or base64-encoded format, or may be passed as a base64 string or as a PEM string.

Only data with an outer SEQUENCE is accepted, which is the rule for all common PKI-related ASN.1 files.

The output is a text file showing the structure of the ASN.1 formatted data. All the bytes in the input are printed in hexadecimal form laid out to show the nested structure of the ASN.1 formatted data together with comments beginning with "--" that give further details about the elements. The length of each object is shown in bytes, for example

30 81 e0  --SEQUENCE/224 bytes

shows the tag (30) and length bytes (81 e0) which begin a SEQUENCE of length 224 bytes, equal to hexadecimal E0 bytes.

Use the PKI_ASN1_NOCOMMENTS option to hide the comments: the resulting hexadecimal output without comments should decode back directly to the original binary file.

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

Parameters

[out]	szOutput	String buffer to receive output.
[in]	nOutChars	Maximum number of characters to be received.
[in]	szFileOrPEMString	Filename of ASN.1 formatted data file to be analyzed (or its base64 representation or PEM string).
[in]	szDirName	Directory in which to create a temporary file. Specify "" for default = system TEMP directory.
[in]	nOptions	option flags: PKI_ASN1_NOCOMMENTS to hide the comments PKI_ASN1_ADDLEVELS to show level numbers

Returns

If successful, the return value is the number of characters in or required for the output string; otherwise it returns a nonzero error code.

Remarks

For the "raw" VBA/C function, the user must allocate an output string buffer szOutput of the required length. Specify a zero nOutChars or an empty string for szOutput to find the required length. ANSI C users must add one to this value when allocating memory.

The input may be a binary file in BER/DER format or a text file in PEM or base64-encoded format, or may be passed as a base64 string or as a PEM string.

Only data with an outer SEQUENCE is accepted, which is the rule for all common PKI-related ASN.1 files.

The output is a text file showing the structure of the ASN.1 formatted data. All the bytes in the input are printed in hexadecimal form laid out to show the nested structure of the ASN.1 formatted data together with comments beginning with "--" that give further details about the elements. The length of each object is shown in bytes, for example

30 81 e0  --SEQUENCE/224 bytes

shows the tag (30) and length bytes (81 e0) which begin a SEQUENCE of length 224 bytes, equal to hexadecimal E0 bytes.

Use the PKI_ASN1_NOCOMMENTS option to hide the comments: the resulting hexadecimal output without comments should decode back directly to the original binary file.

This function creates a temporary file, by default in the system TEMP directory. This file is locked and is automatically deleted after use. The user can specify a particular directory known to be secure if required. If the specified directory does not exist, the system TEMP directory will be used.

Describes the type of ASN.1 data.

Parameters

[out]	szOutput	string of sufficient length to receive the output (guaranteed not to be longer than PKI_ASN1_TYPE_MAXCHARS).
[in]	nOutChars	specifying the maximum number of characters to be received.
[in]	szFileOrPEMString	filename of ASN.1 formatted data file to be analyzed (or its base64 representation or PEM string).
[in]	nOptions	option flags: not used in this release. Specify zero.

Returns

If successful, the return value is the number of characters in or required for the output string; otherwise it returns a negative error code.

Remarks

For the "raw" VBA/C function, the user must allocate an output string buffer szOutput of the required length. Specify a zero nOutChars or an empty string for szOutput to find the required length. ANSI C users must add one to this value when allocating memory.

The input may be a binary file in BER/DER format or a text file in PEM or base64 format, or may be passed as a base64 string or as a PEM string. The output is a string describing the most likely type of the ASN.1-formatted data, or an empty string ("") if the type cannot be determined. The following types are detected:

Note that these descriptions are not necessarily those used as labels for PEM formatted files. See PEM_FileFromBinFile and [RFC7468].

Encrypt or decrypt data in a byte array.

The key and initialization vector are given as byte arrays.

Deprecated:

Use CIPHER_EncryptBytes or CIPHER_DecryptBytes instead.

Parameters

[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[out]	lpOutput	array of sufficient length to receive the output.
[in]	lpData	array containing the input data.
[in]	nDataLen	specifying the length of the input data in bytes.
[in]	lpKey	array containing the key.
[in]	lpIV	containing the initialization vector (IV), or zero (0) for ECB mode.
[in]	szAlgAndMode	containing the block cipher algorithm and mode (see Specifying the algorithm and mode for generic block cipher functions).
[in]	nOptions	option flags.

Returns

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

Remarks

The algorithm and mode must be specified using either the szAlgAndMode or nOptions parameter (see Specifying the algorithm and mode for generic block cipher functions).

The length of key lpKey must be exactly the required key size, and the length of the IV, if required, exactly the block size. See Valid key and block sizes.

Important: The output array lpOutput must be at least nDataLen bytes long. lpOutput and lpData may be the same.

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

Decrypt data using an authenticated encryption algorithm.

Parameters

[out]	lpOutput	array of sufficient length to receive the output.
[in]	nOutBytes	length of the output buffer in bytes.
[in]	lpInput	array containing the input data.
[in]	nInputLen	length of the input data in bytes.
[in]	lpKey	array containing the key.
[in]	nKeyLen	length of the key in bytes.
[in]	lpIV	initialization vector (IV), a.k.a. nonce, if not provided in input.
[in]	nIvLen	length of the IV in bytes.
[in]	lpAAD	additional authenticated data (AAD)
[in]	nAadLen	length of the AAD in bytes.
[in]	nOptions	option flags. Must be one of: PKI_AEAD_AES_128_GCM to use AEAD_AES_128_GCM authenticated encryption algorithm from RFC 5116 PKI_AEAD_AES_256_GCM to use AEAD_AES_256_GCM authenticated encryption algorithm from RFC 5116 PKI_AEAD_AES_192_GCM to use the AES-192-GCM authenticated encryption algorithm in the same manner PKI_AEAD_CHACHA20_POLY1305 to use the AEAD_CHACHA20_POLY1305 authenticated encryption algorithm (RFC8439) and optionally add PKI_IV_PREFIX to expect the IV to be prepended at the start of the input.

Returns

If successful, the return value is the number of bytes required in the output; otherwise it returns a negative error code.

Remarks

The input is expected to be the ciphertext with a 16-byte tag appended ciphertext||Tag, or, if the PKI_IV_PREFIX option is set, then the same but with the 12-byte IV prepended IV||ciphertext||Tag, where || denotes concatenation. If the IV is not prepended to the input, then it must be provided in the lpIV argument. Note that the term "IV" is used here to mean exactly the same as "nonce".

The length of key lpKey must be exactly the required key size in bytes: 16 for PKI_AEAD_AES_128_GCM, 24 for PKI_AEAD_AES_192_GCM, or 32 for PKI_AEAD_AES_256_GCM. It is an error if a PKI_AEAD_ option is not provided in the nOptions argument. In all cases the IV must be exactly 12 bytes (96 bits) and the tag must be exactly 16 bytes (128 bits). If additional authentication data (AAD) was provided during encryption then the exact same AAD data must be provided here.

If nOutBytes is set to zero or lpOutput set to 0 (or NULL in C or ByVal 0& in VBA), the required number of bytes will be returned. This will be either exactly 16 bytes shorter than the length of the input, or exactly 28 bytes shorter if the PKI_IV_PREFIX option is used.

The output buffer lpOutput must not be the same as or overlap with the input lpInput.

Decrypt data in a byte array using the specified block cipher algorithm, mode and padding.

The key and initialization vector are passed as byte arrays.

Parameters

[out]	lpOutput	array of sufficient length to receive the output (must be at least as long as the input, see ** in remarks)).
[in]	nOutBytes	specifying the length of the output buffer in bytes.
[in]	lpInput	array containing the input data.
[in]	nInputLen	specifying the length of the input data in bytes.
[in]	lpKey	array containing the key.
[in]	nKeyLen	the length of the key in bytes.
[in]	lpIV	containing the initialization vector (IV), or zero (0) or NULL for ECB mode.
[in]	nIvLen	the length of the IV in bytes.
[in]	szAlgModePad	containing the block cipher algorithm, mode and padding (see Specifying the algorithm, mode and padding for generic block cipher functions).
[in]	nOptions	option flags: Zero (0) for default options. Optionally add: PKI_IV_PREFIX to expect the IV to be prepended before the ciphertext in the input (ignored for ECB mode).

Returns

If successful, the return value is the number of bytes in or required in the output; otherwise it returns a negative error code.

Remarks

The algorithm/mode/padding must be specified using either the szAlgModePad string or nOptions parameter, but not both (see Specifying the algorithm, mode and padding for generic block cipher functions).

The length of key lpKey must be exactly the required key size, and the length of the IV, if required, exactly the block size. See Valid key and block sizes.

[New in v12.3] You can find the required output length in bytes by setting nOutBytes to zero or lpOutput to 0 (or NULL in C or ByVal 0& in VBA). For ECB and CBC cipher modes, the return value is now (as of [v12.3]) the exact length of plaintext after padding has been removed.

^** For ECB and CBC cipher modes, any padding must be removed. To specify the length of lpOutput you can either

1. [ORIGINAL METHOD] specify the output length of lpOutput equal to the length of the input then truncate the result to the correct length.
2. [NEW in v12.3] do a first pass setting nOutBytes to zero or lpOutput to 0 or NULL to find the exact decrypted length.

See the examples below. In both cases you may need to cope with the special case where the encrypted output is the empty string, a zero-length byte array.

It is an error (DECRYPT_ERROR) if the padding bytes after decryption are not as expected according to the padding method specified. If the cipher mode is ECB or CBC, it is an error (BAD_LENGTH_ERROR) if the length of the input is not an exact multiple of the block size. The input buffer lpInput may point to the same location as the output buffer. If so, the input ciphertext data will be overwritten by the output (and the user must truncate to remove any padding bytes).

Defaults: If padding is not specified then the default padding method depends on the cipher mode: pkcs5padding will be used for ECB and CBC mode and nopadding for all other modes. The default cipher mode is ECB. Thus "aes128" is the same as "aes128/ecb/pkcs5padding".

Decrypt data using the specified block cipher algorithm, mode and padding.

The input data, key and initialization vector are all represented as hexadecimal strings.

Parameters

[out]	szOutput	string buffer of sufficient length to receive the output.
[in]	nOutChars	maximum number of characters to be received.
[in]	szInputHex	the input data in hex format.
[in]	szKeyHex	the key in hex format.
[in]	szIvHex	the initialization vector (IV) in hex format, ignored for ECB mode or if PKI_IV_PREFIX is used (use "").
[in]	szAlgModePad	string specifying the block cipher algorithm, mode and padding (see Specifying the algorithm, mode and padding for generic block cipher functions).
[in]	nOptions	option flags: Zero (0) for default options. Optionally add: PKI_IV_PREFIX to expect the IV to be prepended before the ciphertext in the input (not applicable for ECB mode).

Returns

If successful, the return value is the number of characters in or required in the output; otherwise it returns a nonzero error code.

Remarks

For the "raw" VBA/C function, the user must allocate an output string buffer szOutput of the required length. Specify a zero nOutChars or an empty string for szOutput to find the required length. ANSI C users must add one to this value when allocating memory.

This is the equivalent of CIPHER_DecryptBytes with all parameters passed as hex-encoded strings instead of byte arrays. It is similar to the CIPHER_Hex function except this accepts variable-length input and copes with padding if required, as well as the option to prepend the IV to the ciphertext.

Any padding will be removed after decryption.

If the PKI_IV_PREFIX option is used, the IV will be expected prepended to the ciphertext in the input.

The algorithm/mode/padding must be specified using either the szAlgModePad string or nOptions parameter, but not both (see Specifying the algorithm, mode and padding for generic block cipher functions).

It is an error (BAD_PARAM_ERROR) to pass the empty string "" as input in szInputHex. The output buffer strOutput should not be the same as the input strInputHex.

CAUTION: be aware of the special case where the output is the empty string "" of length zero.

Encrypt data using an authenticated encryption algorithm.

Parameters

[out]	lpOutput	array of sufficient length to receive the output.
[in]	nOutBytes	length of the output buffer in bytes.
[in]	lpInput	array containing the input data.
[in]	nInputLen	length of the input data in bytes.
[in]	lpKey	array containing the key.
[in]	nKeyLen	length of the key in bytes.
[in]	lpIV	(required) initialization vector (IV), a.k.a. nonce.
[in]	nIvLen	length of the IV in bytes (must be exactly 12).
[in]	lpAAD	(optional) additional authenticated data (AAD)
[in]	nAadLen	length of the AAD in bytes.
[in]	nOptions	option flags. Must be one of: PKI_AEAD_AES_128_GCM to use AEAD_AES_128_GCM authenticated encryption algorithm from RFC 5116 PKI_AEAD_AES_256_GCM to use AEAD_AES_256_GCM authenticated encryption algorithm from RFC 5116 PKI_AEAD_AES_192_GCM to use the AES-192-GCM authenticated encryption algorithm in the same manner PKI_AEAD_CHACHA20_POLY1305 to use the AEAD_CHACHA20_POLY1305 authenticated encryption algorithm (RFC 8439) and optionally add PKI_IV_PREFIX to prepend the IV before the ciphertext in the output.

Returns

If successful, the return value is the number of bytes required in the output; otherwise it returns a negative error code.

Remarks

This function carries out authenticated encryption using AES-GCM. In this implementation, the function
must have a fixed-length nonce (IV) of exactly 12 bytes (96 bits) and only creates a fixed-length tag of exactly 16 bytes (128 bits). There is no option to use different lengths for the IV or tag. The tag is automatically appended to the output of the encryption operation. The IV may optionally be prepended to the output using the PKI_IV_PREFIX option flag. Note that the term "IV" is used here to mean exactly the same as "nonce".

The length of key lpKey must be exactly the required key size in bytes: 16 for PKI_AEAD_AES_128_GCM, 24 for PKI_AEAD_AES_192_GCM, or 32 for PKI_AEAD_AES_256_GCM. It is an error if a PKI_AEAD_ option is not provided in the nOptions argument. The length of the IV must be exactly 12 bytes. The user is responsible for providing a unique IV each time the same key is used. Be aware it is a serious security risk if the same IV and key are used to encrypt different plaintexts.

If nOutBytes is set to zero or lpOutput set to 0 (or NULL in C or ByVal 0& in VBA), the required number of bytes will be returned. This will be either exactly 16 bytes longer than the length of the input, or exactly 28 bytes longer if the PKI_IV_PREFIX option is used.

The output buffer lpOutput must not be the same as or overlap with the input lpInput.

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.

Parameters

[out]	lpOutput	array of sufficient length to receive the output.
[in]	nOutBytes	specifying the length of the output buffer in bytes.
[in]	lpInput	array containing the input data.
[in]	nInputLen	specifying the length of the input data in bytes.
[in]	lpKey	array containing the key.
[in]	nKeyLen	the length of the key in bytes.
[in]	lpIV	containing the initialization vector (IV), or zero (0) or NULL for ECB mode.
[in]	nIvLen	the length of the IV in bytes.
[in]	szAlgModePad	containing the block cipher algorithm, mode and padding (see Specifying the algorithm, mode and padding for generic block cipher functions).
[in]	nOptions	option flags: Zero (0) for default options. Optionally add: PKI_IV_PREFIX to prepend the IV before the ciphertext in the output (ignored for ECB mode).

Returns

If successful, the return value is the number of bytes required in the output; otherwise it returns a negative error code.

Remarks

Padding is added as specified to the input before encryption. The user must allocate an output buffer of the required length, which will always be at least as long as the input, or longer if padding is to be added.

The algorithm/mode/padding must be specified using either the szAlgModePad string or nOptions parameter, but not both (see Specifying the algorithm, mode and padding for generic block cipher functions).

The length of key lpKey must be exactly the required key size, and the length of the IV, if required, exactly the block size. See Valid key and block sizes.

If nOutBytes is set to zero or lpOutput set to 0 (or NULL in C or ByVal 0& in VBA), the required number of bytes will be returned. If the NoPadding option is specified, the required output length will be the same as the input.

Defaults: If padding is not specified then the default padding method depends on the cipher mode: pkcs5padding will be used for ECB and CBC mode and nopadding for all other modes. The default cipher mode is ECB. Thus "aes128" is the same as "aes128/ecb/pkcs5padding".

Note that padding is only needed for ECB or CBC mode where the input length is not a multiple of the block size. It is an error (BAD_LENGTH_ERROR) to specify NoPadding with ECB or CBC mode if the length of the input is not an exact multiple of the block size.

The padding option is ignored for CTR, OFB and CFB modes, which do not need padding. The default nopadding is always used for these modes regardless of what is specified (so just use the default, e.g. "aes128/ctr").

[New in v12.3] Use the PKI_IV_PREFIX to prepend the IV before the ciphertext in the output. This will add the IV before the ciphertext in the form IV||CT. This is the scheme used with block ciphers in XML encryption (see section 5.2 of [XMLENC]) where they use the phrase "The resulting cipher text is prefixed by the IV." It is the responsibility of the receiver to parse this data to recover the IV.

Encrypt data using the specified block cipher algorithm, mode and padding.

The input data, key and initialization vector are all represented as hexadecimal strings.

Parameters

[out]	szOutput	string buffer of sufficient length to receive the output.
[in]	nOutChars	maximum number of characters to be received.
[in]	szInputHex	the input data in hex format.
[in]	szKeyHex	the key in hex format.
[in]	szIvHex	the initialization vector (IV) in hex format, ignored for ECB mode (use "").
[in]	szAlgModePad	string specifying the block cipher algorithm, mode and padding (see Specifying the algorithm, mode and padding for generic block cipher functions).
[in]	nOptions	option flags: Zero (0) for default options. Optionally add: PKI_IV_PREFIX to prepend the IV before the ciphertext in the output (ignored for ECB mode).

Returns

If successful, the return value is the number of characters in or required in the output; otherwise it returns a nonzero error code.

Remarks

For the "raw" VBA/C function, the user must allocate an output string buffer szOutput of the required length. Specify a zero nOutChars or an empty string for szOutput to find the required length. ANSI C users must add one to this value when allocating memory.

This is the equivalent of CIPHER_EncryptBytes with all parameters passed as hex-encoded strings instead of byte arrays. It is similar to the CIPHER_Hex function except this accepts variable-length input and adds padding if required, as well as the option to prepend the IV to the ciphertext.

Padding is added as specified to the input before encryption. The output will always be at least as long as the input, or longer if padding or a prefixed IV is to be added.

The algorithm/mode/padding must be specified using either the szAlgModePad string or nOptions parameter, but not both (see Specifying the algorithm, mode and padding for generic block cipher functions).

It is an error (BAD_PARAM_ERROR) to pass the empty string "" as input in szInputHex. The output buffer strOutput should not be the same as the input strInputHex.

Use the PKI_IV_PREFIX option to prepend the IV before the ciphertext in the output. This will add the IV before the ciphertext in the form IV||CT. This is the scheme used with block ciphers in XML encryption (see section 5.2 of [XMLENC]) where they use the phrase "The resulting cipher text is prefixed by the IV."

Encrypt or decrypt data in a file using the specified block cipher algorithm and mode.

Deprecated:

Use CIPHER_FileEncrypt() or CIPHER_FileDecrypt() instead.

Parameters

[in]	fEncrypt	direction flag: set as ENCRYPT (True) to encrypt or DECRYPT (False) to decrypt.
[in]	szFileOut	with the full path name of the output file to be created.
[in]	szFileIn	with the full path name of the input file to be processed.
[in]	lpKey	array containing the key.
[in]	lpIV	containing the initialization vector (IV), or zero (0) for ECB mode.
[in]	szAlgAndMode	containing the block cipher algorithm and mode (see Specifying the algorithm and mode for generic block cipher functions).
[in]	nOptions	option flags.

Returns

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

Remarks

The key and initialization vector are passed as bytes arrays. PKCS5 padding is used, if required. The algorithm and mode must be specified using either the szAlgAndMode or nOptions parameter (see Specifying the algorithm and mode for generic block cipher functions).

The length of key lpKey must be exactly the required key size, and the length of the IV, if required, exactly the block size. See Valid key and block sizes.

The output file szFileOut will be overwritten without warning. If there is an error, the output file will not exist. The input and output files must not be the same.

In ECB and CBC modes, a padding string will be added or assumed according to the method outlined in Section 6.3 of [CMS], which is the same as the padding method in [PKCS7] section 10.3 and [PKCS5] section 6.1.1 and [RFC1423] para 1.1.

Decrypt a file using specified block cipher algorithm, mode and padding.

Parameters

[in]	szFileOut	with the full path name of the output file to be created.
[in]	szFileIn	with the full path name of the input file to be processed.
[in]	lpKey	array containing the key.
[in]	nKeyLen	specifying the length of the key in bytes.
[in]	lpIV	containing the initialization vector (IV), if required.
[in]	nIvLen	specifying the length of the IV in bytes.
[in]	szAlgModePad	containing the block cipher algorithm, mode and padding (see Specifying the algorithm, mode and padding for generic block cipher functions).
[in]	nOptions	option flags: Zero (0) for default options. Optionally add: PKI_IV_PREFIX to expect the IV to be prepended at the start of the file (ignored for ECB mode).

Returns

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

Remarks

The algorithm/mode/padding must be specified using either the szAlgModePad string or nOptions parameter, but not both (see Specifying the algorithm, mode and padding for generic block cipher functions).

The length of key must be exactly the required key size, and the length of the IV, if required, exactly the block size. See Valid key and block sizes.

The output file szFileOut will be overwritten without warning. If there is an error, the output file will not exist. The input and output files must not be the same.

Prepended IV: If the ciphertext file was created with the IV prepended at the start of the file, then you must specify the PKI_IV_PREFIX option. In this case, the lpIV parameter is ignored and should be set to NULL. The input file is expected to be of the form IV||ciphertext, or IV||ciphertext||tag for AES-GCM.

Defaults: If padding is not specified then the default padding method depends on the cipher mode: pkcs5padding will be used for ECB and CBC mode and nopadding for all other modes. The default cipher mode is ECB. Thus "aes128" is the same as "aes128/ecb/pkcs5padding".

Padding: When decrypting you can specify NoPadding to leave any padding intact in the deciphered file. This is useful if you wish to examine an unknown padding scheme. Otherwise, when decrypting in ECB or CBC mode, you must specify the same padding scheme used when encrypting. It is an error (DECRYPT_ERROR) if the expected padding string is not found after decrypting. The padding parameter is ignored when decrypting in CTR, OFB or CFB mode.

GCM mode: [New in v20.7] Use aes*-gcm to decrypt the file using AES-GCM mode. A 16-byte tag (mac) must be appended at the end of the file. Only a 16-byte tag is supported. The IV must be exactly 12 bytes long for AES-GCM mode. Use the PKI_IV_PREFIX flag to indicate that the IV is at the start of the file.

Encrypt a file using specified block cipher algorithm, mode and padding.

The IV may be prepended to the file, if required.

Parameters

[in]	szFileOut	with the full path name of the output file to be created.
[in]	szFileIn	with the full path name of the input file to be processed.
[in]	lpKey	array containing the key.
[in]	nKeyLen	specifying the length of the key in bytes.
[in]	lpIV	containing the initialization vector (IV), if required.
[in]	nIvLen	specifying the length of the IV in bytes.
[in]	szAlgModePad	containing the block cipher algorithm, mode and padding (see Specifying the algorithm, mode and padding for generic block cipher functions).
[in]	nOptions	option flags: Zero (0) for default options. Optionally add: PKI_IV_PREFIX to prepend the IV before the ciphertext in the output file (ignored for ECB mode).

Returns

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

Remarks

The algorithm/mode/padding must be specified using either the szAlgModePad string or nOptions parameter, but not both (see Specifying the algorithm, mode and padding for generic block cipher functions).

The length of key must be exactly the required key size, and the length of the IV, if required, exactly the block size. See Valid key and block sizes.

The output file szFileOut will be overwritten without warning. If there is an error, the output file will not exist. The input and output files must not be the same.

Prepended IV: If the PKI_IV_PREFIX option flag is set in nOptions then the IV will be prepended (i.e. added) at the start of the output file. That is, the output file will be of the form IV||ciphertext. The PKI_IV_PREFIX flag is ignored in ECB mode where an IV is not needed.

Defaults: If padding is not specified then the default padding method depends on the cipher mode: pkcs5padding will be used for ECB and CBC mode and nopadding for all other modes. The default cipher mode is ECB. Thus "aes128" is the same as "aes128/ecb/pkcs5padding".

Padding: In normal circumstances you should leave the padding unspecified and use the default padding when encrypting. The only time it should be required is if you want to use an exotic padding like OneAndZeroesPadding instead of pkcs5padding with EBC or CBC mode. Note that, unlike the behaviour with CIPHER_EncryptBytes, it is an error (BAD_PARAM_ERROR) to specify NoPadding when encrypting a file with ECB or CBC mode under any circumstances. The padding option is ignored for CTR, OFB and CFB modes; that is, the default nopadding is always used for these modes regardless of what is specified (so just use the default, e.g. "aes128/ctr").

GCM mode: [New in v21.0] Use aes128-gcm, aes192-gcm or aes256-gcm to encrypt the file using AES-GCM mode. A 16-byte tag (mac) is always appended to the file. The IV must be exactly 12 bytes long for AES-GCM mode. Add the PKI_IV_PREFIX flag to prepend the IV at the start of the output file (this is in accordance with section 5.2.4 of [XMLENC]).

Encrypt or decrypt data represented as a hexadecimal string.

The key and initialization vector are represented as a hexadecimal string.

Parameters

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

Returns

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

Remarks

The algorithm and mode must be specified using either the szAlgAndMode or nOptions parameter (see Specifying the algorithm and mode for generic block cipher functions). All data parameters are expected to be in hexadecimal-encoded format and to be of valid lengths. Valid hexadecimal characters are [0-9A-Fa-f]. The hex-encoded key string szKey must represent a value with a length of exactly the required key size. The hex-encoded initialization vector string szIV, if required, must represent a value with a length of exactly the block size. See Valid key and block sizes.

Important: The output string szOutput must be dimensioned with at least the same number of characters as the input string before calling. The variables szOutput and szInput should be different.

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

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

Unwrap (decrypt) a content-encryption key with a key-encryption key.

Parameters

[out]	lpOutput	array of sufficient length to receive the output.
[in]	nOutBytes	specifying the maximum length of the output array.
[in]	lpData	array containing the input data (wrapped key).
[in]	nDataLen	specifying the length of the input data in bytes.
[in]	lpKek	array containing the key encryption key.
[in]	nKekLen	specifying the length of the key encryption key.
[in]	nOptions	option flags: Select the key wrap algorithm from one of the following: PKI_KWRAP_AES128 (or PKI_BC_AES128) to use AES128-Wrap PKI_KWRAP_AES192 (or PKI_BC_AES192) to use AES128-Wrap PKI_KWRAP_AES256 (or PKI_BC_AES256) to use AES128-Wrap PKI_KWRAP_3DES (or PKI_BC_3DES) to use cms3DESWrap

Returns

If successful, the return value is the number of bytes in the output; otherwise it returns a negative error code.

Remarks

This unwraps (decrypts) key material using a key encryption key (KEK) and uses either the AES Key Wrap Algorithm from [RFC3394] or the Triple-DES Key Wrap algorithm from [RFC3217]. There is no default algorithm. The algorithm must be specified in the nOptions parameter. To find the required length for the output key material, pass zero as the nOutBytes parameter. This will be 8 bytes less than the input length for AES and 16 bytes less for triple DES. No parity bit checks or changes are made for a Triple-DES key.

Wrap a content-encryption key with a key-encryption key.

Parameters

[out]	lpOutput	array of sufficient length to receive the output.
[in]	nOutBytes	specifying the maximum length of the output array.
[in]	lpData	array containing the input data (key material).
[in]	nDataLen	specifying the length of the input data in bytes.
[in]	lpKek	array containing the key encryption key.
[in]	nKekLen	specifying the length of the key encryption key.
[in]	nOptions	option flags: Select the key wrap algorithm from one of the following: PKI_KWRAP_AES128 (or PKI_BC_AES128) to use AES128-Wrap PKI_KWRAP_AES192 (or PKI_BC_AES192) to use AES128-Wrap PKI_KWRAP_AES256 (or PKI_BC_AES256) to use AES128-Wrap PKI_KWRAP_3DES (or PKI_BC_3DES) to use cms3DESWrap

Returns

If successful, the return value is the number of bytes in the output; otherwise it returns a negative error code.

Remarks

This wraps (encrypts) key material using a key encryption key (KEK) and uses either the AES Key Wrap Algorithm from [RFC3394] or the Triple-DES Key Wrap algorithm from [RFC3217]. There is no default algorithm. The algorithm must be specified in the nOptions parameter. The input data to be wrapped must be a valid length for the underlying data encapsulation mechanism; specifically, at least 16 bytes and a multiple of 8 bytes for AES, or exactly 24 bytes for Triple DES. To find the required length for the output wrapped key, pass zero as the nOutBytes parameter (Hint: an AES-wrapped key is exactly 8 bytes longer than the input; a triple-DES-wrapped key is 16 bytes longer). No parity bit checks or changes are made for a Triple-DES key.

Changed in [v20.5]: Added the explicit key wrap options PKI_KWRAP_* which are different from the old PKI_BC_* options. The old PKI_BC_* options are still accepted for backwards compatibility.

Extracts the message digest from a signed-data CMS object file and verifies the signature.

Parameters

[out]	szOutput	to receive the message digest output.
[in]	nOutChars	specifying the length of the output string.
[in]	szFileIn	with name of signed-data CMS object file or the data as a base64 or PEM string.
[in]	szCertFile	specifying an (optional) X.509 certificate file to be used to identify the signer.
[in]	nOptions	option flags: PKI_DEFAULT (0) for default options

Returns

If successful, the return value is a non-negative value indicating the message digest algorithm (CAUTION: this is not the number of characters in the output); otherwise it returns a negative error code.

Remarks

This function extracts the message digest of the signed encapsulated content. In doing so, it also verifies that the signature is valid. The object may be a "detached signature" object. If signed attributes are present, the function will extract the messageDigest attribute for RSA and DSA signature algorithms. If signed attributes are not present, the message digest is extracted directly from the signature value, but only for RSASSA-PKCS1-v1_5 signatures, as the message digest cannot be directly extracted from a DSA or RSA-PSS signature. If given, the function will use the public key from the specified X.509 certificate to validate the signature; otherwise it will use the first valid SignerInfo and certificate pair it finds in the SignedData.

The message digest, if found, is copied into szHexDigest. The maximum expected length of szHexDigest is PKI_MAX_HASH_CHARS characters. ANSI C users must add one to this value when allocating memory. The message digest is encoded in hexadecimal format using lower-case letters [a-f].

The message digest algorithm is indicated by the return code:

CAUTION: unlike other hash-related functions, this function does not return the length of the digest string; it returns the code for the digest algorithm.

Note that this does not verify that the message digest is that of the content. It does, however, verify that the message digest was indeed signed by the purported signer, but it does not check the content itself. To verify that the SignedData object is validly signed, the user must extract the content separately and verify that its message digest matches the digest extracted by this function. To do this, use the functions CMS_ReadSigDataToString() and HASH_HexFromBytes(). See the examples below.

Alternatively, use the CMS_VerifySigData() to verify the signature and message digest directly and use CMS_QuerySigData() to extract the messageDigest attribute, if present, without validation.

Creates a new CMS compressed-data file (.p7z) from an existing input file.

Parameters

[in]	szFileOut	name of output file to be created.
[in]	szFileIn	name of file containing input data.
[in]	nOptions	option flags: not used in this release. Specify zero.

Returns

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

Remarks

This creates a CMS compressed-data file (conventionally saved with a .p7z extension) using the zlibCompress algorithm. It only works in file-to-file mode. Any existing file with the same name as the parameter szFileOut will be overwritten without warning. Note that it may not produce an exact identical output to that of another program on the same input due to differences in ZLIB buffers and window sizes.

Creates a "detached signature" CMS signed-data object from a message digest of the content.

Parameters

[in]	szFileOut	with name of output file to be created.
[in]	szHexDigest	containing the digest of the content in hexadecimal format.
[in]	szCertList	containing the filename of the signer's certificate and (optionally) a list of other certificates to be included in the output, separated by semi-colons (;)
[in]	szPrivateKey	containing the private key data for the signer.
[in]	nOptions	option flags: Select one of: PKI_HASH_SHA1 (0) to use the SHA-1 algorithm (default) PKI_HASH_SHA224 to use the SHA-224 algorithm PKI_HASH_SHA256 to use the SHA-256 algorithm PKI_HASH_SHA384 to use the SHA-384 algorithm PKI_HASH_SHA512 to use the SHA-512 algorithm and optionally add PKI_CMS_EXCLUDE_CERTS to exclude signer's certificate PKI_CMS_INCLUDE_ATTRS to add signed attributes (default = no signed attributes) including content-type and message-digest plus any more added below. PKI_CMS_ADD_SIGNTIME to add SigningTime to the signed attributes (requires PKI_CMS_INCLUDE_ATTRS) PKI_CMS_ADD_SMIMECAP to add sMIMECapabilities to the signed attributes (requires PKI_CMS_INCLUDE_ATTRS) PKI_CMS_ADD_SIGNINGCERT to add ESS Signing Certificate attribute to the signed attributes (requires PKI_CMS_INCLUDE_ATTRS) PKI_CMS_FORMAT_BASE64 to format the output with base64 encoding (default output is binary)

Returns

If successful, the return value is zero; otherwise it returns a nonzero error code. Further error information may be available by calling PKI_LastError().

Remarks

RSASSA-PKCS1V1_5 only. See CMS_MakeSigData() for more details. The PKI_CMS_EXCLUDE_DATA option is obviously ignored.

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

Parameters

[in]	szFileOut	name of output file to be created.
[in]	szFileIn	name of file containing input data.
[in]	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.

Parameters

[in]

szKeyString

(formerly szSeed) Use to pass optional additional user key material (ukm) for KDF where KeyAgreement (kari) type or RSA-KEM 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 or use the format "#x<hex-digits>" to pass a string of arbitrary octet values. Required for pwri and kekri types.

Examples: "abc" will pass the 3 bytes (0x61, 0x62, 0x63); "#xdeadbeef01" will pass the 5 bytes (0xde, 0xad, 0xbe, 0xef, 0x01).

Parameters

[in]	nCount	(formerly nSeedLen) Optional iteration count for KDF in pwri type (default=4096) or tag length for AuthEnvelopedData (in range 12-16, default=16). Otherwise ignored.
[in]	nOptions	option flags: Set as zero (0) to use the defaults rsaEncryption for key transport or ECDH with ANSI-X9.63-KDF using SHA-1 with cms3DESwrap for key agreement; and aes128-CBC for content encryption, and output in binary format. NOTE: some default algorithms [changed in v23.0]

To set the content encryption algorithm (default is aes128-CBC), add one of the following:
PKI_BC_AES128 to use aes128-CBC for content encryption (default as of [v23.0])
PKI_BC_AES192 to use aes192-CBC for content encryption
PKI_BC_AES256 to use aes256-CBC for content encryption
PKI_BC_3DES to use Triple-DES des-EDE3-CBC for content encryption [legacy]
PKI_AEAD_AES_128_GCM to use aes128-GCM for content encryption and authentication
PKI_AEAD_AES_192_GCM to use aes192-GCM for content encryption and authentication
PKI_AEAD_AES_256_GCM to use aes256-GCM for content encryption and authentication
PKI_AEAD_CHACHA20_POLY1305 to use AEAD_CHACHA20_POLY1305 for content encryption and authentication

To set the key transport scheme or key encapsulation mechanism (KEM) for RSA, use one of
PKI_KT_RSAES_PKCS (0) to encrypt the key using the RSAES-PKCS1-v1_5 encryption scheme rsaEncryption (default)
PKI_KT_RSAES_OAEP to encrypt the key using the RSAES-OAEP encryption scheme (see RSA signature and encryption schemes).
PKI_KEM_RSA [New in v23.0] to encrypt the key using the RSA Key Encapsulation Mechanism (RSA-KEM) algorithm (see RSA-KEM).

To select a hash function where applicable, add one of:
PKI_HASH_SHA1 to use SHA-1 (default - CAUTION)
PKI_HASH_SHA224 to use SHA-224
PKI_HASH_SHA256 to use SHA-256 [minimum recommended]
PKI_HASH_SHA384 to use SHA-384
PKI_HASH_SHA512 to use SHA-512

If you have selected PKI_KT_RSAES_OAEP then, optionally, add
PKI_MGF_MGF1SHA1 to force the MGF hash function to be SHA-1 (default = same as encoding hash function set above)

To set the key derivation function (KDF) (where applicable), add one of:
PKI_KDF_X963 to use the ANSI-X9.63-KDF key derivation function (default for ECDH).
PKI_KDF_HKDF to use the HMAC-based Key Derivation Function (HKDF) from [RFC5869]
PKI_KDF_KDF2 to use KDF2 from ANSI-X9.44 [X9-44]
PKI_KDF_KDF3 to use KDF3 from ANSI-X9.44 (default for RSA-KEM)

and add the key wrap algorithm for the ECDH key agreement scheme or the kekri key encryption algorithm or RSA-KEM. Default (0) is to match the key agreement algorithm to the content encryption algorithm:
PKI_KWRAP_3DES to use cms3DESwrap [legacy - only valid if Triple DES used for the content encryption algorithm].
PKI_KWRAP_AES128 to use aes128-wrap
PKI_KWRAP_AES192 to use aes192-wrap
PKI_KWRAP_AES256 to use aes256-wrap

Optionally, add any of the bitflags:
PKI_CMS_FORMAT_BASE64 to encode the output with base64 encoding (default output is binary)
PKI_CMS_ALT_ALGID to use specialist alternative encryption algorithm identifier (see Remarks)
PKI_CMS_BIGFILE to speed up the processing of large files (binary file to binary file only)
PKI_CMS_USE_SKI to use subjectKeyIdentifier (SKI) instead of issuerAndSerialNumber for RecipientInfo [New in v23.0].

Returns

If successful, the return value is the number of successful recipients; otherwise it returns a negative error code.

Remarks

The output is a file containing a CMS EnvelopedData or AuthEnvelopedData object which can be sent as part of an S/MIME message or used directly as a binary .p7m file. The supported objects are those described in CMS Content Types. RecipientInfo types can be KeyTransRecipientInfo (ktri), KeyAgreeRecipientInfo (kari), KEKRecipientInfo (kekri) and PasswordRecipientinfo (pwri). If the content encryption algorithm is an authenticated encryption algorithm (AES*-GCM), then the output will be an Authenticated-Enveloped-Data object (AuthEnvelopedData) as specified in [RFC5083] and [RFC5084].

TL;DR. The RecipientInfo type will be set according to the type of public key in the X.509 certificates. If the certificate has an RSA key, then a key-transport RecipientInfo (ktri) will be created (default PKCS#1v1.5 or RSA-OAEP if flag set). If the certificate contains a supported ECC public key, then a key-agreement type (kari) will be used (default ANSI-X9.63-KDF and keywrap to match the content encryption algorithm, HKDF if flag set). You can pass a list of mixed certificates and the appropriate RecipientInfo type will be chosen for each. There are special cases for KEK and password recipientInfo types - see below.

ktri and kari types

By default, the RecipientInfo type is set automatically depending on the public key found in each certificate in szCertList, one for each certificate. If the public key is RSA (rsaEncryption) then the key transport technique (ktri) will be used to create that particular recipientInfo. If the public key is a supported ECC key, then the standard ECDH ephemeral-static key agreement technique (kari) will be used as per [RFC5753] and [RFC8418].

No checks are made on the validity period of the recipients' X.509 certificates or their key usage attributes. A PKCS#7 certificate chain file may be specified as an argument for szCertList. In which case, all certificates in the chain file will be used as recipients.

It is an error if any specified certificate file in szCertList is missing or corrupted. Call PKI_LastError() to find more details of the errors that occurred.

kekri and pwri types

[New in v20.6] RecipientInfo types KEKRecipientInfo (kekri) and PasswordRecipientinfo (pwri) are supported for a single recipient only. For these types no certificates are required and the szCertList argument must include "type=@kekri" or "type=@pwri", respectively, all characters lower case. In addition, for a kekri type, this argument should be of the form "type=@kekri,keyid=<string>" (Note separated by a comma ',') where the value for the keyid attribute is used to set the keyIdentifier field in the KEKIdentifier. This can be a simple ASCII string or can use the format "#x<hex-digits>" to pass a string of arbitrary octet values. If omitted, the default keyIdentifier is "keyid". Optionally add a date field in the KEKIdentifier by adding a date=<iso-date-string>, e.g. "type=@kekri,keyid=ourkeyid,date=2022-07-31T12:01".

The szKeyString argument must include either the key encryption key (KEK) for kekri or the password for pwri. This parameter is expected to be an ASCII string. A binary KEK may be passed by using the format "#x<hex-digits>" to pass a string of arbitrary octet values.

Examples

nRet = CMS_MakeEnvData("xscipher_kekri.p7m", "plain.txt", "type=@kekri,keyid=oursharedkey", 
    "#x0123456789ABCDEFF0E1D2C3B4A59687", 0, PKI_BC_AES192 Or PKI_KWRAP_AES128);

Creates an EnvelopedData file with a single recipientInfo of type KEKRecipientInfo (kekri) with a keyid of "oursharedkey" using the 128-bit KEK (0x)0123456789ABCDEFF0E1D2C3B4A59687 wrapped with aes128-wrap. The content is encrypted with AES-192 using a random content encryption key.

nRet = CMS_MakeEnvData("xscipher_pwri.p7m", "plain.txt", "type=@pwri", 
    "This is my password", 6666, PKI_BC_AES256);

Creates an EnvelopedData file with a single recipientInfo of type PasswordRecipientinfo (pwri) using the password "This is my password". The iteration count for the KDF is 6666 (default=4096). The content is encrypted with AES-256 using a random content encryption key.

Other options

Use the PKI_CMS_BIGFILE option flag to handle large files more efficiently. This results in improvements of speed typically of 30% and enables, in theory, unlimited sizes of enveloped files (subject, of course, to your level of boredom in waiting for the output). Binary output only. Not available for authenticated encryption or kekri or pwri recipientInfo types.

Specialist Option: If the PKI_CMS_ALT_ALGID option flag is present, an alternative Content Encryption Algorithm Identifier will be used as follows:

This alternative TeleTrusT algorithm identifier was added for compatibility with certain (superseded?) German Health profiles.

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

Parameters

[in]	szFileOut	name of output file to be created.
[in]	lpInput	byte array containing the input data.
[in]	nInputLen	length in bytes of input data.
[in]	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.

Parameters

[in]

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 or use the format "#x<hex-digits>" to pass a string of arbitrary octet values. Required for pwri and kekri types.

Examples: "abc" will pass the 3 bytes (0x61, 0x62, 0x63); "#xdeadbeef01" will pass the 5 bytes (0xde, 0xad, 0xbe, 0xef, 0x01).

Parameters

[in]	nCount	(formerly nSeedLen) Optional iteration count for KDF in pwri type (default=4096) or tag length for AuthEnvelopedData (in range 12-16, default=16). Otherwise ignored.
[in]	nSeedLen	formerly used for length of the seed string. No longer used. [IGNORED!]
[in]	nOptions	option flags: see the options in CMS_MakeEnvData.

Returns

If successful, the return value is the number of successful recipients; otherwise it returns a negative error code.

Remarks

This function is the same as CMS_MakeEnvData except the input data is in a byte array instead of a file.

See the remarks for CMS_MakeEnvData() above.

Use this function if the plaintext contains non-ASCII characters such as UTF-8 encoded.

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

Parameters

[in]	szFileOut	name of output file to be created.
[in]	szDataIn	string containing input data.
[in]	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.

Parameters

[in]

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 or use the format "#x<hex-digits>" to pass a string of arbitrary octet values. Required for pwri and kekri types.

Examples: "abc" will pass the 3 bytes (0x61, 0x62, 0x63); "#xdeadbeef01" will pass the 5 bytes (0xde, 0xad, 0xbe, 0xef, 0x01).

Parameters

[in]	nCount	(formerly nSeedLen) Optional iteration count for KDF in pwri type (default=4096) or tag length for AuthEnvelopedData (in range 12-16, default=16). Otherwise ignored.
[in]	nOptions	option flags: see the options in CMS_MakeEnvData.

Returns

If successful, the return value is the number of successful recipients; otherwise it returns a negative error code.

Remarks

This function is the same as CMS_MakeEnvData except the input data is in an ASCII string instead of a file.

See the remarks for CMS_MakeEnvData() above. Use this function only when the plaintext is only plain ASCII text, otherwise use CMS_MakeEnvDataFromBytes.

Creates a CMS object of type SignedData from an input data file.

Parameters

[in]	szFileOut	name of output file to be created.
[in]	szFileIn	name of file containing message data to be signed.
[in]	szCertList	filename of the signer's certificate 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.
[in]	szPrivateKey	private key data for the sender in "internal" string format.
[in]	nOptions	Option flags. Select one of: PKI_SIG_RSA_SHA1 (0) to use RSASSA-PKCS-v1_5 with SHA-1 (sha1WithRSAEncryption) (default - CAUTION) PKI_SIG_RSA_SHA224 to use RSASSA-PKCS-v1_5 with SHA-224 (sha224WithRSAEncryption) PKI_SIG_RSA_SHA256 to use RSASSA-PKCS-v1_5 with SHA-256 (sha256WithRSAEncryption) [minimum recommended] PKI_SIG_RSA_SHA384 to use RSASSA-PKCS-v1_5 with SHA-384 (sha384WithRSAEncryption) PKI_SIG_RSA_SHA512 to use RSASSA-PKCS-v1_5 with SHA-512 (sha512WithRSAEncryption) PKI_SIG_RSA_MD5 to use RSASSA-PKCS-v1_5 with MD5 (md5WithRSAEncryption) [legacy, not recommended for new implementations] PKI_SIG_RSA_PSS_SHA1 to use RSASSA-PSS with SHA-1 PKI_SIG_RSA_PSS_SHA224 to use RSASSA-PSS with SHA-224 PKI_SIG_RSA_PSS_SHA256 to use RSASSA-PSS with SHA-256 PKI_SIG_RSA_PSS_SHA384 to use RSASSA-PSS with SHA-384 PKI_SIG_RSA_PSS_SHA512 to use RSASSA-PSS with SHA-512 PKI_SIG_ECDSA_SHA1 to use ecdsaWithSHA1 PKI_SIG_ECDSA_SHA224 to use ecdsaWithSHA224 PKI_SIG_ECDSA_SHA256 to use ecdsaWithSHA256 PKI_SIG_ECDSA_SHA384 to use ecdsaWithSHA384 PKI_SIG_ECDSA_SHA512 to use ecdsaWithSHA512 PKI_SIG_ED25519 to use Ed25519 [New in v20.0] PKI_SIG_ED448 to use Ed448 [New in v22.0] And optionally add any combination of the following flags: PKI_CMS_EXCLUDE_CERTS to exclude signer's certificate PKI_CMS_EXCLUDE_DATA to exclude the eContent data PKI_CMS_CERTS_ONLY to create a "certs-only" PKCS#7 certficate chain PKI_CMS_USE_SKI to use subjectKeyIdentifier (SKI) instead of issuerAndSerialNumber for SignerIdentifier [New in v23.0]. PKI_CMS_INCLUDE_ATTRS to add signed attributes (default = no signed attributes) including content-type and message-digest plus any more added below. PKI_CMS_FORMAT_BASE64 to format the output with base64 encoding (default output is binary) PKI_CMS_NO_OUTER to create a "naked" SignedData object with no outerContentInfo as permitted by PKCS#7 v1.6 (specialist option) PKI_CMS_ALT_ALGID to use an alternative signature algorithm identifier (see Remarks) PKI_CMS_BIGFILE to speed up the processing of large files (see Remarks) PKI_PSS_SALTLEN_ZERO to set the salt length to be zero (RSASSA-PSS only, default = same length as the output of the hash function) PKI_MGF_MGF1SHA1 to force the MGF hash function to be SHA-1 (RSASSA-PSS only, default = same as signature hash function) PKI_CMS_PSEUDOSIG to create a create a "pseudo" SignedData object with a dummy placeholder signature (see Remarks) PKI_CMS_ADD_SIGNER to add a new signer to an existing SignedData object [New in v23.0] (see Remarks) If the PKI_CMS_INCLUDE_ATTRS option flag is included, optionally add any of the following: PKI_CMS_ADD_SIGNTIME to add SigningTime to the signed attributes (requires PKI_CMS_INCLUDE_ATTRS) PKI_CMS_ADD_SMIMECAP to add sMIMECapabilities to the signed attributes (requires PKI_CMS_INCLUDE_ATTRS) PKI_CMS_ADD_SIGNINGCERT to add an ESS Signing Certificate Attribute to the signed attributes (requires PKI_CMS_INCLUDE_ATTRS) [New in v12.4] PKI_CMS_ADD_ALGPROTECT to add an Algorithm Identifier Protection Attribute to the signed attributes (requires PKI_CMS_INCLUDE_ATTRS) [New in v12.4]

Returns

If successful, the return value is zero; otherwise it returns a nonzero error code. Further error information may be available by calling PKI_LastError().

Remarks

A SignedData CMS object with a single SignerInfo is created with the message data included by default in the eContent.

The signer's certificate must be included in the certificate list. All certificates in the list will be included in the output by default. Signed attributes are not included by default but can be added by using the PKI_CMS_INCLUDE_ATTRS option flag (see below). Unsigned attributes and attribute certificates are not supported. The default signature algorithm is RSASSA-PKCS-v1_5 with SHA-1 (SHA-1 caution!). The message digest algorithm always matches the digest algorithm used in the signature.

The encapContentInfo eContentType is always id-data: other eContentTypes are not possible. Only one SignerInfo can be included at one time, but [New in v23.0] additional SignerInfos can be added by calling this function second time passing an existing SignedData object as input and setting the PKI_CMS_ADD_SIGNER (see below). [New in v23.0] The signer's public key can be referenced using either issuerAndSerialNumber (default) or subjectKeyIdentifier (use the PKI_CMS_USE_SKI option). If subjectKeyIdentifier is used then the CMSversion will be 3 and the relevant SignerInfo version will also be 3. Otherwise the CMSVersion will be 1 and the SignerInfo structure also version 1.

It is an error (NO_MATCH_ERROR) if the private key does not match any certificate in the certificate list.

[New in v12.2] A PKCS#7 certificate chain file (.p7c/.p7b) may be specified as an argument for szCertList. The signer's certificate can now exist anywhere in the certificate list (previously it had to be the first).

PKI_CMS_CERTS_ONLY: To create a PKCS#7 certificate chain (a degenerate "certs-only" signed data object), include the option flag PKI_CMS_CERTS_ONLY. The szCertList can contain references to any existing certificate files in any order, separated by semi-colons. The szFileIn and szPrivateKey parameters are ignored and can be left empty. See the second example below.

PKI_CMS_INCLUDE_ATTRS: Signed attributes are not included by default. To add signed attributes use the PKI_CMS_INCLUDE_ATTRS option flag. This will add the content-type and message-digest attributes plus any other attributes specified using a PKI_CMS_ADD_* option.

PKI_CMS_ADD_SIGNINGCERT: [New in v12.4] Include the PKI_CMS_ADD_SIGNINGCERT option to add an ESS Signing Certificate Attribute to the signed attributes. This is required for B-level compliance with CAdES-BES [CADES] and with ESS [RFC2634] and [RFC5035].

PKI_CMS_ADD_ALGPROTECT: [New in v12.4] Include the PKI_CMS_ADD_ALGPROTECT option to add an Algorithm Protection Attribute to the signed attributes. This is in accordance with [RFC6211]. If a CMS validator supports this attribute, then additional checks can be made against algorithm substitution attacks.

PKI_CMS_BIGFILE: Include the PKI_CMS_BIGFILE option to cope more efficiently with large files. This only works in binary-file-to-binary-file mode, and only for RSA signatures, but makes a significant difference in processing times. The option flags PKI_CMS_EXCLUDE_DATA, PKI_CMS_CERTS_ONLY, PKI_CMS_FORMAT_BASE64, and PKI_CMS_NO_OUTER are not permitted with this option.

PKI_CMS_ADD_SIGNER: [New in v23.0] To sign an existing SignedData object with another signature, use the PKI_CMS_ADD_SIGNER option and pass the existing SignedData object as the input data file. Pass the signer's certificate in szCertList (plus any additional certificates if required) and the signer's private key string in szPrivateKey.

PKI_PSS_SALTLEN_ZERO: [New in v12.0] Include the PKI_PSS_SALTLEN_ZERO with an RSA-PSS scheme to set the salt length parameter to be zero. This results in a deterministic signature value. The default salt length is otherwise always hLen, the length of the output of the hash function. There are no other salt length options available for this function. See RSA signature and encryption schemes.

PKI_CMS_ALT_ALGID: If the PKI_CMS_ALT_ALGID option flag is present, an alternative Signature Algorithm Identifier will be used as follows (RSAES-PKCS-v1_5 only):

The default is to use the rsaEncryption identifier specified in Section 3.2 of [CMSALG].

PKI_CMS_PSEUDOSIG: [New in v20.2] Include the PKI_CMS_PSEUDOSIG option to create a create a "pseudo" SignedData object. The idea here is that we create an intermediate file which has the same structure as a CMS SignedData object except the signature is a dummy placeholder. We use the term "pseudo" file here to describe this intermediate file.

This pseudo file has the same digest value as the final signed object (as the digest is not calculated over the final signature). We send this digest value to a signing authority (say, Aruba), they sign it, and send back the actual signature value. This can be substituted in the intermediate pseudo file to produce the final SignedData object (.p7m file) using CMS_MakeSigDataFromSigValue with the PKI_CMS_PSEUDOSIG option. RSASSA-PKCS1V1_5 only.

Specialist Option: If the PKI_CMS_NO_OUTER option flag is present, the output will be a "naked" SignedData object without an outerContentInfo. This is not permitted by the CMS standard [CMS] but is allowed by PKCS#7 version 1.6 [PKCS7-EXT]. Some profiles (e.g. Royal Thai Customs) require this.

Create a CMS object of type SignedData from an array of bytes.

Parameters

[in]	szFileOut	name of output file to be created.
[in]	lpInput	byte array containing input data to be signed.
[in]	nInputLen	length in bytes of input data.
[in]	szCertList	filename of the signer's certificate 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.
[in]	szPrivateKey	private key data for the sender in "internal" string format.
[in]	nOptions	Option flags. Select one of: PKI_SIG_RSA_SHA1 (0) to use RSASSA-PKCS-v1_5 with SHA-1 (sha1WithRSAEncryption) (default - CAUTION) PKI_SIG_RSA_SHA224 to use RSASSA-PKCS-v1_5 with SHA-224 (sha224WithRSAEncryption) PKI_SIG_RSA_SHA256 to use RSASSA-PKCS-v1_5 with SHA-256 (sha256WithRSAEncryption) [minimum recommended] PKI_SIG_RSA_SHA384 to use RSASSA-PKCS-v1_5 with SHA-384 (sha384WithRSAEncryption) PKI_SIG_RSA_SHA512 to use RSASSA-PKCS-v1_5 with SHA-512 (sha512WithRSAEncryption) PKI_SIG_RSA_MD5 to use RSASSA-PKCS-v1_5 with MD5 (md5WithRSAEncryption) [legacy, not recommended for new implementations] PKI_SIG_RSA_PSS_SHA1 to use RSASSA-PSS with SHA-1 PKI_SIG_RSA_PSS_SHA224 to use RSASSA-PSS with SHA-224 PKI_SIG_RSA_PSS_SHA256 to use RSASSA-PSS with SHA-256 PKI_SIG_RSA_PSS_SHA384 to use RSASSA-PSS with SHA-384 PKI_SIG_RSA_PSS_SHA512 to use RSASSA-PSS with SHA-512 PKI_SIG_ECDSA_SHA1 to use ecdsaWithSHA1 PKI_SIG_ECDSA_SHA224 to use ecdsaWithSHA224 PKI_SIG_ECDSA_SHA256 to use ecdsaWithSHA256 PKI_SIG_ECDSA_SHA384 to use ecdsaWithSHA384 PKI_SIG_ECDSA_SHA512 to use ecdsaWithSHA512 PKI_SIG_ED25519 to use Ed25519 [New in v20.0] PKI_SIG_ED2448 to use Ed448 [New in v22.0] and optionally add any of the following flags: PKI_CMS_EXCLUDE_CERTS to exclude signer's certificate PKI_CMS_EXCLUDE_DATA to exclude the eContent data PKI_CMS_CERTS_ONLY to create a "certs-only" PKCS#7 certficate chain PKI_CMS_INCLUDE_ATTRS to add signed attributes (default = no signed attributes) including content-type and message-digest plus any more added below. PKI_CMS_FORMAT_BASE64 to format the output with base64 encoding (default output is binary) PKI_CMS_NO_OUTER to create a "naked" SignedData object with no outerContentInfo as permitted by PKCS#7 v1.6 (specialist option) PKI_CMS_ALT_ALGID to use an alternative signature algorithm identifier (see Remarks) PKI_CMS_BIGFILE to speed up the processing of large files (see Remarks) PKI_PSS_SALTLEN_ZERO to set the salt length to be zero (RSASSA-PSS only, default = same length as the output of the hash function) PKI_MGF_MGF1SHA1 to force the MGF hash function to be SHA-1 (RSASSA-PSS only, default = same as signature hash function) If the PKI_CMS_INCLUDE_ATTRS option flag is included, optionally add any of the following: PKI_CMS_ADD_SIGNTIME to add SigningTime to the signed attributes (requires PKI_CMS_INCLUDE_ATTRS) PKI_CMS_ADD_SMIMECAP to add sMIMECapabilities to the signed attributes (requires PKI_CMS_INCLUDE_ATTRS) PKI_CMS_ADD_SIGNINGCERT to add an ESS Signing Certificate Attribute to the signed attributes (requires PKI_CMS_INCLUDE_ATTRS) [New in v12.4] PKI_CMS_ADD_ALGPROTECT to add an Algorithm Identifier Protection Attribute to the signed attributes (requires PKI_CMS_INCLUDE_ATTRS) [New in v12.4]

Returns

If successful, the return value is zero; otherwise it returns a nonzero error code. Further error information may be available by calling PKI_LastError().

Remarks

This function is identical to CMS_MakeSigData() except the input is passed as a byte array instead of in a file.

See the remarks for CMS_MakeSigData above.

Use this function if the content contains non-ASCII characters such as UTF-8 encoded.

Creates a CMS object of type SignedData using a pre-computed signature value.

Parameters

[in]	szFileOut	name of output file to be created.
[in]	lpSigValue	byte array containing the pre-computed signature.
[in]	nSigLen	length of the signature value in bytes.
[in]	lpData	byte array containing the data that has been signed (required).
[in]	nDataLen	length of the data in bytes.
[in]	szCertList	filename of the signer's certificate 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.
[in]	nOptions	Option flags. Select one of: PKI_HASH_SHA1 (0) to use the SHA-1 algorithm (default) PKI_HASH_SHA224 to use the SHA-224 algorithm PKI_HASH_SHA256 to use the SHA-256 algorithm PKI_HASH_SHA384 to use the SHA-384 algorithm PKI_HASH_SHA512 to use the SHA-512 algorithm PKI_HASH_MD5 to use the MD5 algorithm and optionally add PKI_CMS_EXCLUDE_CERTS to exclude signer's certificate PKI_CMS_FORMAT_BASE64 to format the output with base64 encoding (default output is binary) PKI_CMS_NO_OUTER to create a "naked" SignedData object with no outerContentInfo as permitted by PKCS#7 v1.6 PKI_CMS_ALT_ALGID to use alternative signature algorithm identifiers (see Remarks for CMS_MakeSigData()) PKI_CMS_PSEUDOSIG to create a SignedData object from a "pseudo" object (see Remarks).

Returns

If successful, the return value is zero; otherwise it returns a nonzero error code. Further error information may be available by calling PKI_LastError().

Remarks

This is a specialized option for a specific case where the RSA v1.5 signature value over the content has been computed separately (say, using a smart card) and the user requires this to be used inside a CMS signed-data object.

A SignedData CMS object with a single SignerInfo is created with the message data included in the eContent. Signed attributes cannot be added. Unsigned attributes and attribute certificates are not supported. The content must be included in the input using the lpData and nDataLen parameters. Only RSASSA-PKCS-v1_5 signature schemes are supported by this function. Only one message digest algorithm is used in each object. SHA-1 is used by default. Alternative hash algorithms can be used instead by adding the appropriate PKI_HASH_ option flag (this must match the digest algorithm used to compute the signature). The content and the signature are checked before the output file is created. If the signature data is not valid, or the data is not the data signed, or the certificate specified is not that of the signer, then it will return SIGNATURE_ERROR (-22).

[New in v12.2] A PKCS#7 certificate chain file (.p7c/.p7b) may be specified as an argument for szCertList. The signer's certificate can now exist anywhere in the certificate list (previously it had to be the first).

[New in v20.2] Use the PKI_CMS_PSEUDOSIG option to create a SignedData object from a "pseudo" object, created using CMS_MakeSigData with the PKI_CMS_PSEUDOSIG option.

Create a CMS object of type SignedData from an input string.

Parameters

[in]	szFileOut	name of output file to be created.
[in]	szDataIn	string containing message data to be signed.
[in]	szCertList	filename of the signer's certificate 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.
[in]	szPrivateKey	private key data for the sender in "internal" string format.
[in]	nOptions	Option flags. Select one of: PKI_SIG_RSA_SHA1 (0) to use RSASSA-PKCS-v1_5 with SHA-1 (sha1WithRSAEncryption) (default - CAUTION) PKI_SIG_RSA_SHA224 to use RSASSA-PKCS-v1_5 with SHA-224 (sha224WithRSAEncryption) PKI_SIG_RSA_SHA256 to use RSASSA-PKCS-v1_5 with SHA-256 (sha256WithRSAEncryption) [minimum recommended] PKI_SIG_RSA_SHA384 to use RSASSA-PKCS-v1_5 with SHA-384 (sha384WithRSAEncryption) PKI_SIG_RSA_SHA512 to use RSASSA-PKCS-v1_5 with SHA-512 (sha512WithRSAEncryption) PKI_SIG_RSA_MD5 to use RSASSA-PKCS-v1_5 with MD5 (md5WithRSAEncryption) [legacy, not recommended for new implementations] PKI_SIG_RSA_PSS_SHA1 to use RSASSA-PSS with SHA-1 PKI_SIG_RSA_PSS_SHA224 to use RSASSA-PSS with SHA-224 PKI_SIG_RSA_PSS_SHA256 to use RSASSA-PSS with SHA-256 PKI_SIG_RSA_PSS_SHA384 to use RSASSA-PSS with SHA-384 PKI_SIG_RSA_PSS_SHA512 to use RSASSA-PSS with SHA-512 PKI_SIG_ECDSA_SHA1 to use ecdsaWithSHA1 PKI_SIG_ECDSA_SHA224 to use ecdsaWithSHA224 PKI_SIG_ECDSA_SHA256 to use ecdsaWithSHA256 PKI_SIG_ECDSA_SHA384 to use ecdsaWithSHA384 PKI_SIG_ECDSA_SHA512 to use ecdsaWithSHA512 PKI_SIG_ED25519 to use Ed25519 [New in v20.0] PKI_SIG_ED448 to use Ed448 [New in v22.0] and optionally add any of the following flags: PKI_CMS_EXCLUDE_CERTS to exclude signer's certificate PKI_CMS_EXCLUDE_DATA to exclude the eContent data PKI_CMS_CERTS_ONLY to create a "certs-only" PKCS#7 certficate chain PKI_CMS_INCLUDE_ATTRS to add signed attributes (default = no signed attributes) including content-type and message-digest plus any more added below. PKI_CMS_FORMAT_BASE64 to format the output with base64 encoding (default output is binary) PKI_CMS_NO_OUTER to create a "naked" SignedData object with no outerContentInfo as permitted by PKCS#7 v1.6 (specialist option) PKI_CMS_ALT_ALGID to use an alternative signature algorithm identifier (see Remarks) PKI_PSS_SALTLEN_ZERO to set the salt length to be zero (RSASSA-PSS only, default = same length as the output of the hash function) PKI_MGF_MGF1SHA1 to force the MGF hash function to be SHA-1 (RSASSA-PSS only, default = same as signature hash function) If the PKI_CMS_INCLUDE_ATTRS option flag is included, optionally add any of the following: PKI_CMS_ADD_SIGNTIME to add SigningTime to the signed attributes (requires PKI_CMS_INCLUDE_ATTRS) PKI_CMS_ADD_SMIMECAP to add sMIMECapabilities to the signed attributes (requires PKI_CMS_INCLUDE_ATTRS) PKI_CMS_ADD_SIGNINGCERT to add an ESS Signing Certificate Attribute to the signed attributes (requires PKI_CMS_INCLUDE_ATTRS) [New in v12.4] PKI_CMS_ADD_ALGPROTECT to add an Algorithm Identifier Protection Attribute to the signed attributes (requires PKI_CMS_INCLUDE_ATTRS) [New in v12.4]

Returns

If successful, the return value is zero; otherwise it returns a nonzero error code. Further error information may be available by calling PKI_LastError().

Remarks

This function is identical to CMS_MakeSigData() except the input is passed as a string instead of in a file.

Zero-terminated ANSI data is expected in szDataIn.

To sign a messsage that contains binary or Unicode UTF-8 or UTF-16 data, use CMS_MakeSigDataFromBytes.

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

Parameters

[out]	szOutput	to receive the output.
[in]	nOutChars	specifying the length of the output string.
[in]	szFileIn	with name of signed-data CMS object file or the data as a base64 or PEM string.
[in]	szQuery	specifying the query (see Remarks below).
[in]	nOptions	option flags: PKI_DEFAULT (0) for default options PKI_QUERY_GETTYPE to return the type of data returned for a given query.

Returns

If successful, the return value is a positive integer indicating either the result itself (if the result is a number) or the number of characters in the output string (if the query is looking for a string). If the item queried cannot be found, the return value is zero. If there is an error (e.g. an invalid signed-data file), it returns a negative error code.

Remarks

This function queries a given EnvelopedData file for selected information. The query string is case-insensitive, so "version", "VERSION" and "VeRsIoN" are all valid.

Valid queries are (case-insensitive):

By default, the function queries the first recipientInfo in the file. To query the Nth recipientInfo append "/N" to the query string, e.g. "recipientInfoVersion/2" to find the version number of the second recipientInfo in the file. The query encryptedContent may be slow to respond if the file is large.

The "raw" VBA/C function behaves differently depending on whether the output is a string or a number. If the result data type is a number then it returns the value directly. If the result is a string, then it sets szOutput and returns the number of characters in the string. The required number of characters can be found by passing zero for nOutChars or a null string for szOutput. ANSI C users must add one to this value when allocating memory.

Note that the VBA wrapper function and the C#/VB.NET and C++ (STL) methods always return a string, which is different from the behaviour of the raw VB6/C function.

To find out the type of data returned for a given query, use the PKI_QUERY_GETTYPE option. The function will return either PKI_QUERY_NUMBER (1) or PKI_QUERY_STRING (2), or a negative "invalid query" error. For example

nRet = CMS_QueryEnvData("", 0, "", "version", PKI_QUERY_GETTYPE);

will return PKI_QUERY_NUMBER.

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

Parameters

[out]	szOutput	to receive the output.
[in]	nOutChars	specifying the length of the output string.
[in]	szFileIn	with name of signed-data CMS object file or the data as a base64 or PEM string.
[in]	szQuery	specifying the query (see Remarks below).
[in]	nOptions	option flags: PKI_DEFAULT (0) for default options PKI_QUERY_GETTYPE to return the type of data returned for a given query.

Returns

If successful, the return value is a positive integer indicating either the result itself (if the result is a number) or the number of characters in the output string (if the query is looking for a string). If the item queried cannot be found, the return value is zero. If there is an error (e.g. an invalid signed-data file), it returns a negative error code.

Remarks

This function queries a given SignedData file for selected information. Only version 1 signed-data objects are fully supported. The function will attempt to query other versions but may not succeed. Note that this function does not verify any data, including the messageDigest attribute, it just returns what it finds. The query string is case-insensitive, so "version", "Version" and "VeRsIoN" are all valid.

Valid queries are (case-insensitive):

By default, the function queries the first signerInfo in the file. To query the Nth signerInfo append "/N" to the query string, e.g. "signerInfoVersion/2" to find the version number of the second signerInfo in the file.

[New in v23.0] The query "certificate/N" will output the Nth certificate in the CertificateSet (default N = 1) encoded in base64. Note that the length of an X.509 certificate is typically several hundred bytes.

The "raw" VBA/C function behaves differently depending on whether the output is a string or a number. If the result data type is a number then it returns the value directly. If the result is a string, then it sets szOutput and returns the number of characters in the string. The required number of characters can be found by passing zero for nOutChars or a null string for szOutput. ANSI C users must add one to this value when allocating memory.

Note that the VBA wrapper function and the C#/VB.NET methods always return a string, which is different from the behaviour of the raw VB6/C function.

To find out the type of data returned for a given query, use the PKI_QUERY_GETTYPE option. The function will return either PKI_QUERY_NUMBER (1) or PKI_QUERY_STRING (2), or a negative "invalid query" error. For example

nRet = CMS_QuerySigData("", 0, "", "version", PKI_QUERY_GETTYPE);

will return PKI_QUERY_NUMBER.

Read and extract the decompressed contents of a CMS compressed-data file.

Parameters

[in]	szFileOut	name of output file to be created.
[in]	szFileIn	name of file containing input data.
[in]	nOptions	option flags: PKI_DEFAULT (0) for default options PKI_CMS_NO_INFLATE to extract the compressed data as is without inflation

Returns

If successful, the return value is the number of bytes in the output file; otherwise it returns a negative error code.

Remarks

This will read and extract the contents of a CMS compressed-data file (conventionally saved with a .p7z extension) which uses the zlibCompress algorithm. It only works in file-to-file mode. Any existing file with the same name as the parameter szFileOut will be overwritten without warning. Use the PKI_CMS_NO_INFLATE option to extract the compressed data as is without inflation.

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

Parameters

[in]	szFileOut	with name of output file to be created.
[in]	szFileIn	with name of file containing input data (binary or base64-encoded) or the data as a base64 or PEM string.
[in]	szCertFile	(optional) specifies the filename of the recipient's X.509 certificate.
[in]	szPrivateKey	recipient's private key in internal string format.
[in]	nOptions	option flags: PKI_DEFAULT (0) for default options. PKI_CMS_BIGFILE to speed up the processing of large files (binary only).

Returns

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

Remarks

If received as an attachment to an S/MIME email message, the user must first extract the CMS object from the email (Hint: use a text editor and cut out the base64 data from the message

• see Sending an enveloped-data object and work backwards).

The optional certificate szCertFile is used to identify the intended recipient in a message addressed to multiple recipients. If the intended recipient's certificate is not provided, the first valid message that can be decrypted using the given private key, if any, will be extracted.

The supported EnvelopedData and AuthEnvelopedData objects are those described in CMS Content Types.

Use the PKI_CMS_BIGFILE option to process large files more efficiently. See the example in CMS_MakeEnvData().

[Changes in v12.1] To avoid certain attacks that rely on timing differences, the encrypted content will always be decrypted. If all else is good but no valid content encryption key (CEK) can be found in the recipient data, then a random key will be used. The end result in this latter case will always be a negative DECRYPT_ERROR with no further information as to the cause. If there is something obviously wrong with the input, such as a badly-formed input file (INVALID_DATA_ERROR), or the given certificate does not have a match with any recipient (NO_MATCH_ERROR), then an appropriate error code will be returned.

Reads and decrypts CMS enveloped-data object using the recipient's private key writing the plaintext data directly into a byte array.

Parameters

[out]	lpOutput	buffer to receive output plaintext.
[in]	nOutBytes	length in bytes of the output buffer.
[in]	szFileIn	name of file containing input data (binary or base64-encoded) or the data as a base64 or PEM string.
[in]	szCertFile	(optional) filename of the recipient's X.509 certificate.
[in]	szPrivateKey	recipient's private key in internal string format.
[in]	nOptions	option flags: PKI_DEFAULT (0) for default options

Returns

If successful, the return value is the number of bytes in the decrypted plaintext; otherwise it returns a negative error code.

Remarks

See the remarks for CMS_ReadEnvData() above. Call the function with a NULL lpOutput or zero nOutBytes parameter to find out the required length of the output buffer. Alternatively, use the CMS_QueryEnvData() function with the query "sizeofEncryptedContent". This will return an upper bound on the length of the decrypted plaintext, at most 16 bytes too long. Calling CMS_ReadEnvDataToString() with a properly-sized output buffer will return the exact size of the recovered plaintext. The buffer must be large enough to receive the entire output or a SHORT_BUF_ERROR error will result.

Use this function if the output plaintext is known to contain non-ASCII characters such as UTF-8 encoded.

Reads and decrypts CMS enveloped-data object using the recipient's private key writing the plaintext data directly into a string.

Parameters

[out]	szOutput	buffer to receive output plaintext.
[in]	nOutChars	length in bytes of the output buffer.
[in]	szFileIn	name of file containing input data (binary or base64-encoded) or the data as a base64 or PEM string.
[in]	szCertFile	(optional) filename of the recipient's X.509 certificate.
[in]	szPrivateKey	recipient's private key in internal string format.
[in]	nOptions	option flags: PKI_DEFAULT (0) for default options

Returns

If successful, the return value is the number of bytes in the decrypted plaintext; otherwise it returns a negative error code.

Remarks

For the "raw" VBA/C function, the user must allocate an output string buffer szOutput of the required length. Specify a zero nOutChars or an empty string for szOutput to find the required length. ANSI C users must add one to this value when allocating memory.

See the remarks for CMS_ReadEnvData() above.

Alternatively, use the CMS_QueryEnvData() function with the query "sizeofEncryptedContent". This will return an upper bound on the length of the decrypted plaintext, at most 16 bytes too long. Calling CMS_ReadEnvDataToString() with a properly-sized output buffer will return the exact size of the recovered plaintext. The buffer must be large enough to receive the entire output or a SHORT_BUF_ERROR error will result.

Use this function only if the output plaintext is known to be plain ASCII text with no embedded NUL (zero) characters, otherwise use CMS_ReadEnvDataToBytes.

Reads the content from a CMS signed-data object file.

Parameters

[in]	szFileOut	with name of output file to be created.
[in]	szFileIn	with name of signed-data CMS object file (binary or base64-encoded) or the data as a base64 or PEM string.
[in]	nOptions	option flags: PKI_DEFAULT (0) for default options PKI_CMS_BIGFILE to speed up the processing of large files (binary input only).

Returns

If successful, the return value is a positive number indicating the number of bytes in the content; otherwise it returns a negative error code.

Remarks

This function extracts the signed data from the signed-data CMS object without making any attempt to verify it. Any existing file with the same name as the specified output will be overwritten without further warning.

This function automatically checks for and reads "naked" SignedData files as per PKCS#7 version 1.6 [PKCS7-EXT] as well as the default SignedData objects properly encapsulated in an outerContentInfo as per the S/MIME standard.

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

Parameters

[out]	lpOutput	buffer to receive the output.
[in]	nOutBytes	length of the output buffer.
[in]	szFileIn	with name of signed-data CMS object file (binary or base64-encoded) or the data as a base64 or PEM string.
[in]	nOptions	option flags: PKI_DEFAULT (0) for default options

Returns

If successful, the return value is a positive number indicating the number of bytes in the content; otherwise it returns a negative error code.

Remarks

This function extracts the signed content from the signed-data CMS object without making any attempt to verify it. Call the function with a NULL abOutput array or zero nOutBytes parameter to find out the required length of the output buffer. The buffer must be large enough to receive the entire output or a SHORT_BUF_ERROR error will result.

Use this function if the content contains non-ASCII characters such as UTF-8 encoded.

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

Parameters

[out]	szOutput	to receive the output.
[in]	nOutChars	specifying the length of the output string.
[in]	szFileIn	with name of signed-data CMS object file (binary or base64-encoded) or the data as a base64 or PEM string.
[in]	nOptions	option flags: PKI_DEFAULT (0) for default options

Returns

If successful, the return value is a positive number indicating the number of bytes in the content; otherwise it returns a negative error code.

Remarks

For the "raw" VBA/C function, the user must allocate an output string buffer szOutput of the required length. Specify a zero nOutChars or an empty string for szOutput to find the required length. ANSI C users must add one to this value when allocating memory.

This function extracts the signed data from the signed-data CMS object without making any attempt to verify it.

The buffer must be large enough to receive the entire output or a SHORT_BUF_ERROR error will result.

Use this only when the signed content is known to be plain ASCII text, otherwise use CMS_ReadSigDataToBytes.

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

Parameters

[in]	szFileIn	specifying the name of the signed-data CMS object file (binary or base64-encoded) or the data as a base64 or PEM string.
[in]	szCertFile	(optional) specifying an X.509 certificate file to be used to identify the signer. Specify an empty string "" to use the certificate(s) in the input file.
[in]	szHexDigest	(optional) specifying a message digest encoded in hexadecimal format. Use this to verify a "detached-signature" input file. Specify an empty string "" to verify the eContent data in the SignedData file.
[in]	nOptions	option flags: PKI_DEFAULT (0) for default options. PKI_CMS_BIGFILE to speed up the processing of large files (binary input only).

Returns

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

Remarks

This function verifies that the content was indeed signed by the purported signer. Note that it returns zero to indicate success, not true. If a certificate is specified in szCertFile then the public key from that certificate will be used and a matching signerInfo will be searched for in the SignedData file. Otherwise the first matching pair of certificate and signerInfo found in the SignedData file will be used.

If the signed content (eContent) is included in the SignedData object (this is the usual case), then specify an empty string ("") for szHexDigest. For a "detached-signature" file where the signed content has been passed to the user by other means, compute a separate message digest of the data and pass it to the function in the szHexDigest parameter.

This function handles SignedData objects both with and without signedAttributes.

[New in v12.4] If an ESS Signing Certificate attribute is found, then the purported signing certificate will be checked against the value of this attribute as per ESS [RFC5035] and CAdES [CADES]. It is a SIGNATURE_ERROR (22) if these do not match.

[New in v12.4] If an Algorithm Protection Attribute is found, then further verification checks will be made to prevent algorithm substitution attacks as per [RFC6211]. It is a SIGNATURE_ERROR (22) if these checks fail.

Removes non-base64 characters from a string.

Parameters

[out]	szOutput	to receive filtered characters.
[in]	szInput	to be filtered.
[in]	nStrLen	specifying the length of the input string.

Returns

If successful, the return value is the number of characters in the filtered string; otherwise it returns a negative error code.

Remarks

Specify a zero nOutChars or an empty string for szOutput to find the required length of the output string. ANSI C users must add one to this value when allocating memory.

Assumes that the output string is at least as long as the input string.

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

Parameters

[out]	szOutput	to receive encoded data.
[in]	nOutChars	specifying the maximum number of characters to be received.
[in]	lpInput	array of binary data to be encoded.
[in]	nInputLen	number of bytes to be encoded.

Returns

If successful, the return value is the number of characters in the encoded string; otherwise it returns a negative error code.

Remarks

Specify a zero nOutChars or an empty string for szOutput to find the required length of the output string. ANSI C users must add one to this value when allocating memory.

This uses the base64 encoding scheme from [RFC4648]. Pass a zero value of nOutChars to find the required maximum possible number of characters in the output string. The final result may be smaller. C/C++ programmers should add one to the returned length value when allocating memory for szOutput.

Encodes an array of bytes into a base58-encoded string.

Parameters

[out]	szOutput	to receive encoded data.
[in]	nOutChars	specifying the maximum number of characters to be received.
[in]	lpInput	array of binary data to be encoded.
[in]	nInputLen	number of bytes to be encoded.

Returns

If successful, the return value is the number of characters in the encoded string; otherwise it returns a negative error code.

Remarks

For the "raw" VBA/C function, the user must allocate an output string buffer szOutput of the required length. Specify a zero nOutChars or an empty string for szOutput to find the required length. ANSI C users must add one to this value when allocating memory.

This uses the "Bitcoin" scheme of base58 encoding where the leading character '1' is reserved for representing an entire leading zero byte [BTC-B58].

Decodes a base58-encoded string into an array of bytes.

Parameters

[out]	lpOutput	array suitably dimensioned to receive decoded output.
[in]	nOutBytes	specifying the maximum number of bytes to be received.
[in]	szInput	base58 data to be decoded.

Returns

If successful, the return value is the number of bytes in the decoded array; otherwise it returns a negative error code.

Remarks

This uses the "Bitcoin" scheme of base58 encoding where the leading character '1' is reserved for representing an entire leading zero byte [BTC-B58]. Pass a zero value for nOutBytes to find the required number of bytes in the output array.

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

Parameters

[out]	lpOutput	array suitably dimensioned to receive output..
[in]	nOutBytes	specifying the maximum number of bytes to be received.
[in]	lpInput	array containing input data.
[in]	nBytes	number of bytes in input array.
[in]	nOptions	Option flags. Select one of: PKI_CNV_UTF8_FROM_LATIN1 (1) to convert from UTF-8 encoding to Latin-1 PKI_CNV_LATIN1_FROM_UTF8 (2) to convert from Latin-1 encoding to UTF-8

Returns

If successful, the return value is a positive number indicating the number of bytes in the output array, or number of bytes required if nOutBytes is set to zero; otherwise it returns a negative error code.

Remarks

Converting UTF-8 from Latin-1 assumes the input is from the 8-bit Latin-1 character set and so will always produce output that is valid UTF-8. However, for Latin-1 from UTF-8, the input must contain a valid sequence of UTF-8-encoded bytes and this must be convertible to a single-byte character set, or an error will be returned.

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

Parameters

[out]	lpOutput	array suitably dimensioned to receive output.
[in]	nOutBytes	specifying the maximum number of bytes to be received.
[in]	szInput	base64 data to be decoded.

Returns

If successful, the return value is the number of bytes in the decoded array; otherwise it returns a negative error code.

Remarks

This uses the base64 encoding scheme from [RFC4648]. Pass a zero value for nOutBytes to find the required maximum possible number of bytes in the output array. The final array may be shorter.

Warning

[Changed in v11.1] This function now returns an error if it finds an illegal character in the input string (previously any non-base64 character was just ignored). Whitespace characters (space, TAB, LF, CR, VT, FF) are still allowed and ignored but any other non-base64 characters will cause an error.

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

Parameters

[out]	lpOutput	array suitably dimensioned to receive output.
[in]	nOutBytes	specifying the length of the byte array.
[in]	szInput	of hexadecimal data to be decoded.

Returns

If successful, the return value is the number of bytes in the decoded array; otherwise it returns a negative error code.

Remarks

Call the function with a null lpOutput array or zero nOutBytes to find the required length.

Warning

[Changed in v11.1] This function now returns an error if it finds an illegal character in the input string (previously any non-hex character was just ignored). Whitespace characters and ASCII punctuation characters are still allowed and ignored (so "DE:AD:BE:EF" is OK) but characters like those in the range [G-Zg-z] that are obviously non-hex will cause an error.

Checks if a string only contains valid UTF-8 characters.

Deprecated:

Use CNV_CheckUTF8Bytes() instead.

Parameters

[in]

szInput

to be checked.

Returns

Returns zero if the string is invalid UTF-8, or a positive number if the string is valid UTF-8.

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

Parameters

[in]	lpInput	array to be checked.
[in]	nBytes	number of bytes in input array.

Returns

Returns zero if the byte array contains invalid UTF-8, or a positive number if the byte array contains valid UTF-8, where the value of the number indicates the nature of the encoded characters (see Remarks below):

Remarks

Return values:

Returns	Value	Result
PKI_CHRS_NOT_UTF8	0	Not valid UTF-8
PKI_CHRS_ALL_ASCII	1	Valid UTF-8, all chars are 7-bit ASCII
PKI_CHRS_ANSI8	2	Valid UTF-8, contains at least one multi-byte character equivalent to 8-bit ANSI
PKI_CHRS_MULTIBYTE	3	Valid UTF-8, contains at least one multi-byte character that cannot be represented in a single-byte character set.

Overlong UTF-8 sequences and illegal surrogates are rejected as invalid. Strings that return PKI_CHRS_ANSI8 (2) can be converted to Latin-1 format using the CNV_Latin1FromUTF8Bytes() function. Strings that return PKI_CHRS_MULTIBYTE (3) cannot be converted to Latin-1, and strings that return PKI_CHRS_ALL_ASCII (1) are already OK because they only consist of 7-bit ASCII characters.

Checks if a file contains valid UTF-8 characters.

Parameters

[in]

szFileName

containing the name of the file.

Returns

Returns zero if the file contains invalid UTF-8, or a positive number if the file contains valid UTF-8, where the value of the number indicates the nature of the encoded characters: see CNV_CheckUTF8Bytes() for more details. If there is an error, like the file is missing or cannot be read, then it returns a negative error code.

Remarks

This is the same as CNV_CheckUTF8Bytes() but for a file instead of a byte array. For more details, see CNV_CheckUTF8Bytes().