JCE taglib
cryptographic tag library & Expression Language functions for JavaServer Pages

1.0 Final Release, April-2004
© Copyright 2004 Gert Van Ham, open source LGPL license
Home: http://jcetaglib.sourceforge.net
Project: http://sourceforge.net/projects/jcetaglib/

  

This page is best viewed with ... no, not Internet Explorer but ... Mozilla!

Looking for the LightCrypto package (lightweight cryptographic library for HSQLDB & other uses)? You can find this subproject here
Looking for easy encryption for your non-jsp projects? Take a look at CryptoLib!

Table of contents

Introduction

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)
  • 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.
  • Legal issues

    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.

    License and credits

    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

  • JavaTM & JCETM 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)
  • Price

    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 :)

    About cryptography, JCE & other questions

    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.

    Download

    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

    JCE versus Lightweight API

    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

    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.

    Upgrade from 1.0 RC

    1.0 Final was tested with BouncyCastle JCE provider version 1.23

    Upgrade from beta 9

    1.0 RC needs BouncyCastle JCE provider version 1.21 or higher

    Upgrade from beta 6

    beta 9 needs BouncyCastle JCE provider version 1.18 or higher

    Upgrade from beta 5 or a prior version

    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
  • Installation

    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:

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

  • Using tags that take and return strings

    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"

    JSP 2.0 EL (Expression Language)

    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.

    Tag reference

  • In HTML format
  • Supported algorithms (from the BouncyCastle specifications file)

    Symmetric (Block)

    Modes:

    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:

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

    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:

    Signature Algorithms

    Schemes:

    Revision history

    revision history

    Java Docs

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

    Developer notes

  • 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
  • About the author

    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