A Java^TM Kit

to assist Submitters to the NIST Quest for the

Advanced Encryption Algorithm

(As of April 25, 1998) 

Table of contents

• Introduction
  • Description
  • Where to get the latest version
  • Prerequisite
  • Contents of the Kit
  • Current users
• Programming notes
  • How to install the Kit
  • How to test an installation or compile an implementation
  • How to implement a cipher
  • How to package an implementation
  • How to test if the implementation is correct
  • How to generate Intermediate Values KAT data
  • How to generate optimized code for the implementation
  • How to generate KAT and MCT data
  • Source code
    • XXX_Properties.java
    • XXX_Algorithm.java
  • Dynamic Properties
    • Tracing properties
    • Debugging properties
  • Batch/Script files
    • jarit
• Tools for the AES Quest
  • CompileKit --Compiles the sources
  • InstallKit --Installs the Kit for a designated algorithm
  • KAT --Known Answer Tester
  • MCT --Monte Carlo Tester
• Other Sources of Information
  • Mailing list
  • Contact information
  • References

Introduction

Description

The Kit is a framework, a collection of sample Java classes, and tools and utilities that collectively offer a Submitter, of a Candidate Algorithm to the AES Quest, the following:

• Package a Java implementation for the candidate algorithm, referred to in this document as the Algorithm,
  
  
• Test the code with data from Variable Key and Variable Text Known Answer Tests (KAT). This format is described in [1].
  
  
• Generate certification data described, content- and format-wise, in [1] (all Known Answer Tests and Monte Carlo Tests),
  
  
• Generate certification data referred to in [1] as Intermediate Values KAT.
  
  
• Package the classes and required runt-time resources in a Jar file,
  
  

This freely available product is co-produced by the National Institute of Standards and Technology (NIST) and the Cryptix Development Team. The code developed by Cryptix in this project falls under the Cryptix General License.

Where to get the latest version

The Kit is packaged in a ZIPped file and is available from the following mirror sites around the world:

• Australia
• Baltics
• Finland
• Germany
• Japan
• Netherlands
• Switzerland
• Tonga
• United Kingdom
  • ac.UK
  • co.UK
• USA.

To download it from this site, click here: [Download It]

Prerequisite

To use this Kit for coding and/or testing an algorithm implementation, you also need to have a free or commercial Java compiler or runtime environment, such as those available in Sun's JDK and JRE. See JavaSoft's site and alternatives for available Java downloads.

Contents of the Kit

This Kit contains the following:

index.html

This file.

 

docs Directory

Contains the following files:

 

Java-API.html

The Java Cryptographic API for AES Candidate Algorithm Submissions available at the time of packaging this version of the Kit.

 

katmct.pdf

The latest PDF version of the document Description of Known Answer Tests and Monte Carlo Tests for Advanced Encryption Standard (AES) Candidate Algorithm Submissions available at the time of packaging this version of the Kit.

 

katmct.html (and supporting images: ecb.gif, cbc.gif, xor.gif)

An HTML version of the above document.

Important: This html file was generated automatically from the pdf version without proof-reading. In case of discrepancy between these two files, the PDF version takes precedence.

 

License.html

The Cryptix General License.

 

 

NIST Directory

Containing the following:

 

 

NIST.jar

A jar archive containing the compiled classes used by the code in this Kit. These are:

• NIST/NIST.properties
• NIST/CompileKit.class
• NIST/InstallKit.class
• NIST/KAT.class
• NIST/MCT.class
• NIST/NIST_Algorithm.class
• NIST/NIST_CBC.class
• NIST/NIST_CFB.class
• NIST/NIST_Cipher.class
• NIST/NIST_CipherSpi.class
• NIST/NIST_ECB.class
• NIST/NIST_Properties.class



classes Directory

Contains one directory called NIST which includes the file NIST.properties.

 

src Directory

Contains source code of all the classes jarred in NIST.jar.

 

util Directory

Contains a batch file (jarit.bat) and a shell script file (jarit.sh) used to create a jar file for either the NIST package or any AES candidate algorithm implementation developed with this Kit.

 

XXX Directory

Containing the file XXX.properties and a src Directory. The latter contains source of skeleton template classes needed to build a Java implementation of the Algorithm that uses the Basic API defined by NIST.

Current users

The following is a list of the Submitters using the Kit. Click on the algorithm name to download the latest implementation.

Programming notes

The Kit uses the class naming scheme described in the latest NIST API specification. Specifically:

