United States export control laws restrict the exporting of certain types of cryptographic software outside the United States and Canada. If the JCE 1.2 were a part of the JDK, the JDK, as a whole, would fall under these export control laws. This would severely limit Java's world-wide popularity. Although the JCE was not developed specifically to deal with U.S. export control laws, you can think of it as a set of packages that contains the implementations of security-sensitive cryptographic algorithms that would otherwise be restricted. These packages are as follows:

With only three packages, 26 classes, four interfaces, and four exceptions, the JCE is rather small.

The javax.crypto package is the heart of the JCE. It defines the SecretKey interface, which extends java.security.Key to provide support for symmetric, secret-key cryptography. The classes defined by javax.crypto also define fundamental cryptographic objects. They are summarized as follows:

The four exceptions defined by javax.crypto are

They extend java.security.GeneralSecurityException to define exceptions with the size and padding of data processed by cryptographic algorithms.

The javax.crypto.interfaces package defines the DHKey, DHPrivateKey, and DHPublicKey interfaces. DHKey provides access to a Diffie-Helman key, and DHPrivateKey and DHPublicKey provide access to the private and public key components.

The javax.crypto.spec package defines the following key and algorithm parameter specifications:

The key specifications enable keys to be defined in a provider-independent manner. The algorithm parameter specifications are used to define various parameters used with cryptographic algorithms.

The Cryptix Foundation Limited has developed a clean room version of the JCE 1.2, which is available over the Web at http://www.cryptix.org. It is not subject to U.S. export restrictions.

The Cryptix JCE is aimed at being 100% compatible with Sun's JCE 1.2. However, it provides support for additional cryptographic algorithms not available in Sun's implementation. The complete list of algorithms supported by the Cryptix JCE include

Even if you currently have Sun's JCE installed, you might want to download and install the Cryptix JCE because of the additional capabilities that it provides.

One of the design features of the Java Security API and JCE is their support for cryptographic package providers. This support enables software developers to provide an independent implementation of specific cryptographic algorithms. A provider takes the form of a set of packages that implement a subset of the JCE or Java Security API.

The advantage of the Java Security API's cryptographic package provider support is that it provides a common framework for extending the API with additional algorithms, as well as with faster or more secure implementations of existing algorithms. For example, some packages might be implemented in hardware or native code to speed up algorithm response times, whereas others might be implemented in a platform-independent manner to ensure widespread availability. The end result is that the developers of cryptographic applications are able to select the algorithms and providers that best fit their needs.

Cryptographic applications can query the Java runtime environment to determine which providers have been statically installed and then dynamically install any new providers that are needed by the applications. In addition, providers can be installed in a preference order. This enables applications to choose one provider over another when a particular algorithm is supported by multiple providers.

The standard provider that is installed with the JCE 1.2 is SunJCE. SunJCE provides popular algorithms that implement the cryptographic classes of the JCE 1.2.

The Java Security API and JCE support security providers through the use of engine, SPI, and provider classes.

To show you how providers are developed and organized, you'll develop a provider that supplies a custom implementation of the rot13 cipher. The rot13 cipher is a very simple, keyless cipher that has been around since the time of Caesar. In fact, it is the Caesar cipher with a rotation of 13. The section, "A Short History of Secret Writing," in Chapter 5 covers the Caesar cipher and rot13.

Instead of limiting rot13 to the letters of the alphabet, you'll apply it to all 256 possible byte values. That is the byte value of n (between 0 and 255 inclusive) will be mapped to

(n + 13) % 256

To decrypt an encrypted byte value m, map it to

(m + 243) % 256

You'll encrypt using ECB mode and without padding (refer to Chapter 5).

Because you're developing an encryption algorithm, you'll work with the Cipher (the engine) and CipherSpi (the corresponding SPI class) classes of javax.crypto. You'll also extend the java.security.Provider class with a custom provider class that supports rot13.

package com.jaworski.security.handbook;

import java.security.*;
import java.security.spec.*;
import javax.crypto.*;
public class Rot13Cipher extends CipherSpi {
 private int opmode = Cipher.ENCRYPT_MODE;
 private int encryptionKey = 13;
 private int decryptionKey = 243;
 // Default constructor.
 public Rot13Cipher() {
 }
 // Implement the cipher
 private byte cipher(byte b) {
  int key = encryptionKey;
  if(opmode == Cipher.DECRYPT_MODE)
   key = decryptionKey;
  return (byte) ((b + key) % 256);
 }
 // CipherSpi that must be implemented.
 protected void engineInit(int opmode, Key key,
   AlgorithmParameterSpec params, SecureRandom random) {
  this.opmode = opmode;
 }
 protected void engineInit(int opmode, Key key,
   AlgorithmParameters params, SecureRandom random) {
  this.opmode = opmode;
 }
 protected void engineInit(int opmode, Key key, SecureRandom random) {
  this.opmode = opmode;
 }
 protected byte[] engineUpdate(byte[] input, int inputOffset,
   int inputLen) {
  byte[] b = new byte[inputLen];
  for(int i=0; i<inputLen; ++i)
   b[i] = cipher(input[inputOffset + i]);
  return b;
 }
 protected int engineUpdate(byte[] input, int inputOffset,
   int inputLen, byte[] output, int outputOffset)
   throws ShortBufferException {
  String msg = "Not enough room in output buffer.";
  if((output.length - outputOffset) < inputLen)
   throw new ShortBufferException(msg);
  for(int i=0; i<inputLen; ++i)
   output[outputOffset + i] = cipher(input[inputOffset + i]);
  return inputLen;
 }
 protected byte[] engineDoFinal(byte[] input, int inputOffset,
   int inputLen) {
  byte[] b = new byte[inputLen];
  for(int i=0; i<inputLen; ++i)
   b[i] = cipher(input[inputOffset + i]);
  return b;
 }
 protected int engineDoFinal(byte[] input, int inputOffset,
   int inputLen, byte[] output, int outputOffset)
   throws ShortBufferException {
  String msg = "Not enough room in output buffer.";
  if((output.length - outputOffset) < inputLen)
   throw new ShortBufferException(msg);
  for(int i=0; i<inputLen; ++i)
   output[outputOffset + i] = cipher(input[inputOffset + i]);
  return inputLen;
 }
 protected int engineGetBlockSize() {
  return 1;
 }
 protected int engineGetOutputSize(int inputLen) {
  return inputLen;
 }
 protected void engineSetMode(String mode)
   throws NoSuchAlgorithmException {
  String msg = "ROT13 only supports ECB mode.";
  if(!mode.toUpperCase().equals("ECB"))
   throw new NoSuchAlgorithmException(msg);
 }
 protected void engineSetPadding(String padding)
   throws NoSuchPaddingException {
  String msg = "ROT13 only supports the NoPadding option.";
  if(!padding.toUpperCase().equals("NOPADDING"))
   throw new NoSuchPaddingException(msg);
 }
 protected AlgorithmParameters engineGetParameters() {
  return null;
 }
 protected byte[] engineGetIV() {
  return null;
 }
}

