SignedCms Message

Article
11/03/2006

CMS/PKCS #7 provides the SignedCms class to digitally sign messages.

Digitally signing a message protects it by applying security services known as entity authentication and data integrity. Entity authentication gives a high probability that an entity claiming to be the author or sender of a message is indeed that entity. The entity can be a person, a software application, or any other source with a unique identity.

Data integrity gives a high probability that the message itself was not altered in any way, including by deletion or duplication.

Use the SignedCms class to apply either or both of these security services to a message. Use this class if the goal is to verify with high probability the authenticity of a message sender or author, or that the message has not been modified while in storage or transit, or both.

E-mail, using the S/MIME security standard, is an example of how you can use the SignedCms class to provide security. In addition to other security services, S/MIME specifies the ability to verify the authenticity of the sender of an e-mail message as well as the checking the integrity of the message itself.

Multiple signatures can be applied to a message. An example of an application that may need this capability is a document authoring and reading application. With the support of multiple signatures by CMS/PKCS #7, the application can allow multiple document authors to each sign the document they took part in writing. It can also allow the document reader to verify that the claimed authors are the actual authors of a document, and that the document has not been modified since it was signed.

Use one of the ComputeSignature methods of the SignedCms class to compute a message signature. The System.Security.Cryptography.Pkcs.SignedCms.ComputeSignature(System.Security.Cryptography.Pkcs.CmsSigner) method requires the application to first set up the characteristics of the message signer by constructing a CmsSigner object. The CmsSigner class stores the signer's X509 certificate in addition to other properties. The System.Security.Cryptography.Pkcs.SignedCms.ComputeSignature method presents a dialog box so the user can select the appropriate signer's certificate.

A signer's certificate chain can be included in whole or in part within the System.Security.Cryptography.Pkcs.CmsSigner.Certificates property. Set the System.Security.Cryptography.Pkcs.CmsSigner.IncludeOption property to affect how much of the certificate chain is included.

A SignedCms message can either be nondetached or detached. The Boolean property System.Security.Cryptography.Pkcs.SignedCms.Detached determines whether the message is detached. A nondetached SignedCms message contains the message that was signed. A detached SignedCms message does not contain the message that was signed, but contains all other properties of the message, such as signatures and attributes. An example of an application in which a detached SignedCms message might be used is a document-reading application. In this case, it might be undesirable to duplicate the storage of a large signed document by having it stored in the SignedCms message in addition to a primary storage location. Applications that sign large contents are most likely to use detached SignedCms messages.

CMS/PKCS #7 supports countersignatures. A countersignature is a digital signature of another digital signature. As such, it only provides authenticity of the signature, and not of the message's content. A digital signature can be countersigned by multiple countersigners. However, CMS/PKCS #7 supports only one level of countersignature. A countersignature itself cannot be countersigned. An example of an application that might use countersignatures is a digital notary service.

Use one of the ComputeCounterSignature methods of the SignerInfo class to compute a countersignature. The System.Security.Cryptography.Pkcs.SignedCms.SignerInfos property is a collection of SignerInfo objects that result from signing a message. The ComputeCounterSignature methods work analogous to that of the ComputeSignature methods of the SignedCms class.

A SignedCms message can have associated signature-specific attributes. These attributes can be signed or unsigned.

Signed attributes are placed in the message by setting them in the appropriate signer's System.Security.Cryptography.Pkcs.CmsSigner.SignedAttributes property. When a signature is computed for that signer, the signed attributes are signed along with the inner content in the System.Security.Cryptography.Pkcs.SignedCms.ContentInfo property. The signed attributes are available after the message has been signed in the System.Security.Cryptography.Pkcs.SignerInfo.SignedAttributes property for the applicable signer from the System.Security.Cryptography.Pkcs.SignedCms.SignerInfos property. An example of a signed attribute that might be useful is the Pkcs9SigningTime signing-time attribute. This attribute contains the time that the message was signed.

Unsigned attributes are placed in the message by setting them in the appropriate signer's System.Security.Cryptography.Pkcs.CmsSigner.UnsignedAttributes property. These attributes are not signed—it cannot be assumed that they have authenticity or integrity. The unsigned attributes are available after the message has been signed in the System.Security.Cryptography.Pkcs.SignerInfo.UnsignedAttributes property for the applicable signer from the System.Security.Cryptography.Pkcs.SignedCms.SignerInfos property. An example of an unsigned attribute that is used internally by CMS/PKCS #7 is a countersignature. Because it is already a type of signature, it does not need to be signed again. Another example of an attribute that might remain unsigned is a document description, available in the Pkcs9DocumentDescription class.

Use one of the CheckSignature methods of the SignedCms class to verify the message signatures, countersignatures, and signed attributes. The SignedCms message contains the signers' certificates that are necessary for the verification. The signature verification can either validate the signers' certificates or not, as determined by the value of the verifySignatureOnly parameter to these methods.

To verify a detached SignedCms message, first associate the content of the message with the SignedCms message. Do so by constructing a ContentInfo object with the message content. Use that to construct a SignedCms object by using, for example, the SignedCms constructor. Set the second parameter to true to indicate that the message is detached. Decode the encoded SignedCms message to be verified by using the Decode method. Finally, check the signature as previously described.

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

SignedCms Message

See Also

Tasks

Reference

Concepts

Additional resources