JavaTM Cryptography Extension 1.2

API Specification & Reference

Last Modified: 12 February 1998


Introduction

This document is intended as a companion to the Java Cryptography Architecture (JCA) API Specification & Reference. References to chapters not present in this document are to chapters in the JCA Specification.

The Java Cryptography Extension (JCE) 1.2 provides a framework for encryption, key agreement, and message authentication. It includes interfaces and implementations of ciphers (symmetric, asymmetric, block, and stream ciphers), secure Java streams, sealed Java objects, and session key generation.

JCE 1.2 is designed so that other cryptography libraries can be plugged in as a service provider, and new algorithms can be added seamlessly.

JCE 1.2 supplements the Java Development Kit 1.2 (JDK), which already includes interfaces and implementations of message digests and digital signatures. JCE 1.2 is provided as a Java extension to the Java platform.

The architecture of the JCE follows the same design principles found elsewhere in the JCA: implementation independence and, whenever possible, algorithm independence. It uses the same "provider" architecture.

The JCE 1.2 API covers:

JCE 1.2 comes with a built-in cryptographic provider ("SunJCE"), which supplies implementations of the following algorithms:

Concepts

This section provides a high-level description of the concepts implemented by the API, and the exact meaning of the technical terms used in the API specification.

Encryption and Decryption

Encryption is the process of taking data (called cleartext) and a short string (a key), and producing data (ciphertext) meaningless to a third-party who does not know the key. Decryption is the inverse process: that of taking ciphertext and a short key string, and producing cleartext.

Password-Based Encryption

Password-Based Encryption (PBE) generates a key from a password, and encrypts using that key. In order to make the task of getting from password to key very time-consuming for an attacker, most PBE implementations will mix in a random number, known as a salt, to create the key.

Cipher

Encryption and decryption are done using a cipher. A cipher is an object capable of carrying out encryption and decryption according to an encryption scheme (algorithm).

Key Agreement

Key agreement is a protocol by which 2 or more parties can establish the same cryptographic keys, without having to exchange any secret information.

Message Authentication Code (MAC)

A MAC provides a way to check the integrity of information transmitted over or stored in an unreliable medium, based on a secret key. Typically, message authentication codes are used between two parties that share a secret key in order to validate information transmitted between these parties.

A MAC mechanism that is based on cryptographic hash functions is referred to as HMAC. HMAC can be used with any cryptographic hash function, e.g., MD5 or SHA-1, in combination with a secret shared key. HMAC is specified in RFC 2104.

Core Classes and Interfaces

Installing JCE Providers

Cryptographic providers for the JCE are installed and configured in much the same way as cryptographic providers for the JDK. There are two parts to installing a provider: installing the provider package classes, and configuring the provider. The Installing Providers section in the Java Cryptography Architecture API Specification & Reference document explains how to do this.

The masterClassName of Sun's cryptographic provider for the JCE ("SunJCE") is com.sun.crypto.provider.SunJCE. In order to statically add SunJCE to your list of approved providers, add the following line to the java.security file in the lib/security directory of the JDK:

    security.provider.n=com.sun.crypto.provider.SunJCE

This declares the SunJCE provider, and specifies its preference order n.

To dynamically add the SunJCE provider to your list of providers, call either the addProvider or insertProviderAt method in the Security class:

    Provider sunJce = new com.sun.crypto.provider.SunJCE();
    Security.addProvider(sunJce);

The latter type of registration is not persistent and can only be done by "trusted" programs.

Cipher Output Considerations

Some of the update and doFinal methods of Cipher allow the caller to specify the output buffer into which to encrypt or decrypt the data. In these cases, it is important to pass a buffer that is large enough to hold the result of the encryption or decryption operation.

The following method in Cipher can be used to determine how big the output buffer should be:

    public int outOutputSize(int inputLen)

Examples

This section is a short tutorial on how to use some of the major features of the JCE APIs. Complete sample programs that exercise the APIs can be found in Appendix B in this document.

Simple Encryption Example

This section takes the user through the process of generating a key, creating and initializing a cipher object, encrypting a file, and then decrypting it. Throughout this example, we use the Data Encryption Standard (DES).

Generating a Key

To create a DES key, we have to instantiate a KeyGenerator for DES. We do not specify a provider, because we do not care about a particular DES key generation implementation. Since we do not initialize the KeyGenerator, a system-provided source of randomness will be used to create the DES key:

    KeyGenerator keygen = KeyGenerator.getInstance("DES");
    SecretKey desKey = keygen.generateKey();

After the key has been generated, the same KeyGenerator object can be re-used to create further keys.

Creating a Cipher

The next step is to create a Cipher instance. To do this, we use one of the getInstance factory methods of the Cipher class. We must specify the name of the requested transformation, which includes the following components, separated by slashes (/):

  • the algorithm name
  • the mode (optional)
  • the padding scheme (optional)

