CMS SignedData objects

A SignedData object is a digitally-signed container for arbitrary message content. You can create a SignedData object using one of the CMS_MakeSigData, CMS_MakeSigDataFromString, CMS_MakeSigDataFromSigValue, or CMS_MakeDetachedSig functions.

The original specification for a SignedData object is in RSA Lab's PKCS#7 Cryptographic Message Syntax Standard [PKCS7]. The last complete version of this document is version 1.5, which is also republished as RFC 2315. There is also a version 1.6 which is currently just an addendum note [PKCS7-EXT] and which extends the original specification. The CMS specification Cryptographic Message Syntax [CMS] is based on PKCS#7 version 1.5 and ties down some of its ambiguities. S/MIME [SMIME-MSG] uses the CMS specification. Between them, these various documents define five versions of a SignedData object. We support CMS version 1 only (but with a side order of PKCS#7 version 1.6 "naked" SignedData objects also thrown in) - see Supported Algorithms.

A CMS version 1 SignedData object has a variety of possible combinations in what it can contain:

• The original message content (known as eContent) may be included or not (the latter case is known as a "detached signature").
• One person may sign it, or there may be multiple signers.
• Each signer can optionally include signed attributes such as the time of signing or supported S/MIME algorithms (CMS calls these signedAttributes and PKCS#7 calls them authenticatedAttributes). Once signed attributes are included, the method for computing and verifying the digital signature is different.
• If signed attributes are included, then they must include the message digest of the eContent, which is then sent in the clear. The signer then digitally signs a message digest of the signedAttributes themselves, formatted in a specific way. If signed attributes are not present, then the signer signs the message digest of the eContent directly.
• The person signing may or may not include their X.509 certificate for the recipient to use to verify the signature. If it is not included, the recipient has to obtain a copy of the signer's certificate by other means.
• The entire certificate chain for the signer (or multiple signers) can also be included, as could any other certificate the creator feels like including.
• At one extreme, the SignedData object can just consist of a collection of certificates with no signature and no signed message content. These are known as PKCS#7 certficate chain files or in S/MIME terminology as degenerate "certs-only" objects. This format is commonly used to distribute X.509 certificates, usually with the .p7c or .p7b filename extension. Some people sneakily use the .cer extension for these types of files as well, even though that extension is usually used only for single X.509 certificates.

By now we hope you have got the idea that there is whole host of combinations of how to deal with these objects. To verify that the message content was indeed signed by the signer requires the recipient to do the following:

1. Obtain a copy of the signer's X.509 certificate, unless this is already included in the SignedData, and verify independently that this certificate is valid.
2. Decrypt the signature in the SignedData using the public key inside the signer's certificate.
3. Verify that the message digest of the eContent matches the message digest included in the SignedData.

The function CMS_VerifySigData carries out steps 2 and 3 directly with options for the user to pass the signer's certificate details if they are not already included and also to pass the message digest of the eContent for detached signatures.

The function CMS_GetSigDataDigest will extract the message digest, if possible, to enable the user to perform their own separate comparison with an independently-computed message digest. Note that being able to retrieve the message digest with this function implicitly verifies that the purported signer really did use their private key to sign the object. However, unlike the CMS_VerifySigData function, success with this function does not necessarily mean that the signer actually signed the eContent itself. Furthermore, if the signer used the DSA signature algorithm and did not include message attributes, then you cannot directly extract the message digest of the eContent. Confused so far? Try writing this manual.

To extract just the certificates themselves from a SignedData object, use the X509_GetCertFromP7Chain function. This will work for all types of SignedData objects, not just the "certs-only" type.

[Contents] [Index]