In this installment, we’ll:

• Install some simple command-line tools for signing and encrypting email

• Get your sender key / certificate for signing

• Send a signed message via SparkPost, and look at the received message

• Optionally, get your recipient certificate for encryption

• Send a signed and encrypted message via SparkPost, and look at the received message

• Try a handy standalone tool “mimeshow” to look at email file internals.

OK – let’s get started!

1. Install the tools

The demonstration tools are in Github here, complete with installation instructions. You might notice the “build passing” logo – Travis and pytest automatically check the build status. Note these tools are not officially supported by SparkPost, but I’ve tried to make them robust and easy to use.

If you have some acquaintance with Python and pip, installation should feel pretty familiar. The Pipfile takes care of the external dependencies automatically for you. Once it’s done, you can check everything’s installed by running

./sparkpostSMIME.py -h

You should see the friendly help text. 

Next, we need to…

2. Get your sender key / certificate for signing

If you already have a key file for your sending identity, you can skip ahead. Otherwise here are two options to choose from:

a) Self-signed test key / certificate (not externally valid)



If you’re just testing, you can make “self signed” certificates and keys for an email address using the command line tool openssl on Linux,  following a procedure such as this one. At the end of that process, you’ll have a smime.p12  file. Rename this file to match your sending identity, including the @ sign, for example, alice@example.com.p12 .

or

b) Externally valid keys / certificates



If you want to get externally valid keys / certificates that enable you to sign, there’s a list of providers here. I found Comodo works well (free for non-commercial use), and it’s easier than the self-sign procedure above. Follow the sign-up process, receive your validation mail, and be sure to open the link in Firefox. Go to Firefox Preferences / Privacy and Security. Scroll to Certificates / View Certificates:

Select your certificate, and use the “Backup” option to save as a file in PKCS12 format (add the file extension .p12 to your filename) which carries the private key and the public certificate chain.

Provide a password to secure the .p12 file:

Generate separate public (.crt) and private (.pem) key files

Whether you used a) or b), you’ll now have a .p12 file for your sender identity. That’s a big step forward – grab a coffee now!

Now we need to generate separate public and private key files like this – substituting in your own email address for the example one. (Mac OSX and Linux):

openssl pkcs12 -in alice\@example.com.p12 -clcerts -nokeys -out alice\@example.com.crt openssl pkcs12 -in alice\@example.com.p12 -nocerts -nodes -out alice\@example.com.pem

You’ll need to enter the password you provided earlier. Note those backslashes \ are used to escape the @ sign – not separating the names of a directory path (that’s a forward-slash / on Mac OSX and Linux).

If you’re using Windows, there are openssl implementations available such as the MINGW64 one built into the Git command-line tools, but I found it tended to just lock up. You’ll probably find it easier and quicker to do this on Linux and then copy your files over. Those same Git tools for Windows come with a nice ssh client you can use to login to a Linux box, such as an Amazon EC2 instance.

2.1 Signing a message

There’s already a dummy key/cert and email source file in the tests directory for alice@example.com, so you can get some output even before you have your own keys. Just type the following:

cd tests ../sparkpostSMIME.py example_email1.eml --sign

And you’ll get:

To: Bob <bob@example.com> From: Alice <alice@example.com> Subject: A message MIME-Version: 1.0 Content-Type: application/x-pkcs7-mime; smime-type=signed-data; name="smime.p7m" Content-Transfer-Encoding: base64 Content-Disposition: attachment; filename="smime.p7m" MIIKXAYJKoZIhvcNAQcCoIIKTTCCCkkCAQExDzANBglghkgBZQMEAgEFADCCAQoGCSqGSIb3DQEH AaCB/ASB+VRvOiBCb2IgPGJvYkBleGFtcGxlLmNvbT4NCkZyb206IEFsaWNlIDxhbGljZUBleGFt : :

You can’t actually send emails from example.com via SparkPost unless you own that domain, so the next step is to use your own key and send a signed message from your own domain.

3. Send a signed message via SparkPost

Now let’s use a real sending domain, set up as per the SparkPost New User Guide. We have the sender certificate and key files in the current directory:

steve@thetucks.com.crt steve@thetucks.com.pem

The file tests/declaration.eml is included in the project. It’s just a text file, so you can customize the From: address to suit your own sending domain and the To: address to suit your test recipient. The beginning of the file looks like this:

To: Bob <bob.lumreeker@gmail.com> From: Steve <steve@thetucks.com> Subject: Here is our declaration MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit Content-Language: en-GB When in the Course of human events it becomes necessary …

Set your API key:

export SPARKPOST_API_KEY=<<Put your API key here>>

Send the email:

./sparkpostSMIME.py tests/declaration.eml --sign --send_api

You will see:

Opened connection to https://api.sparkpost.com/api/v1 Sending tests/declaration.eml From: Steve <steve@thetucks.com> To: Bob  <bob.lumreeker@gmail.com> OK - in 1.15 seconds

A second or so later, the email arrives in Bob’s inbox. Thunderbird displays it with a red dot on the envelope, indicating a valid sender signature.

Success! Finish that coffee, you’ve earned it. If you are having trouble, check your From: address in the email file matches the name of your .crt and .pem files.

4. Encrypting messages

To encrypt a message, you need your recipient’s public key in certificate form. This is a text file which looks like this:

