Part I: Java Coding Exercise (Command Line)

From Notes

Jump to: navigation, search



HcryptoJ is Java API for historical cryptology. It contains classes for simple ciphers, such as Caesar cipher and Vigenere cipher, and analysis tools for breaking ciphers, such as Caesar analyzer.

In this exercise, we will download HcryptoJ from Sourceforge and make changes to its codebase.

Read this overview of HcryptoJ.

For the tutorial portion of this exercise we will work together as a whole group. However, for exercises 1 and 2, we will break up into small teams.

Getting Started Tutorial

  1. Set up a working directory named hcryptoj-hg-repo for this project and download the HcryptoJ source code into your directory.
  2. Extract the source code from the jar file:
    $ cd hcryptoj-hg-repo
    $ jar xvf hcrypto-hg-repo.jar
  3. This will set up the following directory structure:
    $ ls -al
    total 6552
    drwxr-xr-x   12 rmorelli  rmorelli      408 May 18 06:44 .
    drwxr-xr-x@ 219 rmorelli  rmorelli     7446 May 18 06:43 ..
    drwxr-xr-x   12 rmorelli  rmorelli      408 May 18 06:37 .hg
    -rw-r--r--    1 rmorelli  rmorelli      367 Nov  5  2009 .project
    -rw-r--r--    1 rmorelli  rmorelli    35147 Dec  8  2009 LICENSE.txt
    drwxr-xr-x    3 rmorelli  rmorelli      102 May 18 06:37 META-INF
    -rw-r--r--    1 rmorelli  rmorelli     3829 May 18 06:36 README.txt
    -rw-r--r--    1 rmorelli  rmorelli      742 May 17 15:31 build.xml
    drwxr-xr-x    6 rmorelli  rmorelli      204 May 17 15:36 classes
    drwxr-xr-x    7 rmorelli  rmorelli      238 May 17 10:32 data
    -rw-r--r--@   1 rmorelli  rmorelli  3303390 May 18 06:41 hcryptoj-hg-repo.jar
    drwxr-xr-x    6 rmorelli  rmorelli      204 May 17 15:28 src

    The Java source code is stored in src and the executable Java code is in classes. Notice the hidden files -- the .project file is the configuration file for Eclipse and the .hg file is a configuration file for Mercurial

  4. Try running TestCipher from the command line. The following command will encrypt a short command-line message using a Caesar cipher:
    // Usage: 
    //java        classpath          TestCipher           algorithm    keyspec        plaintext message [-d]
    $ java -classpath ./classes/ applications.TestCipher   Caesar    5/az+AZ/az+AZ  "This is a test of Caesar"

    The keyspec, short for key specification, specifies the Caesar shift (5), followed by the plaintext and ciphertext alphabets. In this case, az+AZ means that the cipher engine will encrypt and decrypt only lower and upper case letters. The optional -d option is used to perform a decryption.

  5. Try running FileCipher from the command line:
    // Usage: java FileCipher cipher keyspec -e|-d infile outfile [encoding]
    $ java -classpath ./classes applications.FileCipher Substitution keyword/ascii/ascii -e README.txt README.encrypted.txt
    $ java -classpath ./classes applications.FileCipher Substitution keyword/ascii/ascii -d README.encrypted.txt README.decrypted.txt
  6. Play around with CryptoToolJ, a GUI interface.
    $ java -classpath ./classes applications.cryptotoolj.CryptoToolJ &

    Things to try:

    • Try encrypting and decrypting the README.txt: File > Open > Select Substitution Cipher and specify a key.
    • Create a cipher engine: File > New Cipher > Select Cipher and specify the key.
    • Use a plugin cipher: File > New Cipher > Select a plugin cipher and use it
    • Encrypt a file with Caesar cipher and then try to break it with Caesar Analyzer (under Analysis).

HcryptoJ Design Details

The following UML diagram shows the top-level classes of the HcryptoJ hierarchy. Every cipher consists of two basic components, a cipher engine, which implements the encryption and decryption algorithms, and a cryptographic key, which contains the secret data used by the engine. To create a new cipher, you only need to define subclasses of BlockCipher and HistoricalKey.


One way to extend HcryptoJ would be to add to its code base by defining a new cipher and adding it to HcryptoJ's hierarchy. You can see what ciphers come with the package by listing the engines directory:

