Create, read and analyze Cryptographic Message Syntax (CMS) objects. More...

Public Types
enum class	CipherAlg
	Content encryption algorithm. More...

enum	ComprDataOptions : unsigned int
	Advanced options for CMS compressed-data objects [BitFlags]. More...

enum	EnvDataOptions : unsigned int
	Advanced options for CMS enveloped-data objects [BitFlags]. More...

enum class	Format
	Output format. More...

enum class	HashAlg
	Hash algorithm for RSA-OEAP or ECDH KDF or RSA-KEM. More...

enum class	KeyEncrAlg
	Key encryption algorithm for key transport scheme (ktri) More...

enum class	SigAlg
	Signature algorithm. More...

enum	SigDataOptions : unsigned int
	Advanced options for CMS signed-data objects [BitFlags]. More...

Static Public Member Functions
static std::string	GetSigDataDigest (const std::string &inputFile, const std::string &certFile="")
	Extract the message digest from a signed-data CMS object file. More...

static int	MakeComprData (const std::string &outputFile, const std::string &inputFile)
	Create a CMS compressed-data file (.p7z) from an existing input file [binary file --> binary file]. More...

static int	MakeDetachedSig (const std::string &outputFile, const std::string &hexDigest, const std::string &certList, const std::string &privateKey, SigAlg sigAlg=SigAlg::Default, SigDataOptions opts=SigDataOptions::Default_SigDataOpt, Format format=Format::Default)
	Create a "detached signature" CMS signed-data object from a message digest of the content [hexdigest --> file]. More...

static int	MakeEnvData (const std::string &outputFile, const std::string &inputFile, const std::string &certList, CipherAlg cipherAlg=CipherAlg::Default, KeyEncrAlg keyEncrAlg=KeyEncrAlg::Default, HashAlg hashAlg=HashAlg::Default, EnvDataOptions advOpts=EnvDataOptions::Default_EnvDataOpt, Format format=Format::Default, bool bigFile=false, Kdf::KdfAlg kdfAlg=Kdf::KdfAlg::X963, Kdf::KeyWrapAlg keyWrapAlg=Kdf::KeyWrapAlg::Default, const std::string &keyString="", int count=0)
	Create a CMS enveloped-data object for one or more recipients [file --> file]. More...

static int	MakeEnvData (const std::string &outputFile, const std::string &inputFile, const std::string &schemeType, const std::string &keyString, CipherAlg cipherAlg=CipherAlg::Default, Kdf::KeyWrapAlg keyWrapAlg=Kdf::KeyWrapAlg::Default, EnvDataOptions advOpts=EnvDataOptions::Default_EnvDataOpt, Format format=Format::Default, HashAlg hashAlg=HashAlg::Default, int count=0)
	Create a CMS enveloped-data object using pwri or kekri scheme [file --> file]. More...

static int	MakeEnvDataFromBytes (const std::string &outputFile, const dipki::bvec_t &data, const std::string &certList, CipherAlg cipherAlg=CipherAlg::Default, KeyEncrAlg keyEncrAlg=KeyEncrAlg::Default, HashAlg hashAlg=HashAlg::Default, EnvDataOptions advOpts=EnvDataOptions::Default_EnvDataOpt, Format format=Format::Default, Kdf::KdfAlg kdfAlg=Kdf::KdfAlg::X963, Kdf::KeyWrapAlg keyWrapAlg=Kdf::KeyWrapAlg::Default, const std::string &keyString="")
	Create a CMS enveloped-data object for one or more recipients [bytes --> file]. More...

static int	MakeEnvDataFromString (const std::string &outputFile, const std::string &inputStr, const std::string &certList, CipherAlg cipherAlg=CipherAlg::Default, KeyEncrAlg keyEncrAlg=KeyEncrAlg::Default, HashAlg hashAlg=HashAlg::Default, EnvDataOptions advOpts=EnvDataOptions::Default_EnvDataOpt, Format format=Format::Default, Kdf::KdfAlg kdfAlg=Kdf::KdfAlg::X963, Kdf::KeyWrapAlg keyWrapAlg=Kdf::KeyWrapAlg::Default, const std::string &keyString="")
	Create a CMS enveloped-data object for one or more recipients [string --> file]. More...

static int	MakeSigData (const std::string &outputFile, const std::string &inputFile, const std::string &certList, const std::string &privateKey, SigAlg sigAlg=SigAlg::Default, SigDataOptions opts=SigDataOptions::Default_SigDataOpt, Format format=Format::Default, bool bigFile=false)
	Create a CMS signed-data object from a data file [file --> file]. More...