Bag Attributes   friendlyName: s COMODO CA Limited ID #2   localKeyID: 32 84 AB 9C 56 5C 80 C6 89 4D 40 46 DD D4 7C 71 E8 CD ED C1 subject=/emailAddress=bob.lumreeker@gmail.com issuer=/C=GB/ST=Greater Manchester/L=Salford/O=COMODO CA Limited/CN=COMODO RSA Client Authentication and Secure Email CA -----BEGIN CERTIFICATE----- looks like random characters in here -----END CERTIFICATE-----

There’s a dummy recipient certificate for bob@example.com in the tests directory, so you can practice with it before you have a real certificate:

cd tests ../sparkpostSMIME.py example_email1.eml --sign --encrypt

You’ll see:

To: Bob <bob@example.com> From: Alice <alice@example.com> Subject: A message MIME-Version: 1.0 Content-Type: application/pkcs7-mime; smime-type=enveloped-data; name=smime.p7m Content-Transfer-Encoding: base64 Content-Disposition: attachment; filename=smime.p7m MIIRwQYJKoZIhvcNAQcDoIIRsjCCEa4CAQAxggKlMIICoQIBADCBijCBhDELMAkG :

You’ll notice the length of output is quite a bit longer than with an encrypted message because it carries a lot of extra information as well as the scrambled message itself.

4.1 Sending an encrypted, signed message through SparkPost

Let’s send an encrypted message to a real email address. You can follow the same process as before (self-signed or a provider such as Comodo) to get a public key / certificate for your own recipient addresses. You only need the .crt file – the recipient does not ever need to give you their private key (.p12 and .pem files).

I have the file bob.lumreeker@gmail.com.crt for my intended recipient – matching the From: address in my file.

Here’s the command to send:

./sparkpostSMIME.py tests/declaration.eml --sign --encrypt --send_api

I see:

Opened connection to https://api.sparkpost.com/api/v1 Sending tests/declaration.eml From: Steve <steve@thetucks.com> To: Bob <bob.lumreeker@gmail.com> OK - in 1.168 seconds

The mail shows up in Thunderbird with the “red dot” signature icon and the “padlock” encrypted icon.

You can send complex HTML-based email with links and images just as easily, such as the one shown in Part 1. Some clients such as Thunderbird ask for permission to display external links and images within encrypted S/MIME messages, but signed-only messages display well in clients including Thunderbird and Gmail:

Note the drop-down shows “Verified email address”.

Further thoughts & things to be aware of

This tool takes a super-simple approach to pulling in the necessary keys – it just looks for named files in the current directory. More complex arrangements, such as holding all keys in a database could easily be added, but I wanted the code to be as simple as possible.

You can include other recipients with Cc: and Bcc: and they will be delivered; this could be useful for archival purposes. Signed messages are received and can be displayed by other recipients complete with the signature. The tool strips the Bcc: header from the delivered message (like a desktop mail client would do).

To ensure that messages pass through SparkPost unchanged (which could break signing), the tool sets API options for “transactional” mailing, with open and click tracking disabled.

If you use encryption, bear in mind that the tool picks up the single To: address for that. The other recipients can decode the message body only if they have the To: recipient private key. If you’re just using secondary recipients as a record of deliveries made, for example, that may be OK anyway.

Signed, sealed delivered…I’m yours

That’s our quick overview of how to sign, seal and deliver S/MIME messages through SparkPost. Quick reminder: the demo project is in Github here, I’ve tried to make it easy to install and use.

Bonus feature: displaying MIME parts with “mimeshow”

RFC822 MIME multipart file internals are quite complex to read for humans. The project includes a standalone tool to make this easier, called mimeshow.

This takes any email files you have (not just S/MIME ones) and shows the internal structure. Here’s an example:

./mimeshow.py testcases/img_and_attachment.eml

You’ll see:



To Bob <bob.lumreeker@gmail.com>

From Steve <steve@thetucks.com> 

Subject Testing attachments etc 

MIME-Version 1.0

Content-Type multipart/mixed; boundary="------------7D48652042860D0098C65210"

Content-Language en-GB



 Content-Type multipart/alternative; boundary="------------58C0BF87598336550D70EB95" 



   Content-Type text/plain; charset=utf-8; format=flowed

   Content-Transfer-Encoding 7bit



   Content-Transfer-Encoding quoted-printable 

   Content-Type text/html; charset="utf-8"



 Content-Type application/pdf; name="sparkpost-datasheet-tam-technical-account-management.pdf" 

 Content-Transfer-Encoding base64

 Content-Disposition attachment; filename="sparkpost-datasheet-tam-technical-account-management.pdf"

You can also use as a filter to give a human-readable summary of sparkpostSMIME  output:

./sparkpostSMIME.py tests/declaration.eml --sign --encrypt | ./mimeshow.py

You’ll see:

To Bob <bob.lumreeker@gmail.com> 

From Steve <steve@thetucks.com>

Subject Here is our declaration 

Content-Language en-GB

MIME-Version 1.0

Content-Type application/pkcs7-mime; smime-type=enveloped-data; name=smime.p7m

Content-Transfer-Encoding base64

Content-Disposition attachment; filename=smime.p7m

Finally…

To recap – we’ve installed some simple command-line tools for signing and encrypting email (the Github repo is here, complete with installation instructions).

We got our sender key / certificate for signing, and sent a signed message via SparkPost. We got a recipient certificate for encryption, then sent a signed and encrypted message via SparkPost.

Lastly, we tried the handy standalone tool “mimeshow” to look at email file internals.

That’s it for now! See you soon!.