HOWTO: ZSmime

Ng Pheng Siong <ngps@post1.com>
Copyright 2000-2001. All rights reserved.

What is ZSmime?

ZSmime enables Zope to generate S/MIME-signed and -encrypted messages.

This is useful where Zope accepts confidential information over the web, e.g., credit card numbers, Swiss bank account instructions, etc. Such information can be protected by ZSmime and relayed off-site immediately. This reduces the value of the information carried on-site and in turn reduces the impact of a successful attack against the site.

Even if the S/MIME-protected information remains on-site, it is now encrypted - this introduces additional cost in defeating the protection and may mitigate the effect of a successful site penetration.

What is S/MIME?

S/MIME - Secure Multipurpose Internet Mail Extensions [RFC 2311, RFC 2312] - provides a consistent way to send and receive secure MIME data. Based on the popular Internet MIME standard, S/MIME provides the following cryptographic security services for electronic messaging applications - authentication, message integrity and non-repudiation of origin (using digital signatures) and privacy and data security (using encryption).

Keys and Certificates

To create an S/MIME-signed message, ZSmime needs an RSA key pair (this consists of a public key and a private key) and an X.509 certificate of said public key.

To create an S/MIME-encrypted message, ZSmime needs the recipients' certificates.

To create an S/MIME-signed and -encrypted message, ZSmime first signs the data to create a signed message, then encrypts the signed message with the public keys of the recipients.

You may generate key pairs and obtain certificates by using a commercial certification authority service such as Verisign.

You can also do so using freely-available software. For the purpose of automated S/MIME message-generation by Zope, this approach is cheap and effective.

We now work through the process using OpenSSL. This assumes you have OpenSSL installed properly on your system.

• First, generate an X.509 certificate for the signer. When prompted for an email address, specify orderbot@example.dom.

  openssl req -newkey rsa:1024 -nodes -x509 -days 365 -out zsmime_sender.pem
  

  This command generates a 1024-bit RSA key pair, unencrypted, into the file privkey.pem; it also generates a self-signed X.509 certificate for the public key into the file zsmime_sender.pem. The certificate is valid for 365 days.

  To check the content of zsmime_sender.pem, execute the following:

  openssl x509 -noout -text -in zsmime_sender.pem
  

• Append privkey.pem to zsmime_sender.pem: (Cat-less users please improvise.)

  cat privkey.pem >> zsmime_sender.pem
  

• Next, generate a self-signed X.509 certificate for the recipient. Note that privkey.pem will be overwritten with the new key pair.

  openssl req -newkey rsa:1024 -nodes -x509 -days 365 -out zsmime_recip.pem
  

• Now transform the recipient's key and certificate into PKCS #12 format. The following command should be executed on one line. When prompted for "export password" and "verify password", just hit enter.

  openssl pkcs12 -export -in zsmime_recip.pem -inkey privkey.pem 
      -name "ZSmime" -out zsmime_recip.p12
  

GuardedFile

GuardedFile is a Zope product that eases the creation of protected Zope File objects called, unsurprisingly, GuardedFiles. A GuardedFile is a Zope File that is accessible by proxy only.

You can configure a Zope File to be like a GuardedFile through Zope's management interface. The GuardedFile product simply makes the process much more convenient.

Setting Up ZSmime

• Download and install M2Crypto. Make M2Crypto accessible to Zope.
  
  
• (Recommended) Download GuardedFile. Install the product by unpacking the package in Zope's top-level directory.
  
  
• Download and install ZSmime. Installation is as with GuardedFile.
  
  
• Start (or restart) Zope.
  
  
• Verify via Zope's Product Control Panel that GuardedFile and ZSmime have been installed correctly.
  
  

Using ZSmime

• Choose a folder to do your ZSmime work. Let's call this folder zsmime_work. All operations from now on are carried out in this folder.
  
  
• Upload your signer key/certificate bundle zsmime_sender.pem as a GuardedFile. Give it a Zope id signer.
  
  
• Upload your recipient certificate zsmime_recip.pem as a GuardedFile. Give it a Zope id recip.
  
  
• Create a DTML method like the following. Give it the Zope id smime.

  <pre>
  <dtml-smime signer="signer" recipients="recip">
  The quick brown <dtml-var id> fox.
  </dtml-smime>
  </pre>
  

