Click or drag to resize

CmsMakeEnvData(String, String, String, CipherAlgorithm, CmsKeyEncrAlgorithm, HashAlgorithm, CmsEnvDataOptions, KdfKdfAlg, KdfKeyWrapAlg, String, Int32, CmsContentEncrAlg) Method

Create a CMS enveloped-data object (advanced options).

Namespace: CryptoSysPKI
Assembly: diCrSysPKINet (in diCrSysPKINet.dll) Version: 23.0.0.30549 (23.1.0.0)
Syntax
Copy
public static int MakeEnvData(
	string outputFile,
	string inputFile,
	string certList,
	CipherAlgorithm cipherAlg = ,
	CmsKeyEncrAlgorithm keyEncrAlg = CmsKeyEncrAlgorithm.Default,
	HashAlgorithm hashAlg = HashAlgorithm.Sha1,
	CmsEnvDataOptions advOptions = CmsEnvDataOptions.None,
	KdfKdfAlg kdfAlg = KdfKdfAlg.X963,
	KdfKeyWrapAlg keyWrapAlg = KdfKeyWrapAlg.Default,
	string keyString = "",
	int count = 0,
	CmsContentEncrAlg contEncrAlg = CmsContentEncrAlg.Aes128
)

Parameters

outputFile  String
Name of output file to be created.
inputFile  String
Input data file.
certList  String
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.

cipherAlg  CipherAlgorithm  (Optional)
Content encryption algorithm [default=ignored]. Deprecated: use contEncrAlg. (This parameter will be removed in a future update)
keyEncrAlg  CmsKeyEncrAlgorithm  (Optional)
Key encryption algorithm for ktri type [default=RSAES-PKCS-v1_5)]
hashAlg  HashAlgorithm  (Optional)
Hash function where applicable. Must be one of the SHA-* family [default=SHA-1; SHA-256 for RSA-KEM]
advOptions  CmsEnvDataOptions  (Optional)
Advanced options. See CmsEnvDataOptions.
kdfAlg  KdfKdfAlg  (Optional)
Key derivation function (KDF) for ECDH key agreement scheme (where applicable)
keyWrapAlg  KdfKeyWrapAlg  (Optional)
Key wrap algorithm for ECDH key agreement scheme or kekri type (default=match content encryption algorithm)
keyString  String  (Optional)
(formerly ukmString) Use to pass optional additional user key material (ukm) for KDF where KeyAgreement (kari) type is used. Or use to pass the password for a pwri type or the key encryption key (KEK) for a kekri type. Either pass a plain ASCII string, e.g. "abc" or use the format "#x<hex-digits>" to pass a string of arbitrary octet values, e.g. "#xdeadbeef01" to pass the 5 bytes 0xde,0xad,0xbe,0xef,0x01. Required for pwri and kekri types.
count  Int32  (Optional)
Optional iteration count for KDF in pwri type (default=4096) or tag length for AuthEnvelopedData (in range 12-16, default=16). Otherwise ignored.
contEncrAlg  CmsContentEncrAlg  (Optional)
Preferred way to specify content encryption algorithm with more options. Takes precedence over cipherAlg. [default=AES128-CBC]

Return Value

Int32
Number of successful recipients or a negative error code.
Remarks
The output is a file containing a CMS EnvelopedData object or AuthEnvelopedData object. New in [v22.0] use the preferred contEncrAlg parameter to specify the content-encryption algorithm rather than cipherAlg. If a list of certificates is passed in certList, the recipientInfo type is set automatically depending on the public key found in each certificate, one for each certificate. If the public key is RSA (rsaEncryption) then the key transport technique (ktri) will be used for 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].

Alternatively, use key encryption option Cms.KeyEncrAlgorithm.Rsa_Kem with an RSA public key, and the RSA-KEM algorithm using KEMRecipientInfo will be used for key encryption.

If certList is set to "type=@pwri" then a single recipientInfo will be created of PasswordRecipientInfo type (pwri). The password must be passed in the keyString parameter. The parameters keyEncrAlg, kdfAlg and keyWrapAlg are ignored in this case. If certList is set to "type=@kekri,keyid=<string>" then a single recipientInfo will be created of KEKRecipientInfo type (kekri). The key encryption key (KEK) must be passed in the keyString parameter. The parameters keyEncrAlg, hashAlg and kdfAlg are ignored in this case.

Example
C#
Copy
// Create an enveloped CMS object (ktri type) to Bob using Bob's RSA key
n = Cms.MakeEnvData("cms2bob_aes128.p7m", "excontent.txt", "BobRSASignByCarl.cer", CipherAlgorithm.Aes128, Cms.KeyEncrAlgorithm.Rsa_Oaep);

// Create an enveloped CMS object (kekri type) using a previously distributed symmetric key-encryption key (KEK) 
n = Cms.MakeEnvData("cms_envdata_kekri.p7m", "excontent.txt", "type=@kekri,keyid=ourcommonkey", CipherAlgorithm.Aes256, 
        hashAlg: HashAlgorithm.Sha256, keyWrapAlg:Kdf.KeyWrapAlg.Aes128_wrap, keyString: "#x0123456789ABCDEFF0E1D2C3B4A59687");
See Also