Subsections

3. Using Ganzúa

This chapter explains Ganzúa's interface, how it is divided and shows how to use the features present for all of the supported ciphers.

To better understand the way the program works, you should open Ganzúa and try the features described in this chapter as you read them.

3.1 Interface

The following screenshots show the way Ganzúa's main window looks3.1 on the platforms it has been tested and is known to work in (see section 2.2).

The labels on the images stand for:

  1. Title bar
  2. Menu bar
  3. Main panel and ciphertext statistics tabs
  4. Cipher selection area
  5. Cipher specific tools area
  6. Substitution area
  7. Ciphertext and plaintext area
 
Figure: Ganzúa running on Mac OS X using the Aqua look and feel
Mac OS X screenshot
 
Figure: Ganzúa running on GNU/Linux using the Java look and feel
Linux screenshot
 
Figure: Ganzúa running on Windows XP using the Windows look and feel
Windows screenshot

3.2 Title and Menu Bars

The title bar displays the name of the file the cryptanalysis project you are working on is in. If you have not saved the project, then Untitled is displayed.

The menu bar has five menus, which are not the same for all platforms. The Ganzúa menu (available only in Mac OS X) contains program related options, like About, which displays information about this version of Ganzúa. On the rest of the platforms, About is in the Help menu, which is the only option that menu has, and that is the reason why it is not displayed in Mac OS X. Since almost every platform handles help documents its own way and Ganzúa is not targeted towards any platform in particular, but tries to address as many as possible; the help documents like this manual are provided in standard formats, like HTML and PDF, that you can read on your platform of choice. The only assistance that is provided in the program itself are tool-tips, that appear when the cursor is left over an item for an extended period of time.

The following sections explain the options in the menus that appear on all platforms.

  
3.2.1 File Menu

Open

Lets you open a cryptanalysis project. You used this option back in section 2.3 to test your installation of Ganzúa.

Try:
Open the file BoerWar.xml, that can be found at GANZÚA_HOME/examples/projects/en where GANZÚA_HOME stands for the directory Ganzúa was installed to.

Open Ciphertext

Lets you open a cryptogram from a text file. When you choose this option, a dialog appears. This dialog lets you select a text file and the encoding used by the text file. The encoding defines a character set and the relationship between the characters and their representations in the file. If you don't know which encoding is used in your text files, probably you are using your system's default, which is automatically selected each time Ganzúa starts up.

Note that if you change the selected encoding, that change will remain until you quit Ganzúa or select a different encoding and will affect the rest of the text file related dialogs (those used by Save Ciphertext and Save Plaintext, explained later in this section).

Try:
Open a text file, like Ganzúa's license which is the file named COPYING in the directory Ganzúa is installed in. If you opened BoerWar.xml as suggested previously, note how the contents of the substitution area change, the character substitutions are cleared and the name in the title bar changes to Untitled.
Important:
Ganzúa was written to be used as a tool in an introductory cryptology course and is not meant to handle documents larger than a couple of pages long.

Open Language

Lets you open a file with a language's standard relative frequencies of characters, bigrams and trigrams. These files are typically stored in Ganzúa's frequencies folder (see section 2.4.1). By convention the first two letters of the frequencies files' name are the ISO 639 code of the language.

When you open a language, you define the plain alphabet, the way characters (in both the cipher and plain alphabet) are ordered and the data to be displayed in the Language Stats window (see section 3.2.4).

Important:
When you open a language, the previous plain alphabet is discarded and so are any selected character substitutions.
Important:
When you open a ciphertext file, the language data you were using previously in this session, if any, will remain until you open a new language or cryptanalysis project file.

Save

This option lets you save the cryptanalysis project you are working on to a file similar to the BoerWar.xml file mentioned earlier in this section. If the project has previously been saved or was opened from a file, the data on that file is updated.

The data saved includes the cipher selected in the cipher selection area, the language data (including character, bigram and trigram frequencies) if any, the substitution and the ciphertext.

Save As

Lets you save the current project to a different file.

Save Ciphertext