static int	MakeSigDataFromBytes (const std::string &outputFile, const dipki::bvec_t &data, const std::string &certList, const std::string &privateKey, SigAlg sigAlg=SigAlg::Default, SigDataOptions opts=SigDataOptions::Default_SigDataOpt, Format format=Format::Default)
	Create a CMS signed-data object from data [bytes --> file]. More...

static int	MakeSigDataFromPseudo (const std::string &outputFile, const std::string &inputPseudoFile, const dipki::bvec_t &sigValue, Format format=Format::Default)
	Create a SignedData object from a "pseudo" object. More...

static int	MakeSigDataFromSigValue (const std::string &outputFile, const dipki::bvec_t &sigValue, const dipki::bvec_t &data, const std::string &certList, SigAlg sigAlg=SigAlg::Default, SigDataOptions opts=SigDataOptions::Default_SigDataOpt, Format format=Format::Default)
	Create a CMS object of type SignedData using a pre-computed signature value [bytes --> file]. More...

static int	MakeSigDataFromString (const std::string &outputFile, const std::string &inputStr, const std::string &certList, const std::string &privateKey, SigAlg sigAlg=SigAlg::Default, SigDataOptions opts=SigDataOptions::Default_SigDataOpt, Format format=Format::Default)
	Create a CMS signed-data object from a string [string --> file]. More...

static std::string	QueryEnvData (const std::string &inputFile, const std::string &query)
	Query a CMS enveloped-data object for selected information. More...

static std::string	QuerySigData (const std::string &inputFile, const std::string &query)
	Query a CMS signed-data object for selected information. More...

static int	ReadComprData (const std::string &outputFile, const std::string &inputFile, ComprDataOptions opts=ComprDataOptions::Default_ComprDataOpt)
	Read and extract the decompressed contents of a CMS compressed-data file [binary file --> binary file]. More...

static bvec_t	ReadEnvDataToBytes (const std::string &inputFile, const std::string &privateKey, const std::string &certFile="")
	Read and decrypt a CMS enveloped-data object to a byte array [file --> bytes]. More...

static int	ReadEnvDataToFile (const std::string &outputFile, const std::string &inputFile, const std::string &privateKey, const std::string &certFile="", bool bigFile=false)
	Read and decrypt a CMS enveloped-data object to a file [file --> file]. More...

static bvec_t	ReadSigDataToBytes (const std::string &inputFile)
	Read and decrypt a CMS enveloped-data object to a byte array [file --> bytes]. More...

static int	ReadSigDataToFile (const std::string &outputFile, const std::string &inputFile, bool bigFile=false)
	Read the content from a CMS signed-data object file [file --> file]. More...

static bool	VerifySigData (const std::string &inputFile, const std::string &certFile="", const std::string &hexDigest="", bool bigFile=false)
	Verify the signature and content of a signed-data CMS object file. More...

Detailed Description

Create, read and analyze Cryptographic Message Syntax (CMS) objects.

Supported CMS objects are signed-data, enveloped-data, and compressed-data.

Member Enumeration Documentation

◆ CipherAlg

enum dipki::Cms::CipherAlg

strong

Content encryption algorithm.

Enumerator
Default	Use default algorithm (AES-128) (NB Changed in [v23.0] was Triple DES)
Tdea	Triple DES (TDEA, 3DES, des-ede3)
Aes128	AES-128.
Aes192	AES-192.
Aes256	AES-256.
Aes128_Gcm	AES-128-GCM authenticated encryption algorithm from RFC 5116.
Aes192_Gcm	AES-192-GCM authenticated encryption algorithm in the same manner as RFC 5116.
Aes256_Gcm	AES-256-GCM authenticated encryption algorithm from RFC 5116.
ChaCha20Poly1305	AEAD_CHACHA20_POLY1305 authenticated encryption algorithm from RFC 8439.

◆ ComprDataOptions

enum dipki::Cms::ComprDataOptions : unsigned int

Advanced options for CMS compressed-data objects [BitFlags].

Enumerator
Default_ComprDataOpt	Use default options.
NoInflate	Extract the compressed data as is without inflation.

◆ EnvDataOptions

enum dipki::Cms::EnvDataOptions : unsigned int

Advanced options for CMS enveloped-data objects [BitFlags].

Enumerator
Default_EnvDataOpt	Use default options.
AltEnvAlgId	Use alternative (non-standard) content encryption algorithm identifiers, for example `des_3CBC_pad` instead of `des-ede3-cbc`
Oaep_Mgf1Sha1	Force the MGF1 hash function to be SHA-1 (RSA-OAEP only, default = same as encoding hash algorithm)
UseSkiForRecip	Use subjectKeyIdentifier (SKI) instead of issuerAndSerialNumber for RecipientIdentifier.

