ABA JCE Provider Reference

$Date: 1999/02/19 05:20:48 $
$Revision: 1.3 $

The ABA JCE/Provider

The ABA JCE/Provider is both a clean room implementation of the Java Cryptography Extension and a JCE/JCA Provider that implements a number of security and cryptographic algorithms. The JCE is a standard API written by Sun to enable applications support for cryptography, it expands on the Java Cryptography Architecture (JCA) to provide mechanisms for encryption. Sun's implementation of the JCE is export controlled from the U.S.. In the JCA a provider refers to a package or set of packages that implement one or more cryptography services.

Theoretically our JCE implementation should work with any provider and our provider with any JCE implementation, however the JCE is still an evolving API and it is targeted at JDK1.2 and so has not received the extensive testing that a more mature API may have.

This document covers the specific algorithms implemented and their capabilities.

1.0 Working with Different JDK versions

Since the JCE is a JDK1.2 API it makes use of the JDK1.2 platform which includes classes that are not available in previous JDK versions. To make the JCE and provider available under previous versions of the JDK we have implemented some of the JDK1.2 platform in JDK1.0 and JDK1.1. Unfortunately this leads to three separate versions of our JCE and provider.

1.1 Java platform differences

The ABA JCE/Provider is designed to provide a JCE interface on all three Java platform revisions, however due to the differences in these revisions (and other factors such as performance) there is a different class library for each of these revisions.

The major visible difference to an application developer is the different locations of some classes. Generally when a class is required for the JCE implementation and does not exist under the JDK 1.0 or 1.1 platform we have provided that class in an ABA package. For instance the java.security.KeyFactory class does not exist in JDK 1.1, in our JCE the au.net.aba.security.KeyFactory class takes its place.

Other than differences in the classes provided there are some functionality between the JDK 1.0 version and the JDK 1.1/1.2 versions. The JDK 1.0 version does not support;

Included in the JDK1.0 package is a clean room implementation of the Java serialisation mechanism, however only the Externalizable interface is supported (so the writeObject() and readObject() methods must be provided). Additionally for the serialisation to work between JDK 1.0 and any other revision the class must define the serialVersionUID as 1 (the JDK 1.0 version creates all objects with a version of 1).

1.2 Getting Started

The first thing you will need to do is configure your development environment to include the ABA JCE. Since all development environments are different I have not attempted to explain the specifics on how to set your CLASSPATH, if you need that information you will have to consult the documentation included with your development environment.

1.2.1 JDK 1.0

Getting started under 1.0 is as simple as including the correct zip file in your CLASSPATH. In the ABA/JCE release the 1.0 library is located as jce-aba-1.0/lib-1.0/jce.zip. There is no need to modify the java.security properties file or use the Security.addProvider() interface in your application. The various factory classes in the 1.0 JCE will use the ABA provider regardless of the provider parameter.

1.2.2 JDK 1.1/JDK 1.2

Under JDK 1.1 or 1.2 you will need to include the correct zip file in your classpath. For 1.1 it will be jce-aba-1.0/lib-1.1/jce.zip and for 1.2 jce-aba-1.0/lib-1.2/jce.zip. Secondly you will need to add the ABA provider to the provider list. There are two mechanisms to do so;

  1. Modify the java.security properties file
  2. Use the Security.addProvider() interface
By modifying the java.security properties file you can permanently add the ABA provider to your runtime, every application you run using that runtime will have access to the ABA Provider. If you use the Security.addProvider() interface each application will need to include the following code in order to access the ABA Provider;

java.Security.addProvider(new au.net.aba.crypto.provider.ABAProvider());

If you are modifying your java.security properties file ($JAVA_HOME/lib/security/java.security), simply edit that file and add a new entry for the ABA provider;

security.provider.2=au.net.aba.crypto.provider.ABAProvider

The properties file has additional information regarding how you can configure your system.

1.3 Compatibility Issues

