The GNU Crypto project

Introduction | Downloads | Help wanted | Project status |
GNU Keyring file format | Documentation | Note on primality testing |
Configuration parameters | Building GNU Crypto | Tools |
Mailing lists | Report a bug | Coding styles | Logos

News: GNU Crypto has been merged into GNU Classpath, and we will be maintaining the code there. We encourage you to contribute to Classpath, instead of GNU Crypto, but if there is something you'd like to work on in GNU Crypto that doesn't fit in Classpath, feel free to ask a question on the mailing list.

Introduction

GNU Crypto, part of the GNU project, released under the aegis of GNU, aims at providing free, versatile, high-quality, and provably correct implementations of cryptographic primitives and tools in the Java programming language for use by programmers and end-users.

GNU Crypto is licensed under the terms of the GNU General Public License, with the "library exception" which permits its use as a library in conjunction with non-Free software:

"As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version."

The effect of that license is similar to using the LGPL, except that static linking is permitted. GPL with that exception is sometimes called the Guile License, because the Guile implementation of Scheme (for embedding) uses this license.

Downloads

You can download the latest software from ftp.gnupg.org/gcrypt/gnu-crypto. You'll probably want to use one of the FTP mirror sites, although the mirrors may not be current (most are synchronised daily).

The current distribution is available as:

Binary packages, containing gnu-crypto.jar, javax-crypto.jar, and javax-security.jar:

Also available is a "development release," which adds a great deal of functionality atop 2.0, but maintains most of the present interface:

The NIST and NESSIE compliant test vectors, generated by the algorithms implemented in this library, are available as:

All releases are signed with this key, ID 0446B16B

Up-to-date source code for this project is available in the gnu-crypto module through CVS.

Help wanted!

Development of GNU Crypto is a volunteer effort, and you can also contribute! We need lots of help to finish, and enhance, the current APIs and to keep track of future additions and enhancements. There are also opportunities for testers, web authors, and documenters. Please post to the general discussion mailing list if you're interested in helping.

Here is a list of areas where you can help:

1. Algorithms:
   • NESSIE (phase-2) algorithms,
   • IEEE P1363 algorithms.
   • Elliptic curve public-key algorithms.
   • Kerberos, GSS-API, and the Java Authentication and Authorization Service.
   
   
2. Tools:
   • tool to quantify randomness (better than ENT).
   • tool to construct cipher engines (d&d ciphers, padding, modes).
   • tool to compare 2 test vector sets, not necessarily generated by the same library.
   • A replacement for keytool.
   • An extended jar implementation that can encrypt entries.
   
   
3. Testing:
   • more Mauve test cases.
   • Thorough audit of the source code.
   
   
4. Performance:
   • Evaluate performance of algorithms on different platforms/environments.
   • More optimised versions of algorithms.
   
   
5. Documentation:
   • Thorough review of the programmer's documentation.
   • More comprehensive programmer's documentation text.
   • Programmer's guide(s) for using the library.
   • A programmer's tutorial.
   
   

Cleanroom API Status

In addition to the GNU Crypto API, we also include a clean-room implementation of the Java Cryptography Extension (JCE), which includes the javax.crypto package and its subpackages. The current version is derived from the implementation written by The Legion of the Bouncy Castle, but we are working on our own implementation.

Thanks to the japitools (by Stuart Ballard), and to Tom Tromey from the GCJ project, this page shows the current status of the combined efforts of GCJ and GNU Crypto with regard to Java API compatibility with the JDK 1.4. It is updated nightly, and is run against the CVS trunk. This is the most up-to-date analysis of API differences.

GNU Keyring file format

There is currently a proposal for a new keyring format to be used by various GNU Java projects; e.g. GNU Classpath, GCJ, GNU Crypto, as the official "keystore" format for those platforms. One of the objectives of such format is to provide free Java projects with similar functionalities to those offered by the Java Keystore (JKS) format.

The current draft is available here.

Documentation

