Using in MIME-conformant email messages

This toolkit produces enveloped-data and signed-data CMS objects which can be used in S/MIME v3 messages. To send the output as an email message you first need to wrap it in a MIME body, and to decrypt or verify an incoming message you need to extract the CMS object first.

Use the SMIME_Wrap function or Smime.Wrap method to create an S/MIME file from binary CMS signed-data, enveloped-data and compressed-data objects, and the SMIME_Extract function or Smime.Extract method to extract the body from an S/MIME file.

Sending an enveloped-data object

The output from the CMS_MakeEnvData or CMS_MakeEnvDataFromString function is a CMS object. This CMS object needs to be inserted into an application/pkcs7-mime MIME entity before being sent as an email message.

The CMS object is sent as an attachment to the email, usually with the name smime.p7m. If your email program allows you to tailor the headers, you should identify the Content-Type as application/pkcs7-mime; smime-type=enveloped-data. Most email programs convert the binary CMS object file into base64 encoding automatically. If not, you can use the PKI_CMS_FORMAT_BASE64 option to generate the output directly in base64 encoding.

Ann creates a message for Ben using the default option:

nRet = CMS_MakeEnvDataFromString("smime.p7m", _
    "Be in bar at 7 pm wearing a red rose", "ben.cer", "", 0, 0);

The output file smime.p7m will be in binary BER-encoded format. To send as an S/MIME email, you attach this file to your email message and you need to add the following headers:-

Date: Mon, 23 Feb 2004 12:00:52 +1100
From: alice@example.com
To: ben@example.com
Subject: Secret message
MIME-Version: 1.0
Content-Type: application/pkcs7-mime;
    smime-type=enveloped-data; id="smime.p7m"
Content-Transfer-Encoding: base64
Content-Description: attachment;filename=smime.p7m

MIAGCSqGSIb3DQEHA6CAMIACAQAxgZMwgZACAQAwOjA0MQswCQYDVQQGEwJBVTEV
...

When Bob receives the email, he can either:-

1. Rely on his email program correctly identifying the enveloped-data pkcs7-mime message and using his certificate and private key he previously loaded into the Windows certificate store to decrypt it; or
2. Save the attachment from the email to a file on his hard drive and decrypt it using the toolkit CMS_ReadEnvData function.

Identifying the Content-Type as application/pkcs7-mime and enveloped-data should ensure that the receiving email program correctly identifies the file as an encrypted email and treats it accordingly. This is optional, and you may find it more convenient to agree with your sending parties not to do this so you can just save the attached data file directly without getting involved in the "security" hoops that programs like Outlook Express will put you through.

If you can't save the attachment file directly from your email program, remember that email files are just simple text files (even though they may have a .EML extension) and can be edited using a simple text editor like NotePad. Open the email in your favorite text editor and do a cut-and-paste of the attachment data to another file.

Sending an signed-data object

There are two formats for signed messages for S/MIME:

1. S/MIME application/pkcs7-mime signed message
2. S/MIME multipart/signed message

The first format is simpler for our purposes. It consists of a signed-data CMS object which includes the signed content as created by the default CMS_MakeSigData or CMS_MakeSigDataFromString functions. The MIME headers are similar to the enveloped-data example above:-

MIME-Version: 1.0
To: ben@example.com
From: ann@example.com
Subject: Signed message
Date: Mon, 23 Feb 2004 12:00:52 +1100
Content-Type: application/pkcs7-mime; smime-type=signed-data;
    name=smime.p7m
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename=smime.p7m

MIIDmwYJKoZIhvcNAQcCoIIDjDCCA4gCAQExCTAHBgUrDgMCGjAtBgkqhkiG9w0BBwGgIA
QeDQpUaGlzIGlzIHNvbWUgc2FtcGxlIGNvbnRlbnQuoIIC4jCCAt4wggKdoAMCAQICAgDI
...

To read, just save the attachment to your hard drive and read the file with CMS_ReadSigData or CMS_ReadSigDataToString.

The second format, S/MIME multipart/signed, includes the actual content in the body of the email message and attaches a "detached signature" signed-data object identified as Content-Type: application/pkcs7-signature; name=smime.p7s in the MIME part header. This has the advantage that the signed content can be read directly in the email message, but you need a more sophisticated email program to create the final message. The detached signature CMS object can be created using the CMS_MakeDetachedSig function.

A typical multipart/signed message is:

MIME-Version: 1.0
To: ben@example.com
From: ann@example.com
Subject: Multi-part signed message
Date: Mon, 23 Feb 2004 12:00:52 +1100
Content-Type: multipart/signed;
    micalg=SHA1;
    boundary="----=_NextBoundry";
    protocol="application/pkcs7-signature"

This is a multi-part message in MIME format.

------=_NextBoundry

This is some sample content.
------=_NextBoundry
Content-Type: application/pkcs7-signature; name=smime.p7s
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename=smime.p7s

MIIDeQYJKoZIhvcNAQcCoIIDajCCA2YCAQExCTAHBgUrDgMCGjALBgkqhkiG9w0BBwGggg
LiMIIC3jCCAp2gAwIBAgICAMgwCQYHKoZIzjgEAzASMRAwDgYDVQQDEwdDYXJsRFNTMB4X
...

------=_NextBoundry--

You are strongly recommended to use quoted-printable encoding for the content part of the message to prevent the signed data being changed during transmission.

More information on S/MIME

For more details on how to insert your CMS objects into MIME bodies (honest, that's the term they use), please refer to S/MIME Version 3 Message Specification [SMIME-MSG] and Examples of S/MIME Messages [SMIME-EX]. Stallings also covers the topic well in Cryptography and Network Security [STAL].

[Contents] [Index]