With this option you can save the project's ciphertext (the cryptogram) to a text file. When you choose this option, a dialog similar to the one displayed by Open Ciphertext appears. From this dialog you can choose the encoding to be used in the file. As with Open Ciphertext's dialog, if you change the selected encoding, this will change it on the rest of the text file related dialogs as well (those used by Open Ciphertext and Save Plaintext).

Save Plaintext

Lets you save the project's plaintext (the text that results from applying the substitution to the cryptogram) to a text file. As with Save Ciphertext and Open Ciphertext, a dialog that lets you select the file's encoding will appear and any changes to the selected encoding will be reflected in those dialogs as well.

  
3.2.2 Edit Menu

Copy

Copies the selected text from the ciphertext and plaintext area. If you wish to copy selections from other places, like tables from the Language Stats window or the ciphertext statistics, use the keyboard shortcut displayed next to this option (for example, Command-C in Mac OS X) after making the selection. You can also drag your selection and drop it where you want it copied to. Note that some programs do not support drag and drop operations.

Add Characters To Cipher Alphabet

When you open a cryptogram from a text file (see section 3.2.1) the cipher alphabet is obtained from its characters. But most of the times, the files do not have occurrences of characters that appear in the cipher alphabet you want to use. For example if the letter Z is not used in the text file, the cipher alphabet generated when the file is opened will not include it.

Important:
New line, space and control characters are considered special by Ganzúa and can not be part of the cipher or plain alphabets, any other character is valid.

To include the characters missing from the cipher alphabet, enter them one at a time3.2 in the dialog that is displayed when you choose this option (figure [*]). The dialog's Cancel button closes the dialog and cancels the addition of the character being displayed in the text field.

  
Figure: Add Characters to the Cipher Alphabet dialog
Add Characters to the Cipher Alphabet dialog
Try:
If you open the BoerWar.xml project and click on the ciphertext statistics tab, you will be able to see that the characters W and G do not occur in the cryptogram and were added to the cipher alphabet using this command. Click on the Main tab, to go back to the main panel and add some lowercase letters to the cipher alphabet.

Add Characters To Plain Alphabet

If the language frequencies files available do not contain the plain alphabet you want to use, or are missing some character, you can add them by choosing this option. Note that this is for substitution purposes only. You will not get the benefits you get when your plain alphabet comes from a language frequencies file, like the relative frequencies of the characters. How to make your own language frequencies files is explained later in the manual.

To include characters, enter them one at a time, just like you would if you were adding them to the cipher alphabet.

Remove Characters From Cipher Alphabet

This option lets you remove characters from the cipher alphabet and cryptogram. When you select this option, a window with a list of the characters in the cipher alphabet is displayed. After selecting3.3 the characters you want to remove, press the Remove button, this will remove the characters from the cipher alphabet and any occurrence of these in the ciphertext.

Important:
Ganzúa does not include an undo command, so be careful when you perform operations like removing characters, and save your work often.
Try:
Open the BoerWar.xml project and remove the punctuation characters.

Group Characters

Lets you group the cryptogram's characters in blocks separated by space characters. This is one of the reasons the space character is considered special and can not be part of the cipher alphabet. If it were, this operation would alter the relative frequencies of the cryptogram.

Try:
Group the ciphertext characters of the project BoerWar.xml

Uppercase Ciphertext

Converts all the characters in the ciphertext to uppercase. This operation is equivalent to opening a new cryptogram with an uppercased version of the ciphertext. This means that you will lose all the character substitution information, including characters you added to the cipher alphabet. If the current project's ciphertext is already made up of uppercase characters exclusively (like BoerWar.xml), then this command will not do anything to the current project.

Lowercase Ciphertext

Converts all the characters in the ciphertext to lowercase. Like Uppercase Ciphertext, this operation is equivalent to opening a new cryptogram with a lowercased version of the ciphertext, so you will lose all the character substitution information. If all of the project's ciphertext characters are lowercase, then this command will do nothing to the current project.

Set Plaintext as Ciphertext

Sets the project's plaintext as the ciphertext. This operation is equivalent to opening a ciphertext file that contains this project's plaintext. Like in the cases of Uppercase Ciphertext and Lowercase Ciphertext, this means you will lose all the character substitution information, including the characters added to the cipher alphabet.