GNU info pages (in HTML) are available for on-line browsing here.

JavaDoc HTML pages for the GNU Crypto packages are available, for on-line browsing, with and without frames.

The latest version of the Programmer's Manual (in PDF) is also available here.

The UML diagrams used in the documentation where edited using Dia—diagram files included in the source tarball. This was done this way because of the lack of a free, and working, UML diagramming tool capable of round-trip engineering Java code. The only such tool that will hopefully provide this capability seems to be Umbrello. PNG images were then generated from the DIA files, and later converted to EPS and PDF using ImageMagick.

Reference documents describing the details of the cryptographic algorithms implemented in this library are available for viewing/downloading. Here is the list:

• AES Proposal: Rijndael.
• Integer Counter Mode.
• PKCS #7: Cryptographic Message Syntax Standard.
• RFC 1423: Privacy Enhancement for Internet Electronic Mail: Part III: Algorithms, Modes, and Identifiers.
• Recommendation for Block Cipher Modes of Operation.
• RIPEMD-160: A Strengthened Version of RIPEMD.
• The ANUBIS Block Cipher.
• The Block Cipher Square.
• The KHAZAD Legacy-Level Block Cipher.
• The WHIRLPOOL Hashing Function.
• Twofish: A 128-bit Block Cipher.
• SECURE HASH STANDARD.
• RFC 1321: The MD5 Message-Digest Algorithm.
• DIGITAL SIGNATURE STANDARD.
• RSA-PSS Signature Scheme with Appendix.
• UMAC: Message Authentication Code using Universal Hashing.
• TMMH/16: The Truncated Multi-Modular Hash Function (TMMH).
• UST: The Universal Security Transform.
• Serpent: A Candidate Block Cipher for the Advanced Encryption Standard.
• RFC 1320: The MD4 Message-Digest Algorithm.
• RFC 1319: The MD2 Message-Digest Algorithm.
• The Blowfish Encryption Algorithm.
• Data Encryption Standard DES.
• A Stream Cipher Encryption Algorithm ArcFour.
• Tiger: A Fast New Cryptographic Hash Function.
• HAVAL: A One-Way Hashing Algorithm with Variable Length of Output (Extended Abstract).
• RFC-2144: The CAST-128 Encryption Algorithm.
• RFC-2595: Using TLS with IMAP, POP3 and ACAP.
• RFC-2245: Anonymous SASL Mechanism
• RFC-2195: IMAP/POP AUTHorize Extension for Simple Challenge/Response.
• SRP Authentication Mechanism
• RFC-2898: PKCS #5: Password-Based Cryptography Specification Version 2.0.
• RFC-3447: Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1.
• RFC-2631: Diffie-Hellman Key Agreement Method.

Test vectors, when not included in the reference documents, are made available by the designers of the algorithms. The current implementation was checked against the following test vectors:

• Anubis:
  • 128-bit key,
  • 160-bit key,
  • 192-bit key,
  • 224-bit key,
  • 256-bit key,
  • 288-bit key,
  • 320-bit key.
• Khazad,
• Rijndael:
  • Monte-Carlo Tests
    • ECB Mode: Encryption, Decryption,
    • CBC Mode: Encryption, Decryption,
  • Variable Key Known Answer Test,
  • Variable Text Known Answer Test.
• Serpent:
  • Monte-Carlo Tests
    • ECB Mode: Encryption, Decryption,
    • CBC Mode: Encryption, Decryption,
  • Variable Key Known Answer Test,
  • Variable Text Known Answer Test.
• Twofish:
  • Monte-Carlo Tests
    • ECB Mode: Encryption, Decryption,
    • CBC Mode: Encryption, Decryption,
  • Variable Key Known Answer Test,
  • Variable Text Known Answer Test.
• Whirlpool.

Configuration parameters

There are three parameters that would impact the behaviour of the binaries, all defined, and accessible, from the class gnu.crypto.Properties:

Building GNU Crypto