◆ Format

enum dipki::Cms::Format

strong

Output format.

Enumerator
Default	Use default (binary).
Binary	Binary output (default).
FormatBase64	Encode output in base64 (default = binary).

◆ HashAlg

enum dipki::Cms::HashAlg

strong

Hash algorithm for RSA-OEAP or ECDH KDF or RSA-KEM.

Enumerator
Default	Use default algorithm.
Sha1	SHA-1 (default)
Sha224	SHA-224.
Sha256	SHA-256 (default for RSA-KEM)
Sha384	SHA-384.
Sha512	SHA=512.

◆ KeyEncrAlg

enum dipki::Cms::KeyEncrAlg

strong

Key encryption algorithm for key transport scheme (ktri)

Enumerator
Default	Use default algorithm (RSAES-PKCS-v1_5) [CAUTION].
Rsa_Pkcs1v1_5	RSAES-PKCS-v1_5 (`rsaEncryption`)
Rsa_Oaep	RSAES-OAEP (NB changed in [v23.0] from 0x8000)
Rsa_Kem	Encrypt the key using the RSA Key Encapsulation Mechanism (RSA-KEM) algorithm.

◆ SigAlg

enum dipki::Cms::SigAlg

strong

Signature algorithm.

Enumerator
Default	Use default signature algorithm [rsa-sha1/`sha1WithRSAEncryption`].
Rsa_Sha1	Use `sha1WithRSAEncryption` (rsa-sha1) signature algorithm [default - CAUTION]
Rsa_Sha224	Use `sha224WithRSAEncryption` (rsa-sha224) signature algorithm
Rsa_Sha256	Use `sha256WithRSAEncryption` (rsa-sha256) signature algorithm [minimum recommended].
Rsa_Sha384	Use `sha384WithRSAEncryption` (rsa-sha384) signature algorithm.
Rsa_Sha512	Use `sha512WithRSAEncryption` (rsa-sha512) signature algorithm.
Rsa_Md5	Use md5WithRSAEncryption (rsa-md5) signature algorithm [legacy, not recommended]
Rsa_Pss_Sha1	Use RSA-PSS signature algorithm with SHA-1.
Rsa_Pss_Sha224	Use RSA-PSS signature algorithm with SHA-224.
Rsa_Pss_Sha256	Use RSA-PSS signature algorithm with SHA-256.
Rsa_Pss_Sha384	Use RSA-PSS signature algorithm with SHA-384.
Rsa_Pss_Sha512	Use RSA-PSS signature algorithm with SHA-512.
Ecdsa_Sha1	Use `ecdsaWithSHA1` (ecdsa-sha1) signature algorithm
Ecdsa_Sha224	Use `ecdsaWithSHA224` (ecdsa-sha224) signature algorithm
Ecdsa_Sha256	Use `ecdsaWithSHA256` (ecdsa-sha256) signature algorithm
Ecdsa_Sha384	Use `ecdsaWithSHA384` (ecdsa-sha384) signature algorithm
Ecdsa_Sha512	Use `ecdsaWithSHA512` (ecdsa-sha512) signature algorithm
Ed25519	Use Ed25519 signature algorithm [RFC8032].
Ed448	Use Ed448 signature algorithm [RFC8032].

◆ SigDataOptions

enum dipki::Cms::SigDataOptions : unsigned int

Advanced options for CMS signed-data objects [BitFlags].

Enumerator
Default_SigDataOpt	Use default options.
ExcludeCerts	Exclude X.509 certs from output.
ExcludeData	Exclude data from output.
CertsOnly	Create a "certs-only" PKCS#7 certficate chain.
AddSigner	Add a new signer to an existing SignedData object.
IncludeAttributes	To add signed attributes (default = no signed attributes) including content-type and message-digest plus any more added below.
AddSignTime	Add signing time to the signed attributes (requires `IncludeAttributes`)
AddSmimeCapabilities	Add S/MIME capabilities to the signed attributes (requires `IncludeAttributes`)
AddSigningCertificate	Add an ESS Signing Certificate attribute to the signed attributes (requires `IncludeAttributes`)
AddAlgProtection	Add an Algorithm Protection Attribute [RFC6211] to the signed attributes (requires `IncludeAttributes`)
NoOuter	Create a "naked" SignedData object with no outerContentInfo as permitted by PKCS#7 v1.6 (specialist option)
UseSkiForSigner	Use subjectKeyIdentifier (SKI) instead of issuerAndSerialNumber for SignerIdentifier
AltSigAlgId	Use alternative (non-standard) signature algorithm identifiers, for example `sha1withRSAEncryption` instead of `rsaEncryption`
Pss_Mgf1Sha1	Force the MGF1 hash function to be SHA-1 (RSASSA-PSS only, default = same as encoding hash function)
Pss_SaltLenZero	Use a zero-length salt in an RSA-PSS signature (default = `hLen` the length of the digest output)
PseudoSig	Create/sign a "pseudo" SignedData object with dummy placeholder signature.