This command may be useful if you are using Ganzúa to cipher text instead of cryptanalyzing it.

Try:
Open the BoerWar.xml project and use this command.

3.2.3 View Menu

This menu contains options that change the way the ciphertext and plaintext area displays its contents. You can access these options from a contextual menu that you can trigger on this area (with a Control-click in Mac OS X or a right-click on other platforms, for example).

 
Figure: Ciphertext area contextual menu
Contextual menu

Intercalated

In this mode, the ciphertext's lines are displayed with the corresponding plaintext line immediately under.

Separated

In this mode the ciphertext and plaintext are displayed in separate areas.

  
3.2.4 Window Menu

This menu lets you display Ganzúa's secondary windows.

Show Language Stats

Displays the Language Stats window, which contains tables with the language's standard relative frequencies of characters, bigrams and trigrams. These frequencies correspond to those in the language file that was opened most recently, if no language file has been opened, then this window contains no data.

The data presented in the tables can be sorted alphabetically or by frequency by clicking on the tables' header. For example, if you are looking at the table with the relative frequencies of the characters and click on the label of the column with the characters, the data will be ordered alphabetically and if you click on the label of the frequencies column the data will be ordered by frequency from the most frequent to the least. The data can also be displayed in reverse order by doing a Shift-click instead of a click on the labels.

Try:
Open the BoerWar.xml project and sort the language statistics.

Show Ignored Characters

Displays the characters from the cipher alphabet that are being ignored. How to set a character as ignored and what this means is explained in section 3.3.

  
3.3 Substitution Area

  
Figure: Substitution area
Substitution Area

The substitution area is the section of Ganzúa that displays the relation between the characters in the cipher alphabet and those in the plain alphabet. It contains a region with character substitution elements, a checkbox that handles whether to enforce one-to-one substitution, a button that opens the Ignored Characters window and a control that lets the user select the substitution to be displayed, using the number of the alphabet it belongs to (enabled only for polyalphabetic ciphers).

Each character substitution element displays the character from the cipher alphabet to be replaced at the top, to the right there is a button that allows the user to add it to the set of ignored characters and at the bottom a combo box used to select a replacement character from those in the plain alphabet.

When a character is ignored, it is almost as having it removed from the cryptogram and cipher alphabet. The relative frequencies of the ciphertext are calculated as if those characters did not exist, they are removed from the substitution area, but they are included in the plaintext as they appear in the ciphertext. For example in the project BoerWar.xml the punctuation marks are ignored.

The checkbox sets whether the substitution is forced to be injective (one-to-one) or not. If it is checked, the user is allowed to choose a replacement character only among those in the plain alphabet that have not been selected as replacements already, otherwise all the characters in the plain alphabet are available.

The button labeled Ignored works like Show Ignored Characters in the Window menu, it opens the window that displays the cipher alphabet characters being ignored and lets the user remove them from that set.

3.4 Ciphertext Statistics Panel

The ciphertext statistics panel contains the cryptogram's index of coincidence, tables with its character's relative frequencies and an estimate of the number of alphabets used in the cipher to obtain the ciphertext.

The estimate of the number of alphabets is obtained using the index of coincidence of the cryptogram and that of the language. If the language's index of coincidence is not available, or if the number of characters in the cipher alphabet is greater than that of the language's, no estimate will be shown.

Try:
Open the BoerWar.xml project, see the number of alphabets estimate, add the characters in the Ignored Characters window and check the estimate again.

The relative frequencies tables contain different data depending on the chosen cipher. In the case of monoalphabetic ciphers the tables show the relative frequencies of characters, bigrams and trigrams, while for polyalphabetic ciphers, the relative frequencies of the characters ciphered with each alphabet is displayed.

 
Figure: Cryptogram statistics (monoalphabetic)
Cryptogram statistics (monoalphabetic)
 
