EnvelopedCms Message

Article
11/03/2006

CMS/PKCS #7 provides the EnvelopedCms class to digitally envelope messages.

Digitally enveloping a message protects it by applying a security service known as data confidentiality.

The digital envelope uses encryption to help keep the message confidential. A session key is generated and used to encrypt the message. The session key is itself then encrypted by using the public key of the recipient. The combination of the encrypted message and the encrypted session key constitutes the digital envelope. Upon receipt, the session key is decrypted by using the private key of the recipient. The message is then decrypted by using the session key. The session key can be used to both encrypt and decrypt the message because it is a symmetric key.

Use the EnvelopedCms class in any application that has the requirement to maximize the confidentiality of the data. E-mail, using the S/MIME security standard, is an example of how you can use the EnvelopedCms class to provide security. In addition to other security services, S/MIME specifies the ability to encrypt an e-mail message for multiple recipients. Digital envelopes are tailored to meet that need.

Use one of the Encrypt methods of the EnvelopedCms class to encrypt a message. The System.Security.Cryptography.Pkcs.EnvelopedCms.Encrypt(System.Security.Cryptography.Pkcs.CmsRecipient) method requires the application to first set up the characteristics of the message recipient by constructing a CmsRecipient object. The CmsRecipient class stores the recipient's X509 certificate and the technique by which a session key is established between the message sender and recipient. The System.Security.Cryptography.Pkcs.EnvelopedCms.Encrypt method presents a dialog box so the user can select the appropriate recipient's certificate.

The EnvelopedCms class supports enveloping a message for multiple recipients. Set up the group of recipients in a CmsRecipientCollection collection to use as input to the System.Security.Cryptography.Pkcs.EnvelopedCms.Encrypt(System.Security.Cryptography.Pkcs.CmsRecipientCollection) method.

There are two techniques for establishing the session key between the sender and the recipient of a message. Key transport algorithms typically use the RSA (http://www.rsasecurity.com/rsalabs/node.asp?id=2125) algorithm, in which an originator establishes a shared cryptographic key with a recipient by generating that key and then transporting it to the recipient. Key agreement algorithms typically use the Diffie-Hellman key agreement (http://www.rsasecurity.com/rsalabs/node.asp?id=2126) algorithm. In it, two parties establish a shared cryptographic key by both taking part in its generation and, by definition, agree on that key.

Information for each recipient of an EnvelopedCms message is available in the System.Security.Cryptography.Pkcs.EnvelopedCms.RecipientInfos property. Information about a recipient that establishes the session key with the sender by means of a key transport algorithm is found in a KeyTransRecipientInfo object. Information about a recipient that establishes the session key with the sender by means of a key agreement algorithm is found in a KeyAgreeRecipientInfo object.

An EnvelopedCms message can include unprotected attributes. These are attributes that are not encrypted; they do not have data confidentiality. These attributes are stored in the System.Security.Cryptography.Pkcs.EnvelopedCms.UnprotectedAttributes property.

Use one of the Decrypt methods of the EnvelopedCms class to decrypt the enveloped message. The EnvelopedCms message contains the recipients' identifying information that is necessary for the decryption. That information is contained in the RecipientInfos property.

For several code examples that use EnvelopedCms messages, see Using System.Security.Cryptography.Pkcs.

EnvelopedCms Message

See Also

Tasks

Reference

Concepts

Additional resources