Member Function Documentation

◆ GetSigDataDigest()

static std::string dipki::Cms::GetSigDataDigest	(	const std::string &	inputFile,
		const std::string &	certFile = `""`
	)

static

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

Parameters

inputFile	File containing CMS signed-data object (or a string with its PEM representation).
certFile	an (optional) X.509 certificate file to be used to identify the signer.

Returns: Hash value in hex format.

Remarks: This function extracts the message digest of the signed encapsulated content. In doing so, it also verifies that the signature is valid.; 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; 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.

Exceptions

std::runtime_error Exception if input data is invalid.

◆ MakeComprData()

static int dipki::Cms::MakeComprData	(	const std::string &	outputFile,
		const std::string &	inputFile
	)

static

Create a CMS compressed-data file (.p7z) from an existing input file [binary file --> binary file].

Parameters

outputFile	Name of output file to be created.
inputFile	Input data file.

Returns: Zero if successful.

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

◆ MakeDetachedSig()

static int dipki::Cms::MakeDetachedSig	(	const std::string &	outputFile,
		const std::string &	hexDigest,
		const std::string &	certList,
		const std::string &	privateKey,
		SigAlg	sigAlg = `SigAlg::Default`,
		SigDataOptions	opts = `SigDataOptions::Default_SigDataOpt`,
		Format	format = `Format::Default`
	)

static

Create a "detached signature" CMS signed-data object from a message digest of the content [hexdigest --> file].

Parameters

outputFile	Name of output file to be created.
hexDigest	String containing message digest in hex format.
certList	Filename of the signer's certificate (or a string with its base64 or PEM representation) and (optionally) a list of other certificates to be included in the output, separated by semi-colons(`;`). Alternatively specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate.
privateKey	Internal representation of private key for the sender.
sigAlg	Signature algorithm to use when signing [default=rsa-sha1].
opts	Advanced option flags.
format	Output format (default = binary).

Returns: Zero if successful.

◆ MakeEnvData() [1/2]

static int dipki::Cms::MakeEnvData	(	const std::string &	outputFile,
		const std::string &	inputFile,
		const std::string &	certList,
		CipherAlg	cipherAlg = `CipherAlg::Default`,
		KeyEncrAlg	keyEncrAlg = `KeyEncrAlg::Default`,
		HashAlg	hashAlg = `HashAlg::Default`,
		EnvDataOptions	advOpts = `EnvDataOptions::Default_EnvDataOpt`,
		Format	format = `Format::Default`,
		bool	bigFile = `false`,
		Kdf::KdfAlg	kdfAlg = `Kdf::KdfAlg::X963`,
		Kdf::KeyWrapAlg	keyWrapAlg = `Kdf::KeyWrapAlg::Default`,
		const std::string &	keyString = `""`,
		int	count = `0`
	)

static

Create a CMS enveloped-data object for one or more recipients [file --> file].

Parameters

outputFile	Name of output file to be created.
inputFile	Input data file.
certList	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).
cipherAlg	Content encryption algorithm [default=AES128-CBC]
keyEncrAlg	Key encryption algorithm for key transport scheme [default=RSAES-PKCS-v1_5 (rsaEncryption)].
hashAlg	Hash algorithm for RSAES-OAEP and ECDH KDF [default=SHA-1] or RSA-KEM [default=SHA-256]
advOpts	Advanced option flags.
format	Output format (default = binary).
bigFile	Set as `true` for faster handling of a large input file (binary output only).
kdfAlg	Key derivation function (KDF) for ECDH key agreement scheme (where applicable).
keyWrapAlg	Key wrap algorithm for ECDH key agreement scheme or kekri type (default=match content encryption algorithm)
keyString	Use to pass optional additional user key material (ukm) for KDF where KeyAgreement (kari) type is used.
count	Optional tag length for AuthEnvelopedData (in range 12-16, default=16). Otherwise ignored

Returns: Number of successful recipients or a negative error code.

◆ MakeEnvData() [2/2]

static int dipki::Cms::MakeEnvData	(	const std::string &	outputFile,
		const std::string &	inputFile,
		const std::string &	schemeType,
		const std::string &	keyString,
		CipherAlg	cipherAlg = `CipherAlg::Default`,
		Kdf::KeyWrapAlg	keyWrapAlg = `Kdf::KeyWrapAlg::Default`,
		EnvDataOptions	advOpts = `EnvDataOptions::Default_EnvDataOpt`,
		Format	format = `Format::Default`,
		HashAlg	hashAlg = `HashAlg::Default`,
		int	count = `0`
	)