• Naming: All classes related to the Algorithm shall start with the prefix XXX_ where XXX is the name of the Algorithm with no spaces in between and using legal Java identifier characters only. For a formal definition of Java Identifiers' syntax please refer to this.
  
  
• Packaging: The final product, produced by this Kit, will consist of one file: a Jar file, named XXX.jar -- where XXX will be replaced by the real Algorithm name-- containing the compiled Java classes, and a properties file named XXX.properties.

The following sections detail programming issues related to the Kit.

How to install the Kit

1. Upon receiving the Kit, unzip it preserving its internal tree structure (using the -N option with gunzip or the Use Directory Info with WinZip or equivalent). The extracted tree structure will look as follows, assuming that <dir-1> is the directory where the extracted files will be:

   <dir-1> | KIT __________________|______________ | | | | docs index.html NIST XXX | ___|___ _____|____ ... | | | | NIST.jar ... src XXX.properties ___|___ | | XXX*.java

    

2. Before going any further, you now have to place the NIST.jar file on your Java Class Path. Consult your Java documentation on how to edit the CLASSPATH environment variable for your specific platform. This NIST.jar includes all the supplied.tools described in the rest of this page.
   
   
3. From your console, run the following command:
   
   
   >> java NIST.InstallKit -v -s <dir-1> -d <dir-2> <Foo>
   
   

   where:

   • <dir-1>: is the pathname to the directory where you extracted the Kit,
   • <dir-2>: is a destination directory where the customised template source files will be generated, and
   • <Foo>: is the name of the candidate algorithm you want to implement.
     
     
4. After successful completion of the NIST.InstallKit command, this is what <dir-2> will look like:

   <dir-2> | Foo _____________|___________ | | | classes src (Foo.jar) | ___|___ Foo | | _______|_________ Foo*.java | | | (Foo*.class) Foo.properties

    

   File object names between parentheses denote objects that are not initially included in the distribution, but will be created by the javac compiler and jar tools. Specifically:

   • (Foo*.class) files under the classes/Foo directory will be created by NIST.CompileKit.
   • (Foo.jar) will be created by the jarit batch/srcipt.

How to test an installation or compile an implementation

1. To make sure that everything works so far, or if you started editing the source files, you need to compile the sources using the CompileKit command tool.
   
   
   >> java NIST.CompileKit -v -h <dir-2> Foo
   
   

   The unedited sources (just after a first-time installation of the Kit) are effectively a NULL block cipher, which outputs the same data it receives on input.. No compilation errors should occur.

How to implement a cipher

1. Edit the file src/Foo_Algorithm.java implementing the real algorithm and the NIST Basic API methods and repeat the previous step until all compilation erros are eliminated.

How to package an implementation

1. Run the jarit batch/script which will package the Foo.properties file along with the Foo*.class compiled files into one jar file called Foo.jar.
   
   
2. Add the Foo.jar file to your CLASSPATH environment variable, preferably at its beginning. Please note that you need doing this only once even if you generate the same .jar file more than once.

How to test if the implementation is correct

1. To make sure that the implemented algorithm works (more precisely to test if it does decrypt what it encrypts and vice versa), run the self_test method(s). This is achieved by entering:
   
   
   >> java Foo.Foo_Algorithm
   
   

   on your console. This will invoke the main() method in the above class which in turn will test your implementation for the 3 required NIST key sizes; ie. 128-, 192- and 256-bit cases.

How to generate Intermediate Values KAT data

1. Open the Foo.properties file, which should be located in <dir-2>/Foo/classes/Foo where <dir-2> is the pathname of Foo's home directory, and edit the Debug.Level.Foo_Algorithm property to assign it the value 7; eg:
   
   
   Debug.Level.Foo_Algorithm = 7
   
   

   Note: The values 7 to 9 inclusive for Debug.Level properties are used in the default template code for special purposes according to the following table
   
   

   Value	Print to System.out
   9	Result(s) of static code and initialization timings.
   8	Intermediate values for session key generation.
   7	Intermediate values for encryption/decryption; ie. Intermediate Values KAT data.

    

2. Set the GLOBAL_DEBUG constant in the Foo_Properties.java file to true.
   
   
3. Recompile the code unless GLOBAL_DEBUG was set to false previously.
   
   
4. Package Foo using the jarit batch/shell.
   
   
5. Run Foo_Algorithm from the Java console and collect the output, say in the file out.dl7.txt prefereably in <dir-2>/Foo directory like so:
   
   
   >> java Foo.Foo_Algorithm >out.dl7.txt

How to generate optimized code for the implementation

1. Open the Foo_Properties.java file with your editor and change the value of the constant GLOBAL_DEBUG to false.
   
   
2. Re-compile the sources using the -o switch in the CompileKit command tool:
   
   
   >> java NIST.CompileKit -v -o -h <dir-2> Foo
   
   