In this example, we create a DES (Data Encryption Standard) cipher in Electronic Codebook mode, with PKCS#5-style padding. We do not specify a provider, because we do not care about a particular implementation of the requested transformation.

The standard algorithm name for DES is "DES", the standard name for the Electronic Codebook mode is "ECB", and the standard name for PKCS#5-style padding is "PKCS5Padding":

    Cipher desCipher;

    // Create the cipher desCipher =
    Cipher.getInstance("DES/ECB/PKCS5Padding");

We use the generated desKey from above to initialize the Cipher object for encryption:

    // Initialize the cipher for encryption
    desCipher.init(Cipher.ENCRYPT_MODE, desKey);

    // Our cleartext
    byte[] cleartext = "This is just an example".getBytes();

    // Encrypt the cleartext
    byte[] ciphertext = desCipher.doFinal(cleartext);

    // Initialize the same cipher for decryption
    desCipher.init(Cipher.DECRYPT_MODE, desKey);

    // Decrypt the ciphertext
    byte[] cleartext1 = desCipher.doFinal(ciphertext);

cleartext and cleartext1 are identical.

Password-Based Encryption Example

In this example, the string "Do not share this" is used as the encryption password.

In order to use Password-Based Encryption (PBE) as defined in PKCS#5, we have to specify a salt and an iteration count. The same salt and iteration count that are used for encryption must be used for decryption.

    PBEKeySpec pbeKeySpec;
    PBEParameterSpec pbeParamSpec;
    SecretKeyFactory keyFac;

    // Salt
    byte[] salt = { (byte)0xc7, (byte)0x73, (byte)0x21, (byte)0x8c,
    (byte)0x7e, (byte)0xc8, (byte)0xee, (byte)0x99 };

    // Iteration count
    int count = 20;

    // Create PBE parameter set
    pbeParamSpec = new PBEParameterSpec(salt, count);

    // Convert password into SecretKey object, using a PBE key
    factory pbeKeySpec = new PBEKeySpec("Do not share this");
    keyFac = SecretKeyFactory.getInstance("PBEWithMD5AndDES");
    SecretKey pbeKey = keyFac.generateSecret(pbeKeySpec);

    // Create PBE Cipher
    Cipher pbeCipher = Cipher.getInstance("PBEWithMD5AndDES");

    // Initialize PBE Cipher with key and parameters
    pbeCipher.init(Cipher.ENCRYPT_MODE, pbeKey, pbeParamSpec);

    // Our cleartext
    byte[] cleartext = "This is another example".getBytes();

    // Encrypt the cleartext
    byte[] ciphertext = pbeCipher.doFinal(cleartext);

Key Agreement Example

Please refer to Appendix B for sample programs exercising the Diffie-Hellman key exchange between 2 and 3 parties, respectively.


Appendix A: Standard Names

The API requires and utilizes a set of standard names for various algorithms, algorithm modes, padding schemes, etc. This appendix supplements the standard set of names defined by Appendix A in the Java Cryptography Architecture API Specification & Reference. Note that algorithm names are treated case-insensitive.

Cipher

Algorithm

DES

DESede (alias: TripleDES)

PBEWithMD5AndDES: Password-Based Encryption, as defined in: RSA Laboratories, "PKCS #5: Password-Based Encryption Standard," version 1.5, Nov 1993.

Mode

ECB: Electronic Codebook Mode, as defined in: The National Institute of Standards and Technology (NIST) Federal Information Processing Standard (FIPS) PUB 81, "DES Modes of Operation," U.S. Department of Commerce, Dec 1980.

CBC: Cipher Block Chaining Mode, as defined in NIST FIPS PUB 81.

CFB: Cipher Feedback Mode, as defined in NIST FIPS PUB 81.

OFB: Output Feedback Mode, as defined in NIST FIPS PUB 81.

PCBC: Plaintext Cipher Block Chaining, as defined by Kerberos.

Padding

NoPadding: No padding.

PKCS5Padding: The padding scheme described in: RSA Laboratories, "PKCS #5: Password-Based Encryption Standard," version 1.5, November 1993.

KeyAgreement

DH: Diffie-Hellman Key Agreement as defined in: RSA Laboratories, "PKCS #3: Diffie-Hellman Key-Agreement Standard," version 1.4, November 1993.

MAC

HmacMD5: The HMAC-MD5 keyed-hashing algorithm as defined in: RFC 2104, "HMAC: Keyed-Hashing for Message Authentication," February 1997.

HmacSHA1: The HMAC-SHA1 keyed-hashing algorithm as defined in: RFC 2104, "HMAC: Keyed-Hashing for Message Authentication," February 1997.


Appendix B: Sample Programs


Please send comments to:
java-security@java.sun.com