static

Create a CMS enveloped-data object using pwri or kekri scheme [file --> file].

Parameters

outputFile	Name of output file to be created.
inputFile	Input data file.
schemeType	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.
keyString	Use to pass the password for a pwri type or the key encryption key (KEK) for a kekri type. Either pass a plain ASCII string, e.g. `"abc"` or use the format `"#x<hex-digits>"` to pass a string of arbitrary octet values, e.g. `"#xdeadbeef01"` to pass the 5 bytes `0xde,0xad,0xbe,0xef,0x01`. Required for pwri and kekri types.
cipherAlg	Content encryption algorithm [default=AES128-CBC]
keyWrapAlg	Key wrap algorithm for kekri type (default=match content encryption algorithm)
advOpts	Advanced option flags. Add EnvDataOptions.Authenticated for authenticated encryption.
format	Output format (default = binary).
hashAlg	Hash algorithm for pwri PBKDF2 [default=SHA-1]
count	Optional iteration count for KDF in pwri type (default=4096) or tag length for AuthEnvelopedData (in range 12-16, default=16). Otherwise ignored

Returns: Number of successful recipients or a negative error code.

◆ MakeEnvDataFromBytes()

static int dipki::Cms::MakeEnvDataFromBytes	(	const std::string &	outputFile,
		const dipki::bvec_t &	data,
		const std::string &	certList,
		CipherAlg	cipherAlg = `CipherAlg::Default`,
		KeyEncrAlg	keyEncrAlg = `KeyEncrAlg::Default`,
		HashAlg	hashAlg = `HashAlg::Default`,
		EnvDataOptions	advOpts = `EnvDataOptions::Default_EnvDataOpt`,
		Format	format = `Format::Default`,
		Kdf::KdfAlg	kdfAlg = `Kdf::KdfAlg::X963`,
		Kdf::KeyWrapAlg	keyWrapAlg = `Kdf::KeyWrapAlg::Default`,
		const std::string &	keyString = `""`
	)

static

Create a CMS enveloped-data object for one or more recipients [bytes --> file].

Parameters

outputFile	Name of output file to be created.
data	Input data.
certList	Filename of the signer's certificate (or a string with its base64 or PEM representation) and (optionally) a list of other certificates to be included in the output, separated by semi-colons(`;`). Alternatively specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate.
cipherAlg	Content encryption algorithm [default=AES128-CBC]
keyEncrAlg	Key encryption algorithm [default=RSAES-PKCS-v1_5 (rsaEncryption)].
hashAlg	Hash algorithm for RSAES-OAEP and ECDH KDF [default=SHA-1] or RSA-KEM [default=SHA-256]
advOpts	Advanced option flags.
format	Output format (default = binary).
kdfAlg	Key derivation function (KDF) for ECDH key agreement scheme (where applicable).
keyWrapAlg	Key wrap algorithm for ECDH key agreement scheme.
keyString	Optional user key material (ukm) for ECDH key agreement scheme

Returns: Number of successful recipients or a negative error code.

Remarks: Same as Cms::MakeEnvData except input is from a byte array instead of a file.

◆ MakeEnvDataFromString()

static int dipki::Cms::MakeEnvDataFromString	(	const std::string &	outputFile,
		const std::string &	inputStr,
		const std::string &	certList,
		CipherAlg	cipherAlg = `CipherAlg::Default`,
		KeyEncrAlg	keyEncrAlg = `KeyEncrAlg::Default`,
		HashAlg	hashAlg = `HashAlg::Default`,
		EnvDataOptions	advOpts = `EnvDataOptions::Default_EnvDataOpt`,
		Format	format = `Format::Default`,
		Kdf::KdfAlg	kdfAlg = `Kdf::KdfAlg::X963`,
		Kdf::KeyWrapAlg	keyWrapAlg = `Kdf::KeyWrapAlg::Default`,
		const std::string &	keyString = `""`
	)

static

Create a CMS enveloped-data object for one or more recipients [string --> file].

Parameters

