Java^TM Cryptographic API

for

AES Candidate Algorithm Submissions

Original: April 6, 1998

1. Overview

The NIST intention is to allow both international and U.S. domestic submitters to present AES candidate algorithms under a single, stable API specification. The API set described herein permits all AES submitters to present a working implementation of their algorithm in the Java programming language that (a) can be tested with the freely supplied NIST KAT and MCT Java command line tools, (b) supports the NIST requirement for Electronic Codebook (ECB), Cipher Block Chaining (CBC), and 1-bit Cipher Feedback (1-CFB) modes, and (c) can be compared to other algorithm implementations running on the same Java Virtual Machine (JVM) and/or same implementation running on different JVMs.

To further help submitters with their Java implementation, the NIST and the Cryptix Development Team have co-developed a Kit that includes:

1. A two-level API that allows submitters to present a minimal Java code implementation that complies with NIST requirements as stated above for feedback modes of operation. The first set of these API calls shall be referred to hereafter as Basic API or Level-0 API, while the second set shall be referred to as Extended API or Level-1 API. Submitters must implement the Basic API, and may choose to provide their own concrete implementations of the Extended API or to use the code provided in the NIST/Cryptix Kit for this purpose.
   
   
2. Source code for the API described herein, including concrete implementation for a Null Cipher; ie. a cipher whose output is identical to its input. This code can be freely used to (a) implement the Basic API for a specific candidate algorithm, and (b) serve as an example and test-bed for those submitters who wish to code their own Java implementation of the Extended API classe(s).
   
   
3. Source code (.java files) and binaries (.class files) for KAT and MCT command line tools that submitters can use to (a) test their implementation of a candidate algorithm, and (b) generate the test data in the form and contents described by NIST Description of Known Answer Tests and Monte Carlo Tests for Advanced Encryption Standard (AES) Candidate Algorithm Submissions. The KAT and MCT tools use the Basic API for performance reasons, and it is expected that independent KAT/MCT implementations will do the same since comparative performance analysis would otherwise be impossible.

The toolkit is now available from Cryptix. This toolkit is also available at http://cryptix.moremagic.com/aes/, http://193.192.247.149/mirror/cryptix/aes/, and http://www.bssl.co.uk/mirrors/cryptix/aes/.

2. API in detail

The Minimum Acceptability Requirements (section 3) of the Request for Candidate Algorithm states:

To be considered as a “proper” candidate algorithm submission (and continue further in the AES Development Process), candidate algorithms must meet the following minimum acceptability requirements:

1. The algorithm must implement symmetric (secret) key cryptography.
2. The algorithm must be a block cipher.
3. The candidate algorithm shall be capable of supporting key-block combinations with sizes of 128-128, 192-128, and 256-128 bits. A submitted algorithm may support other key-block sizes and combinations, and such features will be taken into consideration during analysis and evaluation.

The NIST General Requirements (section 2.C.2) also state that the mathematically optimized implementations (both Java and ANSI C) will support the ECB, CBC, and 1-CFB modes of operation.

To fulfil these minimum requirements, the Basic API shall implement the block cipher algorithm primitive operations to (a) generate its internal key from the user supplied key material and (b) to operate the block cipher in encryption/decryption in Electronic Code Book mode. The Extended API shall allow users to instantiate and operate a candidate algorithm in all three required feedback modes of operation.

2.1. Basic API

Shall consist of the following four public methods to be available in a public class called XXX_Algorithm in the package XXX, where the token XXX is replaced with the actual name of the candidate algorithm.

2.1.1. makeKey

public static synchronized Object makeKey (byte[] key) throws InvalidKeyException

Signature	makeKey (byte[] key)
Description	Expand a user-supplied key material into a session key.
Parameters	key The 128/192/256-bit user-key material to use, encoded in a Java byte array.
Exceptions	InvalidKeyException If the user-supplied key material is invalid.
Returns	An object of class Object that contains the session key (also known as the round keys) for both encryption and decryption operations. The semantics of the contents of this object are implementation dependant.

2.1.2. blockEncrypt

public static byte[] blockEncrypt (byte[] in, int inOffset, Object sessionKey)

Signature	blockEncrypt (byte[] in, int inOffset, Object sessionKey)
Description	Encrypt exactly one block of plaintext in Electronic Code Book mode, returning the resulting ciphertext.
Parameters	in A buffer (Java byte array) containing the plaintext.   inOffset Offset in in buffer where plaintext starts.   sessionKey The session key object returned by a previous invocation to the makeKey() method.
Exceptions	None
Returns	A Java byte array containing the resulting ciphertext block.

2.1.3. blockDecrypt

public static byte[] blockDecrypt (byte[] in, int inOffset, Object sessionKey)

Signature	blockDecrypt (byte[] in, int inOffset, Object sessionKey)
Description	Decrypt exactly one block of ciphertext in Electronic Code Book mode, returning the resulting plaintext.
Parameters	in A buffer (Java byte array) containing the ciphertext.   inOffset Offset in in buffer where ciphertext starts.   sessionKey The session key object returned by a previous invocation to the makeKey() method.
Exceptions	None
Returns	A Java byte array containing the resulting plaintext block.

