• Introduction
• Legal Issues
• License and credits
• Price
• About cryptography, JCE & other questions
• Download
• JCE versus Lightweight API
• CryptoLib
• Upgrade from a previous version
• Installation
• Using tags that take and return strings
• JSP 2.0 EL (Expression Language)
• Tag reference
• Supported algorithms (from the BouncyCastle specifications file)
• Revision history
• Java docs
• Developer notes
• About the author

JCE taglib is a set of Open Source JSP tags and expression language EL functions (J2EE 1.4/JSP 2.0), communicating with Sun's JCE (Java Cryptographic Extensions) library to bring high-level strong encryption to your JSP applications. Classes are organized in such way that they can also be used for other non-JSP projects.

Features:

Encrypt/decrypt text and files with secret keys, PBE (password-based) or public/private key (X.509 certificates)

Generates message digests (hash) from text and files

Generates HMAC (message authentication codes) from text and files

Generates and verifies SIG (signatures) from text and files

High-level hybrid encryption/decryption (check the FAQ)

High-level tag to create form digests that prevent unauthorized URL/form parameter manipulation

Provides different popular strong encryption algorithms (DES, AES, Rijndael, Blowfish, Twofish, Serpent, CAST, RC4 stream cipher, RC6, IDEA, ...) in variable bitsizes (64,128,192,256,448,...) & modes/paddings

Generating & verify X.509 v3 certificates / CRL (Certificate Revocation List)

• RSA/DSA algorithms with 512, 1024 or 2048 bit keylength
• self-signed (CA), intermediate and user certificates
• for SSL server and client authentication, S/MIME, signatures, encryption, Code and object signing, ...
• for use with Internet Explorer, Netscape, Mozilla, IIS, Apache and other X.509 enabled products
• PKCS#12 keystores or PEM strings/files
• Generating X.509 certificates (manual or auto-installed) from PKCS#10 (IE and other) and Netscape/Mozilla requests

New! JSP 2.0 EL (Expression Language) functions available (J2EE 1.4)

Open Source

Written entirely in Java

Uses Sun's JCE (Java Cryptography Extensions) 1.2.2 (integrated in Java 2 SDK, Standard Edition, v 1.4, optional package with v. 1.3)

Works with BouncyCastle.org JCE cleanroom provider.

This package does not contain the provider & "cleanroom implementation" of JCE 1.2.2 by BouncyCastle. It must be downloaded separately. This package does not contain any cryptographic code/algorithms and thus it is not bound to any cryptographic export regulations.

However, to use this package, you will have to download this provider so you will be bound to any of your country's cryptographic import regulation (check the CryptoLaw document). The author(s), nor any of the organisations/people listed in the credits do NOT take any responsibility in this matter. By downloading and/or using JCE taglib you agree with these terms.

This software is covered under the GNU Lesser General Public License and is copyrighted by Gert Van Ham. It can be used, copied, distributed & altered freely. However, a donation is always welcome.

Disclaimer

COVERED CODE IS PROVIDED UNDER THIS LICENSE ON AN "AS IS'' BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT THE COVERED CODE IS FREE OF DEFECTS, MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE COVERED CODE IS WITH YOU. SHOULD ANY COVERED CODE PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL DEVELOPER OR ANY OTHER CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS LICENSE. NO USE OF ANY COVERED CODE IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER.

Credits

Java^TM & JCE^TM are products licensed by Sun

The JCE provider is licensed by the Legion of the BouncyCastle

Lots of code (for using X.509 certificates) is re-used from the EJB CA project.

Tools used