outputFile	Name of output file to be created.
inputStr	Input data string.
certList	Filename of the signer's certificate (or a string with its base64 or PEM representation) and (optionally) a list of other certificates to be included in the output, separated by semi-colons(`;`). Alternatively specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate.
cipherAlg	Content encryption algorithm [default=AES128-CBC]
keyEncrAlg	Key encryption algorithm [default=RSAES-PKCS-v1_5 (rsaEncryption)].
hashAlg	Hash algorithm for RSAES-OAEP and ECDH KDF [default=SHA-1] or RSA-KEM [default=SHA-256]
advOpts	Advanced option flags.
kdfAlg	Key derivation function (KDF) for ECDH key agreement scheme (where applicable).
keyWrapAlg	Key wrap algorithm for ECDH key agreement scheme.
keyString	Optional user key material (ukm) for ECDH key agreement scheme
format	Output format (default = binary).

Returns: Zero if successful.

Remarks: Same as Cms::MakeEnvData except input is from a string instead of a file.

◆ MakeSigData()

static int dipki::Cms::MakeSigData	(	const std::string &	outputFile,
		const std::string &	inputFile,
		const std::string &	certList,
		const std::string &	privateKey,
		SigAlg	sigAlg = `SigAlg::Default`,
		SigDataOptions	opts = `SigDataOptions::Default_SigDataOpt`,
		Format	format = `Format::Default`,
		bool	bigFile = `false`
	)

static

Create a CMS signed-data object from a data file [file --> file].

Parameters

outputFile	Name of output file to be created.
inputFile	File containing message data to be signed.
certList	Filename of the signer's certificate (or a string with its base64 or PEM representation) and (optionally) a list of other certificates to be included in the output, separated by semi-colons(`;`). Alternatively specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate.
privateKey	Internal representation of private key for the sender.
sigAlg	Signature algorithm to use when signing [default=rsa-sha1].
opts	Advanced option flags.
format	Output format options [default=binary].
bigFile	Set as `true` for faster handling of a large input file (binary output only).

Returns: Zero if successful.

◆ MakeSigDataFromBytes()

static int dipki::Cms::MakeSigDataFromBytes	(	const std::string &	outputFile,
		const dipki::bvec_t &	data,
		const std::string &	certList,
		const std::string &	privateKey,
		SigAlg	sigAlg = `SigAlg::Default`,
		SigDataOptions	opts = `SigDataOptions::Default_SigDataOpt`,
		Format	format = `Format::Default`
	)

static

Create a CMS signed-data object from data [bytes --> file].

Parameters

outputFile	Name of output file to be created.
data	Message data to be signed.
certList	Filename of the signer's certificate (or a string with its base64 or PEM representation) and (optionally) a list of other certificates to be included in the output, separated by semi-colons(`;`). Alternatively specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate.
privateKey	Internal representation of private key for the sender.
sigAlg	Signature algorithm to use when signing [default=rsa-sha1].
opts	Advanced option flags.
format	Output format options [default=binary].

Returns: Zero if successful.

◆ MakeSigDataFromPseudo()

static int dipki::Cms::MakeSigDataFromPseudo	(	const std::string &	outputFile,
		const std::string &	inputPseudoFile,
		const dipki::bvec_t &	sigValue,
		Format	format = `Format::Default`
	)

static

Create a SignedData object from a "pseudo" object.

Parameters

outputFile	Name of output file to be created.
inputPseudoFile	Input "pseudo" file with dummy placeholder signature.
sigValue	Signature value computed by external service.
format	Output format (default = binary).

Returns: Zero if successful.

Remarks: RSASSA-PKCS1V1_5 only.

◆ MakeSigDataFromSigValue()

static int dipki::Cms::MakeSigDataFromSigValue	(	const std::string &	outputFile,
		const dipki::bvec_t &	sigValue,
		const dipki::bvec_t &	data,
		const std::string &	certList,
		SigAlg	sigAlg = `SigAlg::Default`,
		SigDataOptions	opts = `SigDataOptions::Default_SigDataOpt`,
		Format	format = `Format::Default`
	)

static

Create a CMS object of type SignedData using a pre-computed signature value [bytes --> file].

Parameters

outputFile	Name of output file to be created.
sigValue	Signature value.
data	Message data to be signed.
certList	Filename of the signer's certificate (or a string with its base64 or PEM representation) and (optionally) a list of other certificates to be included in the output, separated by semi-colons(`;`). Alternatively specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate.
sigAlg	Signature algorithm to use when signing [default=rsa-sha1]. RSA-PKCS1V1_5 only.
opts	Advanced option flags.
format	Output format options [default=binary].

Returns: Zero if successful.

◆ MakeSigDataFromString()

static int dipki::Cms::MakeSigDataFromString	(	const std::string &	outputFile,
		const std::string &	inputStr,
		const std::string &	certList,
		const std::string &	privateKey,
		SigAlg	sigAlg = `SigAlg::Default`,
		SigDataOptions	opts = `SigDataOptions::Default_SigDataOpt`,
		Format	format = `Format::Default`
	)

