Part I: Java Coding Exercise (Command Line)

From Notes

Jump to: navigation, search

Contents

Introduction

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.

Image:hcryptoUML.png

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 AffineEngine.java
-rw-r--r--  1 rmorelli  rmorelli   4606 Nov 12  2009 AffineKey.java
-rw-r--r--  1 rmorelli  rmorelli   4489 Nov  4  2009 CaesarEngine.java
-rw-r--r--  1 rmorelli  rmorelli   4391 Dec  8  2009 CaesarKey.java
-rw-r--r--  1 rmorelli  rmorelli   1571 Oct 29  2009 NullEngine.java
-rw-r--r--  1 rmorelli  rmorelli   1714 Oct 29  2009 NullKey.java
-rw-r--r--  1 rmorelli  rmorelli   6585 Nov  4  2009 PlayfairEngine.java
-rw-r--r--  1 rmorelli  rmorelli   9698 Dec  3  2009 PlayfairKey.java
-rw-r--r--  1 rmorelli  rmorelli   7168 Nov  4  2009 PolySubstitutionEngine.java
-rw-r--r--  1 rmorelli  rmorelli   9514 Dec  8  2009 PolySubstitutionKey.java
-rw-r--r--  1 rmorelli  rmorelli   6290 Nov  4  2009 RailfenceEngine.java
-rw-r--r--  1 rmorelli  rmorelli   2848 Nov 12  2009 RailfenceKey.java
-rw-r--r--  1 rmorelli  rmorelli   4218 Nov  4  2009 SubstitutionEngine.java
-rw-r--r--  1 rmorelli  rmorelli  10236 Dec 13  2009 SubstitutionKey.java
-rw-r--r--  1 rmorelli  rmorelli   5349 Nov  4  2009 TranspositionEngine.java
-rw-r--r--  1 rmorelli  rmorelli   3802 Nov 12  2009 TranspositionKey.java
-rw-r--r--  1 rmorelli  rmorelli   5694 Nov  4  2009 VigenereEngine.java
-rw-r--r--  1 rmorelli  rmorelli   4381 Nov  4  2009 VigenereKey.java

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 CaesarEngine.java
-rw-r--r--  1 rmorelli  rmorelli  4383 Dec 13  2009 CaesarKey.java
-rw-r--r--  1 rmorelli  rmorelli  2633 May 17 14:47 PluginProvider.java

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/CaesarKey.java src/plugins/NullKey.java
    $ cp src/plugins/CaesarEngine.java src/plugins/NullEngine.java
    
  2. Edit Provider.java by adding an entry for your Null cipher to its constructor. It should look like this when you are done:
        public PluginProvider(String name) {
            this.name = name;
            put("Caesar", "plugins.CaesarEngine","plugins.CaesarKey"); 
            put("Null", "plugins.NullEngine","plugins.NullKey"); 
        }
    
  3. Edit NullEngine.java and NullKey.java and do a global replace of the word Caesar with Null.
  4. Make the following edits to NullEngine.java:
    • 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 NullKey.java':
    • 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