to assist Submitters to the NIST Quest for the
(As of April 25, 1998)
Table of contents
CompileKit
--Compiles
the sources
InstallKit
--Installs the Kit for a designated algorithm
KAT
--Known Answer Tester
MCT
--Monte Carlo Tester
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:
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.
The Kit is packaged in a ZIPped file and is available from the following mirror sites around the world:
To download it from this site, click here: [Download It]
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.
This Kit contains the following:
index.html
docs
Directory
Java-API.html
katmct.pdf
katmct.html
(and supporting images: ecb.gif, cbc.gif,
xor.gif)
License.html
NIST
Directory
NIST.jar
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
NIST
which
includes the file NIST.properties
.
src
Directory
NIST.jar
.
util
Directory
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
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.The following is a list of the Submitters using the Kit. Click on the algorithm name to download the latest implementation.
Name |
Status | |
Lawrence
Brown, |
Coded | |
Coded | ||
Coded | ||
Twofish |
Awaiting specifications | |
Coded | ||
BOSO |
Jurjen Bos, |
Awaiting specifications |
The Kit uses the class naming scheme described in the latest NIST API specification. Specifically:
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.
-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 |
>>
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.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.
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.
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.
jarit
batch/script which will package the
Foo.properties
file along with the
Foo*.class
compiled files into one jar file called
Foo.jar
.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.
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.
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. |
GLOBAL_DEBUG
constant in the
Foo_Properties.java
file to true.GLOBAL_DEBUG
was set to
false previously.jarit
batch/shell.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
Foo_Properties.java
file with your
editor and change the value of the constant
GLOBAL_DEBUG
to false.CompileKit
command tool:>>
java NIST.CompileKit -v -o -h
<dir-2> Foo
jarit
batch/shell.
KAT
command
tool and check its output for any errors that will indicate, if
present, an erroneous implementation.MCT
command
tool.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:
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:
Here is a detailed list of the allowed property keys and their related semantics:
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.
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.
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.
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.
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.
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 newsrc
/ 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 TesterHere 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
andecb_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.
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
andcbc_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.
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.
Mail Raif S. Naffah & Ian Grigg for any further information.
[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] JavaTM 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.