2.1.4. self_test

public static boolean self_test()

Signature	self_test()
Description	Basic simple self test(s).
Parameters	None
Exceptions	None
Returns	True iff all tests pass; false otherwise.

2.2. Extended API

The Extended API is defined in the NIST.NIST_CipherSpi interface (included in the Kit). It consists of the following methods.

2.2.1. init

public abstract void init (int state, byte[] key) throws InvalidKeyExceptiony;

Signature	init (int state, byte[] key)
Description	Initialize this cipher for encryption/decryption, using designated key material.
Parameters	state Desired operation state of this instance. Valid values are ENCRYPT_STATE or DECRYPT_STATE.   key User key material to use for the session.
Exceptions	InvalidKeyException If the user-supplied key material is invalid.
Returns	Void.
See also	In NIST.NIST_Cipher ENCRYPT_STATE DECRYPT_STATE

2.2.2. setIV

public abstract void setIV (byte[] iv) throws InvalidParameterException;

Signature	setIV (byte[] iv)
Description	Set the starting value of the IV.
Parameters	iv The user-supplied IV value.
Exceptions	InvalidParameterException If the supplied IV value is of the wrong length.
Returns	Void.

2.2.3. update

public abstract byte[] update (byte[] in, int inOff, int inLen);

Signature	update (byte[] in, int inOff, int inLen)
Description	Continue a multi-part encryption/decryption operation.
Parameters	in Input buffer containing the plaintext/ciphertext (depending on the current cipher's operational state).   inOff Offset into in specifying where data starts. Caller must ensure it's a positive value that will not cause an ArrayIndexOutOfBoundsException when accessing in.   inLen Length of the subarray. Caller must ensure inLen is a non-zero positive value.
Exceptions	NullPointerException If the IV has not been set.   IllegalStateException If the cipher's operational state is not properly set.
Returns	The encrypted/decrypted input text.

2.2.4. doFinal

public abstract byte[] doFinal (byte[] in, int inOff, int inLen);

Signature	doFinal (byte[] in, int inOff, int inLen)
Description	Encrypt/decrypt data in a single-part operation or finish a multi-part operation.
Parameters	in Input buffer containing the plaintext/ciphertext (depending on the current cipher's operational state).   inOff Offset into in specifying where data starts. Caller must ensure it's a positive value that will not cause an ArrayIndexOutOfBoundsException when accessing in.   inLen Length of the subarray. Caller must ensure inLen is zero or a positive value.
Exceptions	NullPointerException If the IV has not been set.   IllegalStateException If the cipher's operational state is not properly set.   InvalidParameterException If the operation when carried out, will cause an illegal block size exception; eg. the total length of data to encrypt is not a multiple of the cipher's block size.
Returns	The encrypted/decrypted input text including any other data that may have been buffered in one or more earlier invocations to update.

2.2.5. self_test

public abstract boolean self_test();

Signature	self_test()
Description	Basic simple self test(s).
Parameters	None
Exceptions	None
Returns	True iff all tests pass; false otherwise.

3. Notes to implementors

For submitters who choose to implement their own Extended API, the following notes should be considered:

• Applications using an AES implementation might instantiate a candidate algorithm object through the following call to NIST.NIST_Cipher (for example):
  
  
  NIST_Cipher cipher = new NIST_Cipher("Foo", ECB_MODE);


• The NIST.NIST_Cipher class will try to instantiate an object that implements an AES candidate algorithm operating in one of the NIST required modes.
  
  It first attempts to instantiate a class that implements NIST.NIST_CipherSpi Extended API interface and is supposed to be called aes_suffix , located in package aes. suffix will be ECB, CBC or CFB depending on the value of the mode argument according to the following table:
  

  Mode	Suffix	Full class name
  ECB_MODE	ECB	aes.aes_ECB
  CBC_MODE	CBC	aes.aes_CBC
  CFB_1BIT_MODE	CFB	aes.aes_CFB

  If the above fails, this class then tries to use NIST's own implementations of the feedback modes which assume a class named aes_Algorithm in package aes implementing the Basic API.
  
  If that also fails, this class then throws the appropriate Exception.
  
  

• If submitters choose to implement their own classes to operate the cipher in NIST required feedback modes, and besides the naming convention described above, each class will have at least one public constructor that requires no arguments.
   

4. Packaging of the implementation

1. The Java implementation classes shall be members of a package called Algorithm where the word Algorithm is substituted by the actual candidate algorithm; eg. for a candidate algorithm named Foo, the implementation classes will belong to the package Foo.
   
   
2. Submitters should present the Java implementation packaged in a JAR file named Algorithm.jar where the word Algorithm is substituted by the actual candidate algorithm name; eg. for a candidate algorithm named "Foo", the implementation classes will be packaged in the file Foo.jar.

Questions?

Computer Security Division
National Institute of Standards and Technology