Chapter 9: PKCS#7 Signatures and Envelopes

Public-Key Cryptography Standards (PKCS) are RSA Data Security, Inc.'s series of de-facto standard formats for public-key cryptography. Among all the PKCS standards, PKCS#7 is probably the most widely used one. It describes a general syntax for data that may have cryptography applied to it, such as digital signatures and digital envelopes.

The S/MIME secure mail standard uses PKCS#7 for its digitally signed and encrypted messages. Certificate requests and certificate store (.spc) files also normally use the PKCS#7 format. Every PKCS#7 blob usually encapsulates some content (such as an encrypted message or signed hash value) and one or more certificates used to encrypt or sign this content.

AspEncrypt provides support for the PKCS#7 format via the CryptoMessage object.

9.2.1 Encryption

The CryptoMessage object enables you to encrypt text information directly with a certificate's public key in one easy step. The resultant PKCS#7 encrypted message (also known as "envelope") can only be decrypted with a private key context associated with this certificate. Decryption can take place on the client's machine using the XEncrypt ActiveX control, or on the server.

PKCS#7 envelopes also allow you to encrypt data with multiple certificates at the same time. Any one of the corresponding private keys is sufficient to decrypt the message.

The following code sample demonstrates how to use the CryptoMessage object to encrypt a text string with a certificate. For this code sample to work, you must export your personal certificate to a .cer file and place it on the server.

The CryptoMessage method EncryptText performs encryption on the specified text string and returns a PKCS#7 envelope which may look similar to the following:

Even a short string turns into a relatively large encrypted blob because a PKCS#7 envelope also contains the certificate used for encryption.

Before running this code sample, you need to export your personal certificate to a file and change the path argument to ImportCertFromFile, if necessary. Click on the links below to run this code sample.

http://localhost/aspencrypt/manual_09/09_encrypt.asp http://localhost/aspencrypt/manual_09/09_encrypt.aspx

9.2.1 Decryption

To decrypt a PKCS#7 envelope, you need to call the CryptoMessage method DecryptText and pass it, besides the blob, the name of the private key container for the encryption certificate. This name can be obtained via the expression Cert.PrivateKeyContext.ContainerName. If no container name is specified, AspEncrypt will try all certificates in the MY store until a match is found.

The following code snippet is to be executed on the user's machine using the XEncrypt ActiveX control:

Click on the links below to run this code sample.

http://localhost/aspencrypt/manual_09/09_decrypt_vb.htm http://localhost/aspencrypt/manual_09/09_decrypt_js.htm

Using XEncrypt as described above is not the only way to decrypt a PKCS#7 envelope on the user's machine. An alternative method is to generate an email message with the PKCS#7 blob as the message body. An S/MIME-enabled email client such as Microsoft Outlook, Outlook Express, Mozilla Thunderbird or Windows Live Mail with a digital certificate installed will be able to decrypt the envelope and display its content to the user. For this arrangement to work, certain MIME headers have to be added to the email message, and the CR/LF characters must be put in front of the text string before it can be operated on by CryptoMessage.EncryptText.

The following code sample demonstrates this technique:

Before running this code sample, you need to specify your own certificate path, SMTP server and email addresses.

Click on the links below to run this code sample.

http://localhost/aspencrypt/manual_09/09_email.asp http://localhost/aspencrypt/manual_09/09_email.aspx

9.4.1 Signature Generation

The CryptoMessage object can also be used to generate detached PKCS#7 digital signatures using a user certificate's private key. To let a user pick a certificate for signing, you can follow the same procedure as in the previous chapter. The only difference is that instead of using CryptoHash.Sign to generate a signature, you should use CryptoMessage.SignText, as follows:

The CryptoMessage object is also capable of generating PKCS#7 signatures from arbitrary files via the method CryptoMessage.SignFile. This method is identical to SignText except that it expects a file path as an argument:

9.4.2 Signature Verification

The CryptoMessage object provides the method VerifySignature which verifies a detached PKCS#7 signature against a given hash value and a public key contained in a certificate. The following code verifies a signature generated by the previous sample:

9.4.3 Client-Side Signing of Server-Side Data

As of Version 2.9, the CryptoMessage object is capable of generating PKCS#7 signatures based solely on the hash value of data being signed. The data itself does not need to be present to generate the signature. This is particularly useful when the data being signed resides on the server, while the signer certificate resides on the user workstation, and neither the data nor the user's private key can travel for security or practicality reasons.

Under this scenario, the hash value of the sever-side data is calculated and transferred to the client side where it is fed to CryptoMessage's new SignHash method. This method accepts a single argument, a CryptoBlob object populated with the hash value. Currently, only 20-byte values (SHA1) are supported as the input. The method returns another CryptoBlob object populated with the PKCS#7 signature of the specified hash value. The following code sample creates the PKCS#7 signature of a Hex-encoded hash value and formats the signature as a Hex-encoded string.

While the SignHash method can be used to sign any kind of server-side data, this feature was added to AspEncrypt specifically to implement the client-side signing of server-side PDF files using the Persits AspPDF and AspPDF.NET components. The following user manual chapters contain detailed code samples and live demos demonstrating the use of the CryptoMessage.SignHash method in tandem with our PDF management components to perform the secure signing of PDF documents:

AspPDF User Manual Section 8.4 - Client-Side Signing of Server-Side PDFs

AspPDF.NET User Manual Section 8.4 - Client-Side Signing of Server-Side PDFs

9.5.1 Enhancements in EncryptText and EncryptBinary

As of Version 2.6, CryptoKey's EncryptText and EncryptBinary methods can be used not only for symmetric but also for public-key encryption. The encrypted data comes out in the PKCS#1 format and has Little-Endian byte order.

The following code snippet imports a certificate's public key into the CryptoKey object and encrypts some test with it.

Note that only short strings can be encrypted this way.

To decrypt, CryptoKey's DecryptText and DecryptBinary methods should be used. The decrypting CryptoKey object must be created using a context associated with the proper private key. For example, to decrypt with the private key associated with a certificate residing in the MY store, the following code can be used:

Note that many public-key encryption packages such as OpenSSL expect the PKCS#1 encrypted data to have Big-Endian byte order. Call the CryptoBlob Reverse method to reverse the byte order if necessary.

9.5.2 Importing Public Keys in PEM Format

Public keys are often distributed in the Privacy Enhanced Mail (PEM) format where the Base64-encoded public key is sandwiched between the header -----BEGIN CERTIFICATE---- and footer -----END CERTIFICATE----, as follows:

As of Version 2.6, AspEncrypt is capable of importing such public keys via the CryptoContext method ImportPublicKey. This method accepts a single argument, a CryptoBlob object populated with the key data (but without the header and footer), and returns an instance of the CryptoKey object representing this public key.

The following code snippet imports the key shown above into a CryptoKey object:

As of Version 2.7, AspEncrypt is capable of exporting the public key information from a certificate via the property CryptoCert.PublicKeyInfo. This property returns an instance of the CryptoBlob object populated with the public-key data in a format used by many standards such as PEM, DomainKeys Identified Mail (DKIM) and others.