package com.jaworski.security.handbook;

import java.security.*;

public final class Rot13Provider extends Provider {
 public Rot13Provider() {
  // Pass info to superclass constructor
  super("Rot13Provider", 1.0,
   "Rot13Provider 1.0 provides a custom ROT13 implementation.");
  // Set provider properties
  put("Cipher.ROT13","com.jaworski.security.handbook. Rot13Cipher");
 }
}

#
# List of providers and their preference orders (see above):
#
security.provider.1=sun.security.provider.Sun
security.provider.2=com.sun.crypto.provider.SunJCE

security.provider.3=com.jaworski.security.handbook.Rot13Provider

Having developed and installed the Rot13Provider, we'll write a test program that loads the provider, verifies its properties, and performs a sample encryption. The ProviderTest program of Listing 8.3 is this program. It displays the following results:

Provider name: Rot13Provider
Provider version: 1.0
Provider information: Rot13Provider 1.0 provides a custom ROT13 implementation.
Cipher: ROT13
Data to be encrypted: This is a test!
Encrypted data: 617576802d76802d6e2d817280812e
Decrypted data: 546869732069732061207465737421
Decrypted data as a String: This is a test!

The ProviderTest program invokes two methods, listProviderInfo() and testCipher(), that perform these tests. The listProviderInfo() method loads the Rot13Provider and displays the information returned by the getName(), getVersion(), and getInfo() methods inherited from Provider.

The testCipher() method creates a Cipher object that implements the rot13 algorithm as supplied by the Rot13Provider:

   Cipher cipher = Cipher.getInstance("ROT13", "Rot13Provider");

It then initializes this object and puts it in the encryption mode:

   cipher.init(Cipher.ENCRYPT_MODE,null,new SecureRandom());

A SecureRandom object is provided with init() so that the compiler can tell which form of init() to use. However, the SecureRandom object is not used by Rot13Cipher.

The test string is encrypted via the doFinal() method of Cipher:

   byte[] b1 = cipher.doFinal(testString.getBytes());

The cipher is then reinitialized in decryption mode, and the encrypted data is decrypted:

   cipher.init(Cipher.DECRYPT_MODE,null,new SecureRandom());
   byte[] b2 = cipher.doFinal(b1);

The results of these operations are then displayed to the console.

package com.jaworski.security.handbook;

import java.security.*;
import javax.crypto.*;

public final class ProviderTest {
 String providerName = "Rot13Provider";
 String algorithmName ="ROT13";
 public static void main(String[] args) {
  listProviderInfo();
  testCipher();
 }
 static void listProviderInfo() {
  Provider p = Security.getProvider("Rot13Provider");
  System.out.println("Provider name: " + p.getName());
  System.out.println("Provider version: " + p.getVersion());
  System.out.println("Provider information: " + p.getInfo());
 }
 static void testCipher() {
  try {
   Cipher cipher = Cipher.getInstance("ROT13", "Rot13Provider");
   System.out.println("Cipher: " + cipher.getAlgorithm());
   String testString = "This is a test!";
   cipher.init(Cipher.ENCRYPT_MODE,null,new SecureRandom());
   byte[] b1 = cipher.doFinal(testString.getBytes());
   cipher.init(Cipher.DECRYPT_MODE,null,new SecureRandom());
   byte[] b2 = cipher.doFinal(b1);
   System.out.println("Data to be encrypted: " + testString);
   System.out.println("Encrypted data: " +
    Conversion.byteArrayToHexString(b1));
   System.out.println("Decrypted data: " +
    Conversion.byteArrayToHexString(b2));
   System.out.println("Decrypted data as a String: " + new String(b2));
  } catch(Exception e) {
   e.printStackTrace();
   System. exit(0);
  }
 }
}

In this chapter, you took a high-level view of the JCE and learned its organization and capabilities. You also looked at the Cryptix JCE. You learned how cryptographic providers are organized in terms of engine, SPI, and provider classes. Then you developed and tested a provider that implements the rot13 cipher. In the next chapter, you'll learn how the Java Authentication and Authorization Service (JAAS) is used to support strong authentication and user authorization.