3. Package Foo using the jarit batch/shell.

How to generate KAT and MCT data

1. Run the supplied KAT command tool and check its output for any errors that will indicate, if present, an erroneous implementation.
   
   
2. Run the supplied MCT command tool.
   

Source code

The XXX directory contains the Java source code of the classes implementing the Algorithm. The same code will be copied to the new directory, which we referred to earlier as Foo under a subdirectory called src. During the Installation phase, all occurences of the string XXX in the template sources will be replaced by Foo which is really the name you chose for your algorithm.

The following is a detailed list of the skeleton classes supplied with the Kit. The description for each file is valid for the XXX*.java as well as the Foo*.java files. Since Foo is just an example name, in the following, we will refer to the XXX*.java files.

XXX_Properties.java

The actual client class that manages the system-wide algorithm implementation properties. It is intended to act as the hook to the Dynamic Properties; ie. those properties that may be changed without recompiling the source code.

XXX_Algorithm.java

This class actually implements the mathematical formulae of the Algorithm through Java static methods. Doing so allows a variety of uses of the Algorithm that otherwise would have been:

• inaccessible through a rigid Security API,
• forced to carry an undesired performance overhead, or
• dependent on the underlying JCE implementation (version, features, etc...).

Dynamic Properties

The XXX.properties file contains algorithm and environment specific properties that you can modify without re-compiling the sources.

The syntax of this file obeys standard Java properties file rules, namely and for what is relevant to this project:

• a comment line starts with the "#" symbol and extends until the end of the current line.
• a property line starts with a 'key' in dotted form, followed by the "=" sign and terminated by a character literal.

Here is a detailed list of the allowed property keys and their related semantics:

Tracing properties

These are of the form:

Trace.<class-name> = <traceable>

where <class-name> is any of the classes described in the previous section, and <traceable> is one of true or false. When a class class is traceable, and for those methods where tracing has been set by the programmer, a message will be printed on System.err at both entry and exit points.

Debugging properties

These are of the form:

Debug.Level.<class-name> = <debug-level>

or

Debug.Level.* = <default-debug-level>

As mentioned above, <class-name> refers to any one of the classes contained in the Package. <debug-level> And <default-debug-level> are numeric constants between 0 and 9 inclusive.

These properties operate in conjunction with a global debugging constant (Static Property) named GLOBAL_DEBUG set in the XXX_Properties class. If this GLOBAL_DEBUG constant is set to false then the values of the tracing and debugging properties are inoperable. Otherwise, a message and debug information will be printed on System.err anywhere the programmer has set a debugging command in the source.

To set a default global debugging level, assign a value to the Debug.Level.* property key.

Batch/script files