Tomcat (http://jakarta.apache.org/tomcat)

IntelliJ IDEA 4 (http://www.intellij.com)

Keyman for testing certificates & keystores (http://www.alphaworks.ibm.com/tech/keyman).

OpenSSL for testing certificates & keystores (http://www.openssl.org)

Xdoclet for automatically generating TLD file (http://xdoclet.sourceforge.net)

TLDDoc to generate reference docs from the TLD file (http://developers.sun.com/dev/coolstuff/tlddoc)

Using and deploying this software is free of charge, however, if you are using this software in a commercial product or in a production environment inside a governmental/commercial organisation you are urged to support my efforts by donating with PayPal. I'll apply some voodoo on you if you don't :)

If you are familiar with cryptography, JCE & security issues you can go further, but starters are recommended to read the FREQUENTLY ASKED QUESTIONS document first. It contains some links and basic cryptographic information.

The latest version can always be found on http://sourceforge.net/projects/jcetaglib/

Don't forget that this package DOES NOT INCLUDE the JCE provider and that it must be downloaded separately from Bouncycastle.org

Sun Microsystems did a great job when designing JCE because it hides cryptographic complexity. However, JCE is big and resource/memory hungry. In some situations, such as designing secure apps for mobiles & PDA's, this could be a huge problem. Fortunately, the BouncyCastle organisation have also a lightweight implementation for all your projects where JCE is not suitable for the job. Keep using JCE for all your server-side applications.

Check out my subproject called LightCrypto on http://jcetaglib.sourceforge.net/lightcrypto.

CryptoLib is basically the same as the main package (equal code), but is stripped down and repackaged without the jsp-specific code so it can be used easily for your non-JSP projects (JMS, EJB, etc...).

Download CryptoLib at the project page.

1.0 Final was tested with BouncyCastle JCE provider version 1.23

1.0 RC needs BouncyCastle JCE provider version 1.21 or higher

beta 9 needs BouncyCastle JCE provider version 1.18 or higher

Starting from beta 6, the symmetric key & PBE encryption has been re-written:

symmetric keystore is now passphrase-protected

symmetric keystore is now encrypted (Twofish)

symmetric keystore does not contain the IV (Initialization Vectors) anymore

The IV is now stored together with the encrypted file/string. In previous versions it was stored within the keystore

The PBE salt is now random and stored inside each encrypted file/string. In previous versions it was fixed.

Changed passwords and text from Strings to StringBuffers

This has impact on the following:

String or files encrypted with a version prior to beta 6 are incompatible with beta 6 or later

Symmetric keys generated with a version prior to beta 6 are incompatible with beta 6 or later

Your code needs some changes (see FAQ here and here )

Perform the following steps to upgrade to a new version:

1. Decrypt all strings/files encrypted with the "encrypt"/"fileencrypt" tag
2. Decrypt all strings/files encrypted with the "pbeencrypt"/"pbefileencrypt" tag
3. Upgrade to the new version
4. Re-generate symmetric keys (with passphrase now)
5. Change your code (see FAQ here)
6. Encrypt all strings/files again

Before you can use this package you will have to download the BouncyCastle provider and "cleanroom implementation". Make sure you download "Clean room JCE and provider" package (jar file) for your JVM. This jar contain strong encryption, so check your country's cryptographic import restrictions (CryptoLaw document). Again, the author does NOT take any responsibility in this matter.

Open the file "java.security" under [jvm]\runtime\jre\lib\security and add the following line to the file: "security.provider.3=org.bouncycastle.jce.provider.BouncyCastleProvider" (without "). You can put it under "security.provider.2=com.sun.rsajca.Provider". Save the file.

Copy the tag library descriptor file (dist/lib/jce.tld) to the /WEB-INF subdirectory of your web application.

Copy the tag library JAR file (dist/lib/jcetaglib.jar) to the /WEB-INF/lib subdirectory of your web application.

Copy the BouncyCastle JCE JAR file (e.g. jce-jdk13-121.jar) to the /WEB-INF/lib subdirectory of your web application.

Add a <taglib> element to your web application deployment descriptor in /WEB-INF/web.xml like this:

<taglib>
  <taglib-uri>http://jcetaglib.sourceforge.net</taglib-uri>
  <taglib-location>/WEB-INF/jce.tld</taglib-location>
</taglib>

To use the tags from this library in your JSP pages, add the following directive at the top of each page:

<%@ taglib uri="http://jcetaglib.sourceforge.net" prefix="jce" %>

where "jce" is the tag name prefix you wish to use for tags from this library. You can change this value to any prefix you like.

Note:

If you get unexpected errors, the cause is most likely that you have problems getting the BouncyCastle provider to work with your environment. Check or try the following:

• Check if you have downloaded the correct provider for your JVM
• Try to set BouncyCastle as default security provider ("security.provider.1" instead of "security.provider.3")
• Try to put the BouncyCastle JAR in your "<tomcat install dir>/server/lib" folder (don't forget to reload/restart Tomcat)
• Try to put the BouncyCastle JAR in your "<JVM install dir>/jre/lib/ext" folder

If none of the above helps, contact the BouncyCastle Community through the mailinglist.

The tags are loosely based on JSTL (JSP Standard Tag Library) 1.0 Apache Jakarta implementation and work more or less the same. You can specify scoped variables or use tag body to send/return strings. Some examples:

<jce:pbeencrypt ...>please encrypt this text</jce:pbeencrypt>

Encrypts the text and directly print the result

<jce:pbeencrypt value="please encrypt this text" .../>

Same as above

<jce:pbeencrypt var="mySess" scope="session" ...>please encrypt this text</jce:pbeencrypt>

Encrypts the text and store it in session variable "mySess"

<jce:pbeencrypt var="myApp" scope="application" value="please encrypt this text" .../>

Encrypts the text and store it in application variable "myApp"

JCE taglib 1.0 final has some EL functions for basic encryption.

The Expression Language, inspired by both ECMAScript and the XPath expression languages, provides a way to simplify expressions in JSP. It is a simple language that is based on available namespace (the PageContext attributes), nested properties and accessors to collections, operators - arithmetic, relational and logical, extensible functions mapping into static methods in Java classes, and a set of implicit objects. It was first introduced in JSTL 1.0.

EL provides the ability to use run-time expressions outside JSP scripting elements. Scripting elements are the elements in a page that can be used to embed Java code in the JSP file. They are commonly used for object manipulation and performing computation that affects the generated content. JSP 2.0 adds EL expressions as a scripting element. JSP 2.0 is supported by Tomcat 5 and is included in the J2EE 1.4 final specifications.

Some examples:

${jce:digest("mytext","MD5")}

<c:set var="mysessionvar" scope="session" value="mytext"/>
<c:out value='${jce:pbeencrypt(sessionScope.mysessionvar,"mypassword",null)}'/>

The encryption EL functions (including javadoc) can be found in the "net.sourceforge.jcetaglib.jsp20.ELFunctions" class. More samples can be found in the sample application.

In HTML format

Symmetric (Block)

Modes:

• ECB

• CBC

• OFB(n)

• CFB(n)

Where (n) is a multiple of 8 that gives the blocksize in bits, eg, OFB8. Note that OFB and CFB mode can be used with plain text that is not an exact multiple of the block size if NoPadding has been specified.

Padding Schemes:

• No padding

• PKCS5/7

• ISO10126/ISO10126-2

• X9.23/X923

• CTS

When placed together this gives a specification for an algorithm as;

• DES/CBC/WithCTS

• DES/CBC/X9.23Padding

• DES/OFB8/NoPadding

• IDEA/CBC/ISO10126Padding

• SKIPJACK/ECB/PKCS7Padding

Note: default key sizes are in bold.

Name	KeySizes (in bits)	Block Size	Notes
AES	0 .. 256 (192)	128 bit
AESWrap	0 .. 256 (192)	128 bit	A FIPS AES key wrapper
Blowfish	0 .. 448 (448)	64 bit
CAST5	0 .. 128(128)	64 bit
CAST6	0 .. 256(256)	128 bit
DES	64	64 bit
DESede	128, 192	64 bit
IDEA	128 (128)	64 bit
RC2	0 .. 1024 (128)	64 bit
RC5	0 .. 128 (128)	64 bit	Uses a 32 bit word
RC5-64	0 .. 256 (256)	128 bit	Uses a 64 bit word
RC6	0 .. 256 (128)	128 bit
Rijndael	0 .. 256 (192)	128 bit
Skipjack	0 .. 128 (128)	64 bit
Twofish	128, 192, 256 (256)	128 bit
Serpent	128, 192, 256 (256)	128 bit

PBE

Name	Key Generation Scheme	Key Length (in bits)
PBEWithMD5AndDES	PKCS5 Scheme 1	64
PBEWithMD5AndRC2	PKCS5 Scheme 1	128
PBEWithSHA1AndDES	PKCS5 Scheme 1	64
PBEWithSHA1AndRC2	PKCS5 Scheme 1	128
PBEWithSHAAnd2-KeyTripleDES-CBC	PKCS12	128
PBEWithSHAAnd3-KeyTripleDES-CBC	PKCS12	192
PBEWithSHAAnd128BitRC2-CBC	PKCS12	128
PBEWithSHAAnd40BitRC2-CBC	PKCS12	40
PBEWithSHAAnd128BitRC4	PKCS12	128
PBEWithSHAAnd40BitRC4	PKCS12	40
PBEWithSHAAndTwofish-CBC	PKCS12	256
PBEWithSHAAndIDEA-CBC	PKCS12	128

Digest

Name	Output (in bits)	Notes
MD2	128
MD4	128
MD5	128
RipeMD128	128	basic RipeMD
RipeMD160	160	enhanced version of RipeMD
SHA1	160
SHA-256	256	Draft version from FIPS 180-2
SHA-384	384	Draft version from FIPS 180-2
SHA-512	512	Draft version from FIPS 180-2
Tiger	192

MAC

Name	Output (in bits)	Notes
Any MAC based on a block cipher, CBC (the default) and CFB modes.	half the cipher's block size (usually 32 bits)
MD2/HMac	128
MD4/HMac	128
MD5/HMac	128
RipeMD128/HMac	128
RipeMD160/HMac	160
SHA1/HMac	160
Tiger/HMac	192

Examples:

• DESMac

• DESMac/CFB8

• DESedeMac

• DESedeMac/CFB8

• SKIPJACKMac

• SKIPJACKMac/CFB8

• IDEAMac

• IDEAMac/CFB8

• RC2Mac

• RC2Mac/CFB8

• RC5Mac

• RC5Mac/CFB8

Signature Algorithms

Schemes:

• MD2withRSA

• MD5withRSA

• SHA1withRSA

• RIPEMD160withRSA

• SHA1withDSA

• SHA1withECDSA

revision history

Java programmers can view the java class documentation for this tag library as javadocs.

A PKCS#12 keystore is the safest and most recommended way to store your certificates and private keys. You can use the BouncyCastle provider together with the Java Keytool to generate a PKCS#12 keystore or the OpenSSL binaries (http://www.openssl.org)

Before you start coding your own CA (Certification Authority) please note that there are already some fine open source solutions such as EJB CA and Open CA

Gert Van Ham is since '94 working as a Database & Intranet Consultant for Cronos NV where he was the first member and founder of the xNet department. Now, this department has over 50 consultants designing & implementing top-of-the-bill Internet technology for Top 100 multinational & local companies, which put Cronos in a number 1 position on the Belgian market of technical Internet/Intranet Consultancy.

As a pioneer in Internet & Intranet database development, he successfully deployed and administered multiple large Intranet sites for industrial & governmental organizations using Oracle, Netscape & Cold Fusion web technology. He focusses now on security, middleware and the J2EE platform.

E-mail: hamgert@users.sourceforge.net
Personal homepage: http://users.pandora.be/gert.van.ham