static

Create a CMS signed-data object from a string [string --> file].

Parameters

outputFile	Name of output file to be created.
inputStr	String containing message data to be signed.
certList	Filename of the signer's certificate (or a string with its base64 or PEM representation) and (optionally) a list of other certificates to be included in the output, separated by semi-colons(`;`). Alternatively specify a single PKCS#7 certificate chain file (.p7c/.p7b) containing the signer's certificate.
privateKey	Internal representation of private key for the sender.
sigAlg	Signature algorithm to use when signing [default=rsa-sha1].
opts	Advanced option flags.
format	Output format options [default=binary].

Returns: Zero if successful.

◆ QueryEnvData()

static std::string dipki::Cms::QueryEnvData	(	const std::string &	inputFile,
		const std::string &	query
	)

static

Query a CMS enveloped-data object for selected information.

Parameters

inputFile	File containing CMS enveloped-data object (or a string with its PEM representation).
query	Query string (case insensitive). See remarks.

Returns: String containing the result, or an empty string if not found.

Remarks

An integer result is returned as a string, e.g. "1". Use std::stoi(s) to convert to an integer.

Valid queries are:

Query String	Returns
`version`	envelopedData CMSVersion (`edVer`) value, e.g. `"0"`.
`recipientInfoVersion`	recipientInfo version (`riVer`) value
`recipientInfoType`	Type of recipientInfo: `ktri`, `kari`, `kekri`, `pwri`
`countOfRecipientInfos`	Number of RecipientInfos included in the data
`recipientIssuerName`	Distinguished Name of recipient's certificate issuer
`recipientSerialNumber`	serialNumber of recipient's certificate in hex format
`keyEncryptionAlgorithm`	keyEncryptionAlgorithm, e.g. `"rsaEncryption"`
`keyEncryptionFlags`	Bit flags used for the key encryption algorithm (ktri only)
`sizeofEncryptedKey`	Size (in bytes) of the EncryptedKey
`encryptedKey`	EncryptedKey value encoded in hex
`oaepParams`	Parameters used for RSA-OAEP (if applicable).
`keyWrapAlgorithm`	Key wrap algorithm, e.g. `"aes128-wrap"` (if applicable)
`originatorKeyAlgorithm`	OriginatorPublicKey algorithm, e.g. `"ecPublicKey"`
`originatorPublicKey`	OriginatorPublicKey publicKey value encoded in hex
`keyid`	keyIdentifier for KEKRecipientInfo (kekri) type
`contentEncryptionAlgorithm`	contentEncryptionAlgorithm, e.g. `"des-EDE3-CBC"`
`sizeofEncryptedContent`	Size (in bytes) of the EncryptedContent
`encryptedContent`	EncryptedContent encoded in hex
`iv`	Initialization vector encoded in hex

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.

Exceptions

std::runtime_error Exception with error code if input data or query is invalid.

◆ QuerySigData()

static std::string dipki::Cms::QuerySigData	(	const std::string &	inputFile,
		const std::string &	query
	)

static

Query a CMS signed-data object for selected information.

Parameters

inputFile	File containing CMS signed-data object (or a string with its PEM representation).
query	Query string (case insensitive). See remarks.

Returns: String containing the result, or an empty string if not found.

Remarks

An integer result is returned as a string, e.g. "1". Use std::stoi(s) to convert to an integer.

Valid queries are:

Query String	Returns
`version`	signedData version (`sdVer`) value, e.g. `"1"`.
`eContentType`	ContentType of the EncapsulatedContentInfo, e.g. `"data"`
`HASeContent`	`"1"` if eContent is present; `"0"` if not
`CountOfCertificates`	Number of certificates included in the data
`CountOfSignerInfos`	Number of SignerInfos included in the data
`signerInfoVersion`	signerInfo version (`siVer`) value
`digestAlgorithm`	digestAlgorithm, e.g. `"sha1"`
`signatureAlgorithm`	signatureAlgorithm, e.g. `"rsaEncryption"`
`signatureValue`	Signature value encoded in hex
`HASsignedAttributes`	`"1"` if signedAttributes (authenticatedAttributes) are present; `"0"` if not
`DigestOfSignedAttrs`	Computed digest over signed attributes, if present, using digestAlgorithm
`DigestOfeContent`	Computed digest over eContent, if present, using digestAlgorithm
`signingTime`	signingTime attribute in format `"2005-12-31 23:30:59"`
`messageDigest`	messageDigest attribute in hexadecimal format, if present
`pssParams`	Parameters used for RSA-PSS (if applicable).
`HASsigningCertificate`	`"1"` if an ESS signingCertificate is present; `"0"` if not.
`signingCertHash`	certHash value of ESS signing certificate, if present, encoded in hex
`HASalgorithmProtection`	`"1"` if a cmsAlgorithmProtection attribute is present; `"0"` if not.

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.