One very simple batch file (for Windows'95) and a Unix script are included in this Kit. They assume that a JDK is properly installed, and that the jar command is in a directory already included in the PATH environment variable.

jarit

Build a Jar file from the compiled source files.

Tools for the AES Quest

Cryptix has specially designed two tools for the AES submitters: KAT and MCT, in addition to two development tools. All are detailed in this section.

CompileKit --Compiles the sources

Here is the synopsis for this command:

NAME
CompileKit: Compiles a specified AES candidate algorithm source.

SYNTAX

java NIST.CompileKit
[ -v ]
[ -o ]
[ -h <home-directory>]
<algorithm>

DESCRIPTION
Invokes the javac command to compile all .java source files in a designated directory according to the conventions of the NIST-Kit.

OPTIONS

-v
Verbose.

-o
Optimise the compiled code.

-h <home-directory>
Pathname of the algorithm home directory containing the 'src' and 'classes' directories. If unspecified, the current user directory is considered.

<algorithm>
Candidate algorithm name (Foo in the documentation).

COPYRIGHT
Copyright (c) 1998 Systemics Ltd. on behalf of the Cryptix Development Team. All rights reserved.

InstallKit --Installs the Kit for a specified algorithm

Here is the synopsis for this command:

NAME
InstallKit: Installs the NIST-Kit template sources for a specified candidate algorithm name..

SYNTAX

java NIST.InstallKit
[ -v ]
[ -f ]
[ -s <source-directory>]
[ -d <destination-directory>]
<algorithm>

DESCRIPTION
Creates a new directory named after the candidate algorithm and copies the template source files there, renaming them by replacing the 'XXX' prefix with the algorithm's name.

OPTIONS

-v
Verbose.

-f
Overwrite existing files and directories if already there.

-s <source-directory>
Pathname where the 'src' directory and the template source files are located (<dir-1>/ in the documentation). If left unspecified, the current user directory is considered.

-d <destination-directory>
Pathname where the new src/ directory and the properly named blank source files will be installed (<dir-2>/ in the documentation). If left unspecified, the current user directory is considered.

<algorithm>
Candidate algorithm name (Foo in the documentation).

COPYRIGHT
Copyright (c) 1998 Systemics Ltd. on behalf of the Cryptix Development Team. All rights reserved.

KAT --Known Answer Tester

Here is the synopsis for this command:

NAME
KAT: A Known Answer Tests data generator/exerciser for any block cipher algorithm.

SYNTAX

java NIST.KAT
[ -k | -t ]
[ -l <comma-separated-key-lengths>]
[ -d <output-directory>]
<cipher>

DESCRIPTION
For a designated symmetric block cipher algorithm, KAT generates and exercises Known Answer Tests data for both Variable Key and Variable Text suites.

KAT's output file format conforms to the layout described in Section 3 of NIST's document Description of Known Answer Tests and Monte Carlo Tests for Advanced Encryption Standard (AES) Candidate Algorithm Submissions dated January 7, 1998.

OPTIONS

-k
Generate data for variable-key tests only. By default KAT generates both variable-key and variable-text test suites.

-t
Generate data for variable-text tests only. By default KAT generates both variable-key and variable-text test suites.

-l <comma-separated-key-lengths>
Comma separated list (maximum of three) of key lengths to use for the tests. If omitted, the following three values are assumed: 128, 192 and 256.

-d <output-directory>
Pathname of the directory where output files: ecb_vk.txt and ecb_vt.txt will be generated. If this destination directory is not specified, those files will be placed in the current user directory.

<cipher>
Cipher algorithm name.

COPYRIGHT
Copyright (c) 1998 Systemics Ltd. on behalf of the Cryptix Development Team. All rights reserved.

MCT --Monte Carlo Tester

Here is the synopsis for this command:

NAME
MCT: A Monte Carlo Tests data generator/exerciser for any block cipher algorithm.

SYNTAX

java NIST.MCT
[ -e | -c ]
[ -E | -D ]
[ -l <comma-separated-key-lengths>]
[ -d <output-directory>]
<cipher>

DESCRIPTION
For a designated symmetric block cipher algorithm, this command generates and exercises Monte Carlo Tests data for both Encryption and Decryption in Electronic Codebook (ECB) and Cipher Block Chaining (CBC) modes.

MCT's output file format is in conformance with the layout described in Section 4 of NIST's document Description of Known Answer Tests and Monte Carlo Tests for Advanced Encryption Standard (AES) Candidate Algorithm Submissions dated January 7, 1998.

OPTIONS

-e
Generate test data for the cipher in ECB mode only. By default MCT generates both ECB and CBC test suites.

-c
Generate test data for the cipher in CBC mode only. By default MCT generates both ECB and CBC test suites.

-E
Generate Encryption data only for the cipher in one or both of ECB and CBC modes depending on the first two switches. By default MCT generates both Encryption and Decryption data.

-D
Generate Decryption data only for the cipher in one or both of ECB and CBC modes depending on the first two switches. By default MCT generates both Encryption and Decryption data.

-l <comma-separated-key-lengths>
Comma separated list (maximum of three) of key lengths to use for the tests. If omitted, the following three values are assumed: 128, 192 and 256.

-d <output-directory>
Pathname of the directory where the output files: ecb_e_m.txt, ecb_d_m.txt, cbc_e_m.txt and cbc_d_m.txt will be generated. If this destination directory is not specified, those files will be placed in the current user directory.

<cipher>
Cipher algorithm name.

COPYRIGHT
Copyright (c) 1998 Systemics Ltd. on behalf of the Cryptix Development Team. All rights reserved.

Other Sources of Information

Mailing list

A mailing list for the Cryptix software library is available for asking for, and most of the time, obtaining help on using the software. To subscribe send an email to majordomo@systemics.com with:

subscribe cryptix-java

only in the body of the message.

Contact information

Mail Raif S. Naffah & Ian Grigg for any further information.

References

[1] Description of Known Answer Tests and Monte Carlo Tests for Advanced Encryption Standard (AES) Candidate Algorithm Submissions --January 7, 1998. Also in the original PDF format.

[2] Java^TM Cryptographic API for AES Candidate Algorithm Submissions. April 6, 1998.

Cryptix is a trademark of Systemics Ltd. Sun, JavaSoft, JDK, and Java are trademarks or registered trademarks of Sun Microsystems, Inc Windows 95 is a registered trademark of Microsoft Corp. All other registered trademarks and trademarks are the property of their respective owner or owners.