This is an API addition to Sun's JavaMail API which provides simple encryption and decryption of emails using S/MIME and/or OpenPGP. The intent is to provide a single, easy-to-use API for email clients that want to send and received encrypted email in either of the two most popular email encryption formats.
The JavaMail-Crypto API is released under the GNU Lesser General Public License (LGPL).
The JavaMail-Crypto API currently supports the following functionality:
There are currently two providers being worked on: an S/MIME provider based off of the BouncyCastle JCE and S/MIME implementation, and an OpenPGP provider based off of the Cryptix JCE and OpenPGP implementation. First drafts of both providers are also available on the SourceForge project page. You will need to download the appropriate JCE and implementation (S/MIME for BouncyCastle, OpenPGP for Cryptix) along with the javamail-crypto api library itself in order to make the providers work.
Quick note: if you try using the JavaMail-Crypto library and get the following exception:
java.lang.SecurityException: Unsupported keysize or algorithm parameters
It means that you need to download and install the Unlimited Strength Jurisdiction Policy Files for your JDK.
This API is intended to be an easy way for JavaMail developers to add encryption functionality to their applications. In addition, given the existence of two conflicting email encryption standards, this API tries to give a single, standard way of accessing encryption functionality that can be used for any encryption standard.
For example, encrypting a javax.mail.internet.MimeMessage
(newMessage), with the default javax.mail.Session
(mailSession), using S/MIME looks like this:
// get the S/MIME EncryptionUtilities
EncryptionUtils smimeUtils = EncryptionManager.getEncryptionUtils(EncryptionManager.SMIME);
// load the S/MIME keystore from the given file.
char[] smimePw = new String("hello world").toCharArray();
EncryptionKeyManager smimeKeyMgr = smimeUtils.createKeyManager();
smimeKeyMgr.loadPublicKeystore(new FileInputStream(new File("./id.p12")),
smimePw);
// get the S/MIME public key for encryption
java.security.Key smimeKey = smimeKeyMgr.getPublicKey("Eric's Key");
// encrypt the message
MimeMessage smimeEncryptedMsg = smimeUtils.encryptMessage(mailSession, newMessage, smimeKey);
While encrypting the same message using the OpenPGP provider is:
// get the PGP EncryptionUtilities
EncryptionUtils pgpUtils = EncryptionManager.getEncryptionUtils(EncryptionManager.PGP);
// load the PGP keystore from the given file.
EncryptionKeyManager pgpKeyMgr = pgpUtils.createKeyManager();
pgpKeyMgr.loadPublicKeystore(new FileInputStream(new File("./alice.pkr")), null);
// get the PGP public key for encryption
java.security.Key pgpKey = pgpKeyMgr.getPublicKey((String) pgpKeyMgr.publicKeyAliases().iterator().next());
// encrypt the message
MimeMessage pgpEncryptedMsg = pgpUtils.encryptMessage(mailSession, newMessage, pgpKey);
Full (simple) examples for signing and encrypting messages can be found
in these four files:
EncryptMessage.java,
ReadEncryptMessage.java,
SignMessage.java,
ReadSignedMessage.java,
as well as in the tests/ section of the CVS source.
At the moment, the only documentation available is the JavaDoc , plus the source code. But, given that this is just a development library, that (hopefully) should be sufficient for this point in the project.
The main API is available in a jarfile called javamail-crypto.jar
. There are currently two providers available: one for S/MIME using
the BouncyCastle provider, and
one for OpenPGP based on the Cryptix
provider.
For the BouncyCastle S/MIME provider, you will need the
bcprov-jdk14-122.jar (BouncyCastle JCE provider) and the
bcmail-jdk14-122.jar (BouncyCastle S/MIME implementation) files
in your CLASSPATH, along with the main javamail-crypto API file
and the javamail-crypto S/MIME provider (javamail-crypto-bouncycastle-smime.jar
).
The Cryptix OpenPGP provider requires the following files from Cryptix:
cryptix-jce-provider.jar, cryptix-openpgp-provider.jar,
cryptix-message-api.jar, and cryptix-pki-api.jar. You
also will need, of course, the main javamail-crypto API jar file and the
javamail-crypto PGP provider(javamail-crypto-cryptix-openpgp.jar).
Update: you can also download the cryptix provider from here, since their site seems to be down for the moment.
The javamail-crypto files are available from the main SourceForge page. The BouncyCastle and Cryptix files are available from their respective sites.
JavaMail-Crypto is officially in alpha right now, but it should be usable for simple encryption and decryption. It is currently being used to provide encryption support for Pooka.
Both the BouncyCastle S/MIME and Cryptix OpenPGP providers are functional, though I would hesitate to call either complete.
There is a mailing list set up at Sourceforge, which is probably the best place to send questions or comments. The SourceForge forums are also good places to go, or you can just email me directly (akp at users.sourceforge.net).
akp at sourceforge dot net
Last modified: February 9, 2004.