Figure: Cryptogram statistics (polyalphabetic)
Cryptogram statistics (polyalphabetic)
Try:
Open the BoerWar.xml project, and click on the Stats tab to pen the ciphertext statistics panel. Now open the main panel and select one of the polyalphabetic ciphers from the cipher selection area. Open the ciphertext statistics panel again and note the changes.
Remember:
The contents of the tables can be sorted alphabetically or by frequency as explained in section 3.2.4. The contents of the tables may be copied (e.g., to a spreadsheet) by selecting and doing a drag-and-drop of your selection or using the keyboard shortcut (see section 3.2.2). To select all of the entries in the table you can use your platform's conventional keyboard shortcut, for example Command-A in Mac OS X or Control-A in GNU/Linux.

3.5 Cipher Selection and Tools Area

The cipher selection area lets the user choose the cipher specific tools he wants to use for his cryptanalysis project, whether one or more alphabets will be used and the information that will be displayed in the ciphertext statistics panel.

 
Figure: Cipher selection and tools area
Cipher selection and tools area

3.5.1 Monoalphabetic

Ganzúa has two groups of tools for monoalphabetic ciphers: the group for monoalphabetic ciphers in general and those for the Caesar cipher.

Caesar Cipher Tools

The kind of substitution in which the alphabet is simply shifted a number of positions is called the Caesar cipher or Caesar shift cipher. In Ganzúa, the tools to solve cryptograms obtained using this method are in the Caesar category. A description of the buttons in the tools area for the Caesar cipher is given next.

Clear:
Clears the replacement characters from the selection.
Identity:
Clears the current substitution and selects one as close to the identity as possible. This is, if the plain alphabet contains the character from the cipher alphabet, that character is chosen, if the character is not in the plain alphabet, but the upper/lowercased character is, then that character is assigned as the substitution.
Complete:
Arbitrarily assigns substitution characters to the characters for which they have not been selected. The replacements are selected from those in the plain alphabet that have not been chosen. The substitution characters are selected in alphabetical order.
Reverse:
Takes the current substitution and reverses the order in which the replacement characters appear. In other words, the character that replaces the first character in the cipher alphabet will be the replacement of the last, etc.
Invert:
Select a substitution as close to the inverse of the current as possible. Takes those cipher alphabet characters that are in the plain alphabet too and whose substitution characters are in the cipher alphabet as well, and inverts the relation (sets the character being substituted as the substitution and the substitution as the substituted). The upper and lower case characters are considered the same way the Identity button does.
Shift:
This control lets you shift the substitution characters to the left or right.
Try:
Open the project BoerWar.xml and click the Clear button. If you don't know or remember why the punctuation symbols remain, read section 3.3. Now click the Identity button and shift the selection to the right three positions. This is the substitution that was used to get the cryptogram, so if you click the Invert button you'll get the original text.

Monoalphabetic Cipher Tools

The tools for monoalphabetic ciphers in general, are the same as those available for the Caesar cipher, except that the shift tool is not available.

If you are working in this mode and find that you need to use the shift tool, select Caesar from the cipher selection area. None of your data will be lost. The same holds for changing from Caesar to Monoalphabetic.

3.5.2 Polyalphabetic

When you choose a polyalphabetic cipher, a control labeled Num. Alphabets will appear at the top of the the cipher specific tools section. That control lets you select the number of alphabets to use in the cipher. Do not confuse the function of this control with the one in the substitution area, that is used to select the substitution to be displayed, using the number of the alphabet it belongs to.

Ganzúa has two groups of tools for polyalphabetic ciphers: the group for the Vigenère cipher and the one for the Alberti cipher.

Vigenère Cipher Tools

In the Vigenère cipher, each alphabet used differs from the others only by a shift, so many of the tools provided for this cipher are similar to those of the Caesar cipher.

Open the project WHeights.xml, see how the different sections of Ganzúa look for polyalphabetic ciphers (like the substitution area, the ciphertext statistics, etc.) and test what the tools for the Vigenère cipher do as you read their descriptions bellow.

Num. Alphabets:
This tool lets you select the number of alphabets to work with and is available for all of the polyalphabetic ciphers.
Kasiski:
Performs the Kasiski test. Finds all the repeated character sequences of length two or more in the cryptogram, the number of times they appear, the distance between occurrences and the prime factors of those distances. Once the test has been finished, the Kasiski Test Results window is opened and the data is presented in a table. The data may be sorted by length of sequence or frequency by clicking on the column headers.
 