• Go to the security tab of zsmime_work. You should see the proxy roles proxy_for_signer and proxy_for_recip; these roles were created when you uploaded the key and certificate files.
  
  
• Assign the proxy roles to smime. To do that in Zope 2.3.0 or later, you'll first need to assign your Zope user those proxy roles; you can do this by creating local roles in zsmime_work.
  
  
• Invoke smime as an anonymous user. Voila! You have an S/MIME-signed/encrypted message created by ZSmime. (Although you probably won't be able to make much sense of the output. ;-)
  
  
• Now try sending ZSmime's output via mail. Create a DTML method like the following. Make sure there is no blank line between "Subject" and the line following it. Substitute the proper hostnames and addresses for your site. Call your method smime_sender.

  <dtml-sendmail smtphost="smtp.example.dom">
  From: "The Order Bot" <orderbot@example.dom>
  To: "The Back Office" <backoffice@example.dom>
  Subject: Another sucker bought our hype.
  <dtml-smime signer="signer" recipients="recip">
  Widget Id: XXX-YYY-111-999
  Credit Card: 1234-5678-9012-3456
  (yada yada yada)
  </dtml-smime>
  </dtml-sendmail>
  

• Assign the proxy roles proxy_for_signer and proxy_for_recip to smime_sender.
  
  
• Invoke smime_sender. You should shortly receive a mail from The Order Bot to The Back Office regarding Another sucker.
  
  

Setting Up Netscape Messenger

Suppose The Back Office reads mail using Netscape Messenger. Here's how to import the signer's certificate and the recipient certificate and key into Messenger, in order to read S/MIME messages from The Order Bot:

• Start Messenger.
  
  
• Click on the (open) "lock" icon at the bottom left corner. This brings up the "Security Info" dialog box.
  
  
• Click on "Yours" under "Certificates".
  
  
• Select "Import a certificate", then pick zsmime_recip.p12 from the ensuing file selection dialog box.
  
  
• Then, you need to import zsmime_sender.pem as a CA certificate, so that Messenger will mark as "trusted" messages signed by zsmime_sender.pem's key. To do this, first create a DER encoding of zsmime_sender.pem:

  openssl x509 -inform pem -outform der -in zsmime_sender.pem -out zsmime_sender.der
  

• Next, install zsmime_sender.der into Navigator as a file of MIME type application/x-x509-ca-cert. You'll need to do this by clicking on zsmime_sender.der from a HTTP server, with the correct MIME type mapping. Follow the series of dialog boxes to accept zsmime_sender.der as a CA for certifying email users.
  
  

The Back Office is now able to decrypt and read The Order Bot's messages with Messenger. Messenger will indicate that each message is "encrypted and signed" via the "stamp" icon on the message window's top right corner.

Clicking on the "stamp" icon will bring you to the Security Info dialog box. Messenger informs you that the message is encrypted with 168-bit DES-EDE3-CBC and that it is digitally signed by the public key contained in the certificate zsmime_sender.pem.

Setting Up Microsoft Outlook

I do not know how to do this since I do not use Outlook. Information on this, as well as on other S/MIME tools, is gratefully accepted.

Security Discussion

ZSmime is designed to run autonomously; as such, the signer key cannot be passphrase-protected, since there may not be a human operator available to supply the passphrase. This means anyone who has access to the signer key can generate signatures with it.

(This practice causes debate in the security community periodically. Some argue that your operational procedure should be such that a person is always required (and available!) to supply passphrases and other necessary information. Ultimately, your security posture depends on the value of your web site and its threat model.)

The signer key should be single-purpose, i.e., its only use should be for your Zope application to generate S/MIME messages. It should also be reasonably well-handled from creation to installation on the Zope site. Within Zope, it is protected by Zope's permissions settings; as such, it should be installed as a GuardedFile.

ZSmime uses the signer key to provide message integrity and non-repudiation of origin.

It is possible to operate ZSmime with just recipient certificates; however, this means S/MIME messages you receive that are encrypted to those recipient certificates may not necessarily originate from your Zope site. (This mode of operation is not enabled.)

The recipient certificates should also be uploaded into Zope as GuardedFiles. This prevents an adversary from grabbing those certificates off your site and flooding you with S/MIME-encrypted mail.

You should upload the key and certificates over HTTPS.

Cryptography

ZSmime uses three-key triple-DES, as supported by "strong cryptography" versions of Netscape Messenger and Microsoft Outlook.

You can change the cryptographic algorithm to 40-bit RC2, as supported by "weak cryptography" versions of Messenger and Outlook, by modifying ZSmime's source code. This is not recommended.

ZSmime Licensing

ZSmime is published under the Zope Public Licence (ZPL). All rights reserved. Usual disclaimers apply.

Acknowledgements

Thanks to:

• The OpenSSL team for OpenSSL.
• Eric Young and Tim Hudson for SSLeay.
• Guido van Rossum and the Python community for Python.
• Digital Creations and the Zope community for Zope.
• Ng Pheng Siong for M2Crypto. (Me! ;-)