109add49afd3:hcrypto-download rmorelli$ ls -l src/hcrypto/engines/
total 280
-rw-r--r--  1 rmorelli  rmorelli   5966 Nov 12  2009
-rw-r--r--  1 rmorelli  rmorelli   4606 Nov 12  2009
-rw-r--r--  1 rmorelli  rmorelli   4489 Nov  4  2009
-rw-r--r--  1 rmorelli  rmorelli   4391 Dec  8  2009
-rw-r--r--  1 rmorelli  rmorelli   1571 Oct 29  2009
-rw-r--r--  1 rmorelli  rmorelli   1714 Oct 29  2009
-rw-r--r--  1 rmorelli  rmorelli   6585 Nov  4  2009
-rw-r--r--  1 rmorelli  rmorelli   9698 Dec  3  2009
-rw-r--r--  1 rmorelli  rmorelli   7168 Nov  4  2009
-rw-r--r--  1 rmorelli  rmorelli   9514 Dec  8  2009
-rw-r--r--  1 rmorelli  rmorelli   6290 Nov  4  2009
-rw-r--r--  1 rmorelli  rmorelli   2848 Nov 12  2009
-rw-r--r--  1 rmorelli  rmorelli   4218 Nov  4  2009
-rw-r--r--  1 rmorelli  rmorelli  10236 Dec 13  2009
-rw-r--r--  1 rmorelli  rmorelli   5349 Nov  4  2009
-rw-r--r--  1 rmorelli  rmorelli   3802 Nov 12  2009
-rw-r--r--  1 rmorelli  rmorelli   5694 Nov  4  2009
-rw-r--r--  1 rmorelli  rmorelli   4381 Nov  4  2009

You can also create your own cipher and add it as a plugin. Plugins must be defined in the plugins package and added to the src/plugins folder. Currently, the plugins folder contains a Caesar cipher as an example:

109add49afd3:hcrypto-download rmorelli$ ls -l src/plugins/
total 40
-rw-r--r--  1 rmorelli  rmorelli  4481 Dec 13  2009
-rw-r--r--  1 rmorelli  rmorelli  4383 Dec 13  2009
-rw-r--r--  1 rmorelli  rmorelli  2633 May 17 14:47

In addition to the CaesarEngine and CaesarKey classes, it is necessary to add an entry for your plugin to the PluginProvider class. This is how the CryptoToolJ application finds new ciphers and loads them into its memory.

Exercise: Create a Null Cipher Plugin

Follow these steps to create a Null cipher.

  1. Make a copy of CaesarEngine and CaesarKey and rename them to NullEngine and NullKey respectively, saving them both in the plugins directory.
    $ cp src/plugins/ src/plugins/
    $ cp src/plugins/ src/plugins/
  2. Edit by adding an entry for your Null cipher to its constructor. It should look like this when you are done:
        public PluginProvider(String name) {
   = name;
            put("Caesar", "plugins.CaesarEngine","plugins.CaesarKey"); 
            put("Null", "plugins.NullEngine","plugins.NullKey"); 
  3. Edit and and do a global replace of the word Caesar with Null.
  4. Make the following edits to
    • Modify the engineEncode() and engineDecode() methods, which perform the actual encryption transformations, so that they perform no transformation of the input text:
          public String engineEncode(String s ) throws Exception {
                 return s;
          public String engineDecode( String s ) throws Exception {
                  return s;
  5. Make the following edits to':
    • Modify the DEFAULT_KEY_DESCRIPTOR_PROMPT_STRING to be whatever you like. It will basically be ignored in Null cipher.
       public final static String DEFAULT_KEY_DESCRIPTOR_PROMPT_STRING = "whatever";
    • Modify the DEFAULT_KEYWORD_STRING to be whatever you like. It will basically be ignored in Null cipher.
       public final static String DEFAULT_KEYWORD_STRING = "blah";
    • Modify the init() method to remove any references to the Caesar shift. It should look like this when you're done:
          public void init(String keyspec) throws Exception {
              initKey(keyspec, false); // Inherited from superclass                                                                                                                                                   
              this.blocksize = 1;
  6. Compile the Java files that you created or modified. The following command from the main hcryptoj directory will compile the files and place the classes in the correct package folder (-d .)"
    $ ant build
  7. Run CryptoToolJ from the main hcrypto directory. It should now include the Null Cipher you created.
    $java -classpath ./classes applications.cryptotoolj.CryptoToolJ &

In the next tutorial we will add the new files we've created and commit our changes to the Mercurial repository.

Personal tools
NSF K-12