Figure: Kasiski Test Results window
Kasiski Test Results window
Group:
Groups the cryptogram's characters in blocks separated by space characters, just like the Group Characters in the Edit menu.
Subst 1:
Copies the substitution for alphabet 1 to the currently selected alphabet.
Clear:
Clears the current alphabet's substitution.
Identity:
Clears the current alphabet's substitution and selects one as close to the identity as possible, just like the monoalphabetic version.
Complete:
Arbitrarily assigns substitution characters to the characters for which they have not been selected in this alphabet, just like its monoalphabetic counterpart.
Reverse:
Takes the current alphabet's substitution and reverses the order in which the replacement characters appear.
Invert:
Select a substitution as close to the inverse of the current alphabet's as possible, just like its monoalphabetic counterpart.
Shift:
Shift this alphabet's substitution characters to the left or right.

Alberti Cipher Tools

The tools for the Alberti cipher, are the same as those available for the Vigenère cipher, except that the shift tool is not available.

If you are working in this mode and find that you need to use the shift tool, select Vigenère from the cipher selection area. None of your data will be lost. The same holds for changing from Vigenère to Alberti.

Important:
When you change from a polyalphabetic cipher to a monoalphabetic cipher all the substitutions but the one for the first alphabet will be lost.

3.6 Language and Country Settings

By default, Ganzúa will use your platform's preferred language and country conventions on its interface. If that language is not supported yet3.4, English will be used.

If you want Ganzúa to use some other language or country settings than the defaults and without changing your defaults, you may specify them as command line options. In order to do this you'll have to run Ganzúa from a command line terminal.

For example, to run the program in Spanish with Mexico's conventions you would use the command:

java -jar GANZÚA_HOME/ganzua.jar -l es -c MX

Where GANZÚA_HOME is the directory Ganzúa was installed to. -l is used to specify the language using its ISO 639 code and -c sets the country conventions using the countries two character ISO 3166 code. You do not have to use both arguments, you may use -l and omit -c and vice versa.

In Mac OS X you may set this arguments in the application package. To do this, open the file Info.plist with a text editor and insert the following two lines in line 29, under <string>1.4+</string>.

<key>Arguments</key>
<string>-l es -c MX</string>

Replace es and MX with the codes for the language and country you want to use. As with the command line, you may use -l or -c by themselves.

3.7 Important Things to Consider

This section lists some things you should keep in mind when using Ganzúa in addition to the bits pointed out previously.

When you open a cryptogram from a text file, the cipher alphabet is obtained from the characters that appear in it and are not considered special characters3.5. The first thing you should do after opening the cryptogram is to check that the cipher alphabet contains all the characters you want to use and only those, since most of the times the files lack characters you want. Failure to do this may unnecessarily complicate the cryptanalysis process. For information on how to add, remove or ignore cipher alphabet characters, read sections 3.2.2 and 3.3.

If you plan to use Ganzúa for polyalphabetic ciphers, you should also remember that the results of the Kasiski Test include every sequence of characters of length two or more that is repeated in the ciphertext. This means that all the subsequences of up to length two are included in the results. So, for example, if you see the sequence ABCDE with frequency of 2 among the results and the sequence BCD with frequency 3, then two of those are subsequences of the ABCDE sequences.

Check Ganzúa's home page ( http://ganzua.sourceforge.net ) for updates, bug fixes and answers to frequently asked questions. Also read chapter 5 for information on how to contact the author, should you find any bugs, errors in the documentation, etc.



Footnotes

... looks3.1
The program may have a different appearance, depending on the value of the JRE's default Look And Feel.
... time3.2
Type in the character and press the Enter key or the Add button.
... selecting3.3
To select more than one character, use the conventional keys used to add items to selections on your platform. For example Shift-click .
... yet3.4
As of version 1.01 Ganzúa supports only two languages: English and Spanish.
... characters3.5
Spaces, line breaks and control characters are considered special characters.
Jesús Adolfo García Pasquel 2004-10-04