At present there are a number of differences between the ABA JCE and the Sun JCE. The impact to you application should be minimal, eventually however, these should disappear.

Algorithm lookups do not support aliases, this is true for the Cipher, KeyAgreement, KeyGenerator, Mac, and SecretKeyFactory classes. Currently with the Sun JCE if you have a provider with the following properties;

	Cipher.RSA = crypto.provider.RSA
	Alg.Alias.Cipher.Foo = RSA

And an application makes a request for the "Foo" Cipher it would return the "RSA" Cipher. The ABA JCE will not do the alias transform and will throw a NoSuchAlgorithmException exception.

When requesting a Cipher transformation of "DES/CBC/PKCS5Padding" the Sun JCE will search for the following implementations (in this order);

	DES/CBC/PKCS5Padding
	DES/CBC
	DES//PKCS5Padding
	DES

The ABA JCE will search for the full transformation, and then just the algorithm (ie "DES/CBC/PKCS5Padding" then "DES").

2.0 Cipher Engines

The following table lists the currently implemented encryption algorithms that are accessible through the javax.crypto.Cipher interface:

Cipher Name Key Size (bits) Modes Padding
Blowfish 128-448 ECB/CBC PKCS5Padding/NoPadding
DES 64 ECB/CBC PKCS5Padding/NoPadding
DESede 168 ECB/CBC PKCS5Padding/NoPadding
IDEA 128 ECB/CBC PKCS5Padding/NoPadding
RC4 40-128    
RSA 96-4096 ECB PKCS1Padding/NoPadding
Twofish 128-256 ECB/CBC PKCS7Padding/NoPadding

Additionally the following password based encryption (PBE) algorithms are available through the javax.crypto.Cipher interface:

2.1 Blowfish

This algorithm is is a 64-bit block cipher with a variable-length key. The algorithm is described in Applied Cryptography by Bruce Schneier.

The algorithm will accept any key size up to 448 bits and can operate in ECB or CBC mode.

The Cipher will accept either a au.net.aba.crypto.provider.BlowfishKey or a javax.crypto.spec.SecretKeySpec.

When operating in CBC mode the Cipher may be initialised with a javax.crypto.spec.IvParameterSpec or a au.net.aba.crypto.spec.InlineIvParameterSpec. This engine will not return these parameters as java.security.AlgorithmParameters however.

2.2 DES