Exceptions

std::runtime_error Exception with error code if input data or query is invalid.

◆ ReadComprData()

static int dipki::Cms::ReadComprData	(	const std::string &	outputFile,
		const std::string &	inputFile,
		ComprDataOptions	opts = `ComprDataOptions::Default_ComprDataOpt`
	)

static

Read and extract the decompressed contents of a CMS compressed-data file [binary file --> binary file].

Parameters

outputFile	Name of output file to be created.
inputFile	Input data file.
opts	Options [default=inflate contents].

Returns: Zero if successful.

◆ ReadEnvDataToBytes()

static bvec_t dipki::Cms::ReadEnvDataToBytes	(	const std::string &	inputFile,
		const std::string &	privateKey,
		const std::string &	certFile = `""`
	)

static

Read and decrypt a CMS enveloped-data object to a byte array [file --> bytes].

Parameters

inputFile	Input data file.
privateKey	Internal representation of private key.
certFile	(optional) recipient's X.509 certificate.

Returns: Message data.

Remarks: To convert bytes array to a string use dipki::bvec2str().

◆ ReadEnvDataToFile()

static int dipki::Cms::ReadEnvDataToFile	(	const std::string &	outputFile,
		const std::string &	inputFile,
		const std::string &	privateKey,
		const std::string &	certFile = `""`,
		bool	bigFile = `false`
	)

static

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

Parameters

outputFile	Name of output file to be created.
inputFile	Input data file.
privateKey	Internal representation of private key.
certFile	(optional) recipient's X.509 certificate.
bigFile	Set as `true` for faster handling of a large input file (binary only).

Returns: Number of successful recipients or a negative error code.

◆ ReadSigDataToBytes()

static bvec_t dipki::Cms::ReadSigDataToBytes ( const std::string & inputFile )

static

Read and decrypt a CMS enveloped-data object to a byte array [file --> bytes].

Parameters

inputFile Input data file.

Returns: Message data.

Remarks: To convert bytes array to a string use dipki::bvec2str().

Exceptions

std::runtime_error Exception if input data is invalid.

◆ ReadSigDataToFile()

static int dipki::Cms::ReadSigDataToFile	(	const std::string &	outputFile,
		const std::string &	inputFile,
		bool	bigFile = `false`
	)

static

Read the content from a CMS signed-data object file [file --> file].

Parameters

outputFile	Name of output file to be created.
inputFile	Name of file containing CMS signed-data object (binary or base64-encoded) or the data as a base64 or PEM string.
bigFile	Set as `true` for faster handling of a large input file (binary only).

Returns: Zero if successful.

Exceptions

std::runtime_error Exception if input data is invalid.

◆ VerifySigData()

static bool dipki::Cms::VerifySigData	(	const std::string &	inputFile,
		const std::string &	certFile = `""`,
		const std::string &	hexDigest = `""`,
		bool	bigFile = `false`
	)

static

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

Parameters

inputFile	File containing CMS signed-data object (or a string with its PEM representation).
certFile	(optional) X.509 certificate file of the signer (or its base64 or PEM representation).
hexDigest	(optional) digest of eContent to be verified (use for "detached-signature" form).
bigFile	Set as `true` for faster handling of a large input file.

Returns: True if signature is valid, else false.

Remarks: If a certificate is specified in certFile then the public key from that certificate will be used and a matching signerInfo field 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. 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 hexDigest parameter.

Exceptions

std::runtime_error Exception if file is missing or corrupt, or parameters are bad, etc.

Public Types

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ CipherAlg

◆ ComprDataOptions

◆ EnvDataOptions

◆ Format

◆ HashAlg

◆ KeyEncrAlg

◆ SigAlg

◆ SigDataOptions

Member Function Documentation

◆ GetSigDataDigest()

◆ MakeComprData()

◆ MakeDetachedSig()

◆ MakeEnvData() [1/2]

◆ MakeEnvData() [2/2]

◆ MakeEnvDataFromBytes()

◆ MakeEnvDataFromString()

◆ MakeSigData()

◆ MakeSigDataFromBytes()

◆ MakeSigDataFromPseudo()

◆ MakeSigDataFromSigValue()

◆ MakeSigDataFromString()

◆ QueryEnvData()

◆ QuerySigData()

◆ ReadComprData()

◆ ReadEnvDataToBytes()

◆ ReadEnvDataToFile()

◆ ReadSigDataToBytes()

◆ ReadSigDataToFile()

◆ VerifySigData()