GNU Crypto can be built in three different ways, yielding two different types of binaries:

1. GCJ-friendly build
   

   This is an all-GNU process that results in dynamic shared libraries (javax-crypto.so, javax-security.so, gnu-crypto.so). Building the library this way is the best (and in some cases, the only) way when compiling and linking native applications. Especially optimised implementations of some algorithms are automagically included in this build.

   This method relies on the GNU toolchain and on GCJ (GNU Compiler for Java), part of GCC (GNU Compiler Collection). Note however that you need version 3.1 or later of the GCJ.

2. Non-GCJ-friendly build
   

   No shared libraries are produced in these builds; only .class files in Jars are generated. This is achieved, either

   • With Apache ANT tool, or

   • With the GNU toolchain (configure, make, etc.)

     The only requirements for building the library this way is to define which java bytecode compiler, as well as which java bytecode interpreter to use. This is done by setting the environment variables JAVA, JAVAC, and CLASSPATH appropriately during the configure phase. Optionally the environment variable JAVAFLAGS may need to be set.

     The following configurations are known to be working. If you succeed in configuring, building and or testing the library with other tools, please let us know so we can list these here:

     • Sun's JDK 1.4.2_01:

       ./configure JAVAC=javac JAVA=java JAVAFLAGS="-Xbootclasspath/p:../jce/javax-crypto.jar"
       make
       make check
             

     • Jikes compiler, and Jikes RVM:

       ./configure JAVAC=jikes JAVA=rvm CLASSPATH=$JAVA_HOME/jre/lib/rt.jar
       make
       make check
             

     • Jikes compiler, and kissme VM:

       ./configure JAVAC=jikes JAVA=kissme CLASSPATH=.:$JAVA_HOME/jre/lib/rt.jar
       make
       make check
             

   This type of build is best suited for applications running with free VMs, or with JIT-like runtime interpreters.

The INSTALL document in the distribution contains a step-by-step description of each of the above processes.

Mailing lists

The main discussion list is <gnu-crypto-discuss@gnu.org>, and is used to discuss all aspects of GNU Crypto project.

Announcements about GNU Crypto are made on the low-volume <gnu-crypto-announce@gnu.org> mailing list.

For subscription information, see the mailing list info from the project page.

When this project first started, it was hosted under another GNU project. The archives of the discussion mailing list during that period are still available:

November 2001	27.4 KB
December 2001	43.4 KB
January 2002	19.1 KB
February 2002	4.1 KB
April 2002	4.3 KB
June 2002	209.5 KB
July 2002	34.2 KB
September 2002	112.9 KB
August 2002	35.7 KB
All	657.9 KB

Report a bug

If you think you have found a bug in GNU Crypto, then you should send as complete a report as possible to <gnu-crypto-discuss@gnu.org>.

Coding styles

New source files for this project should be written according to the GNU Coding Standards, with a few differences for Java.

Existing files are written according to these rules, and the two styles should not be mixed. If a change from the old style to the new is desired, then the entire file should be changed, and the formatting change should be checked in atomically.

These rules should be followed for ANT build.xml files.

Logos

In January 2003, GNU Crypto finally got, not one but two logos! At the heart of both logos, is the GNU+Keyhole figure.

IN HOC SIGNO TECTIS

This (brilliant) design idea, used with permission, is by Casey Marshall and is his copyright.

The long-square logo is for exclusive use by the GNU Crypto project; the circular one is for Users and System Integrators that include GNU Crypto in their product(s) and/or distributions.

Trademarks

All trademarks and registered trademarks are the property of their respective owner(s).

Return to GNU's home page.

Please send FSF & GNU inquiries & questions to gnu@gnu.org. There are also other ways to contact the FSF.

Please send comments on these web pages to webmasters@gnu.org, send other questions to gnu@gnu.org.

Copyright (C) 2001, 2002, 2003, 2004 Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.

Last Modified: $Date: 2006/05/31 16:59:20 $ $Author: rsdio $