This algorithm is a 64-bit block cipher with a 64-bit key, however the effective key size is only 56-bit as 8 bits of the key are used for parity bits. The algorithm described in FIPS PUB 46-2 (see http://www.itl.nist.gov/div897/pubs/fip46-2.htm).

The Cipher will accept either a au.net.aba.crypto.provider.DESKey or a javax.crypto.spec.SecretKeySpec. There are a number of weak DES keys, the javax.crypto.spec.DESKeySpec.isWeak() method may be used to check for weak keys.

When operating in CBC mode the Cipher may be initialised with a javax.crypto.spec.IvParameterSpec or a au.net.aba.crypto.spec.InlineIvParameterSpec. This engine will not return these parameters as java.security.AlgorithmParameters however.

2.3 DESede

This algorithm, known as triple-DES, is a 64-bit block cipher with a 168-bit key. This algorithm works by splitting the 168-bit key into three 64-bit keys and then applying the basic DES cipher, firstly in the encrypt mode, secondly in the decrypt mode and finally in the encrypt mode. The algorithm is described in ANSI X9.17.

The Cipher will accept either a au.net.aba.crypto.provider.DESedeKey or a javax.crypto.spec.SecretKeySpec.

When operating in CBC mode the Cipher may be initialised with a javax.crypto.spec.IvParameterSpec or a au.net.aba.crypto.spec.InlineIvParameterSpec. This engine will not return these parameters as java.security.AlgorithmParameters however.

2.4 IDEA

This algorithm is a 64-bit block cipher with a 128-bit key. This algorithm is patented in Europe and the United States by Ascom-Tech Ag (see http://www.ascom.com/ however no license fee is required for non-commercial use. A description of the cipher may be found at http://www.ascom.ch/infosec/idea/techspecs.html.

The Cipher will accept either a au.net.aba.crypto.provider.IDEAKey or a javax.crypto.spec.SecretKeySpec.

When operating in CBC mode the Cipher may be initialised with a javax.crypto.spec.IvParameterSpec or a au.net.aba.crypto.spec.InlineIvParameterSpec. This engine will not return these parameters as java.security.AlgorithmParameters however.

2.5 RC4

This algorithm is a stream cipher with a variable length key usually 40-bit or 128-bit. RC4 is a trademarked by RSA Data Security. A description of the algorithm may be found in Applied Cryptography by Bruce Schneier.

The algorithm will accept either a au.net.aba.crypto.provider.RC4Key or a javax.crypto.spec.SecretKeySpec for initialisation and does not support any algorithm parameters.

2.6 RSA

This algorithm is a block cipher with a variable length key whose block size is equal to the key size. RSA is patented in the United States by RSA Data Security. A description of the algorithm may be found in PKCS-1, see http://www.rsa.com/rsalabs/pubs/PKCS/html/pkcs-1.html.

The algorithm will accept any RSA Key that implements either java.security.interface.RSAPublicKey or java.security.interface.RSAPrivateKey. The key must be at least 96 bits, the maximum is limited by processing power (however 1024-bit or 2048-bit keys are the norm).

2.7 Twofish

This algorithm is a 128-bit block cipher with a variable-sized key. Twofish has been submitted to the AES. A description of the algorithm may be found at http://www.counterpane.com/twofish.html.

The Cipher will accept either a au.net.aba.crypto.provider.TwofishKey or a javax.crypto.spec.SecretKeySpec.

When operating in CBC mode the Cipher may be initialised with a javax.crypto.spec.IvParameterSpec or a au.net.aba.crypto.spec.InlineIvParameterSpec. This engine will not return these parameters as java.security.AlgorithmParameters however.

2.8 PBEWithMD5AndDES

This algorithm is a 64-bit block cipher whose key is derived from a variable length ASCII password. Data is encrypted using DES in CBC mode and the DES key is generated using the supplied password and the MD5 algorithm. This algorithm is described in PKCS#5, see (http://www.rsa.com/rsalabs/pubs/PKCS/html/pkcs-5.html.

The Cipher will accept a au.net.aba.crypto.provider.PBEKey and a javax.crypto.spec.PBEKeySpec during initialisation.

This engine does not support the Cipher.getParameters() method.

2.9 PBEWithSHA1And128BitRC4

This algorithm is a stream cipher whose key is derived from a variable length Unicode password. Data is encrypted using RC4 with the key generated using the supplied password and the SHA1 algorithm. This algorithm is described in PKCS#12, see (http://www.rsa.com/rsalabs/pubs/PKCS/html/pkcs-5.html.

The Cipher will accept a au.net.aba.crypto.provider.PBEKey and a javax.crypto.spec.PBEKeySpec during initialisation.

This engine does not support the Cipher.getParameters() method.

3.0 Message Digest Engines

3.1 SHA

The SHA message digest algorithm produces a 160-bit digest. The algorithm is described in FIPS PUB 180-1, see http://www.itl.nist.gov/div897/pubs/fip180-1.

The SHA0 engine implements the original digest algorithm however this is known to be flawed and is only provided for backward compatibility. The SHA1 is believed to be secure.

3.2 MD5

This message digest algorithm produces a 128-bit digest. The algorithm is described in RFC-1321, see http://www.ietf.org/rfc/rfc1321.txt.

4.0 Signature Engines

4.1 MD5withRSA

This signature algorithm creates a digest of the data to be signed using the MD5 algorithm and then encrypts the digest using RSA. The algorithm is described in PKCS#1, see http://www.rsa.com/rsalabs/pubs/PKCS/html/pkcs-1.html.

5.0 Mac Engines

5.1 DESMac

This MAC algorithm is based on the DES encryption algorithm and produces a 4 byte MAC value. The algorithm is described in FIPS PUB 113, see FIPS PUB 113.

6.0 KeyPairGenerator Engines

6.1 RSA

The RSA key-pair generator will generate an RSA key-pair that is compatible with the RSA encryption algorithm. This factory is compatible with the Java2 keytool which allows generation of Certificates containing RSA keys.

The exponent will have the value 0x11. The public-key will be a au.net.aba.crypto.provider.RSAPubKey key which supports X.509 encoding and the private-key will be a au.net.aba.crypto.provider.RSAPrivKeyCrt key which supports PKCS#8 encoding.

This factory does not support initialisation via java.security.spec.AlgorithmParameterSpec parameters. The size parameter must be a multiple of 8 and greater than 96.

7.0 KeyGenerator Engines

These engines will create the ABA-provided key for the particular algorithm. These keys are encoded in the RAW format, that is a simple byte array.

In the case of the DES and DESede engines weak keys will not be generated.

These engines do not support java.security.spec.AlgorithmParameterSpec, and the strength value should be in the correct range for each algorithm.

8.0 KeyFactory Engines

These engines are used to convert between the opaque KeySpec classes and the provider based Key and visa-versa.

8.1 Blowfish

This class is used to convert Blowfish keys into a format usable by the ABA provider. The supported KeySpec classes are au.net.aba.crypto.spec.BlowfishKeySpec and javax.crypto.spec.SecretKeySpec. In the case of the SecretKeySpec the key data must not be encoded. The supported Key class is au.net.aba.crypto.provider.BlowfishKey.

8.2 DES

This class is used to convert DES keys into a format usable by the ABA provider. The supported KeySpec classes are javax.crypto.spec.DESKeySpec and javax.crypto.spec.SecretKeySpec. In the case of the SecretKeySpec the key data must be at least 8 bytes long and there must be no encoding on the key data. The supported Key class is au.net.aba.crypto.provider.DESKey.

8.3 DESede

This class is used to convert DESede keys into a format usable by the ABA provider. The supported KeySpec classes are javax.crypto.spec.DESedeKeySpec and javax.crypto.spec.SecretKeySpec. In the case of the SecretKeySpec the key data must be at least 24 bytes long and there must be no encoding on the key data. The supported Key class is au.net.aba.crypto.provider.DESedeKey.

8.4 IDEA

This class is used to convert IDEA keys into a format usable by the ABA provider. The supported KeySpec classes are au.net.aba.crypto.spec.IDEAKeySpec and javax.crypto.spec.SecretKeySpec. In the case of the SecretKeySpec the key data must not be encoded. The supported Key class is au.net.aba.crypto.provider.IDEAKey.

8.5 RC4

This class is used to convert RC4 keys into a format usable by the ABA provider. The supported KeySpec classes are au.net.aba.crypto.spec.RC4KeySpec and javax.crypto.spec.SecretKeySpec. In the case of the SecretKeySpec the key data must not be encoded. The supported Key class is au.net.aba.crypto.provider.RC4Key.

8.6 RSA

This class can convert between the following KeySpec classes:

And the following Key classes (note however that not all combinations make sense!):

8.7 Twofish

This class is used to convert Twofish keys into a format usable by the ABA provider. The supported KeySpec classes are au.net.aba.crypto.spec.TwofishKeySpec and javax.crypto.spec.SecretKeySpec. In the case of the SecretKeySpec the key data must not be encoded. The supported Key class is au.net.aba.crypto.provider.TwofishKey.

8.8 PBEWithMD5AndDES

This class is used to convert password based keys into a format usable by the ABA provider. The supported KeySpec class is javax.crypto.spec.PBEKeySpec and the supported Key class is au.net.aba.crypto.provider.PBEKey.

The same key factory is used for the PBEWithSHA1And128BitRC4 algorithm.