-
Notifications
You must be signed in to change notification settings - Fork 33
Wizard
The Wizard was designed for easier access to special cryptographic scenarios for users that are not familiar with CT2. It also helps users to explore the CT2 functionality. Please keep that in mind before making changes to the plugin or its configuration and read the guidelines at first.
Please make sure the configuration meets the following criteria:
* Configure only one task per page so the page's content is not overloaded * Add a meaningful headline that fits to the task * Add explanatory descriptions * Configure icons that fit to the current page
Within the "Wizard" project in the CT2 solution, there exists the "Config" directory, which contains all the configuration files which can easily be altered and extended. They are written in a easily human readable XML format. For maintainability reasons, the configuration is split into many different files, each of which is related to a special cryptographic topic. The configuration files can be referenced in another file, to include it in the global wizard configuration tree. (If you want to add a new config file later, don't forget to set its "Build Action" to "Embedded Ressource") The starting point is represented by the "wizard.config.start.xml" file.
The wizard can be configured by setting up different "pages". The availability and content of these pages are described by special XML elements. Because of the tree-like nature of XML formats, the relations of wizard pages are also represented by a tree of pages, i.e. by nesting page decriptions.
There are mainly two different kind of pages: "category" and "input". While "category" represents a page, which gives the user the possibility to select amongst different given options (like: "Which one of these algorithms you want to use?"), the "input" page gives the possibility to let the user to fill in some kind of data, which will be used to set up a special workspace for him.
There is also another kind of page type, which is related to "input". This page type is called "sampleViewer" and is used to show the actual data of an underlying running workspace. For this reason, "sampleViewer" can be seen as some kind of output page. Another way to see it is to regard it as some kind of mask for an underlying workspace.
Another element, which conceptually stands on the same level as the above described pages, but which isn't a page in the real sense, is the "loadSample" element. As soon as the wizard user reaches a page like this, a given template file is opened in the workspace manager and is shown externally (i.e. outside of the wizard).
The nesting of different pages leads to special pathes, which directly serves the purpose of a given scenario. This means, that the different pages on this path can gather informations from the user, which are used in the last action of the path, which should always be the loading of a template and the filling of it with the user informations. This means, that a path should end with either an "loadSample" or an "sampleViewer" action.
The semantics of most wizard pathes is, that the user first has to select, which algorithm he wants to use (this selection is spread amongst many category pages). Then he has to fill in an input page, and in the last step, he sees the corresponding template in action.
Take a look at the "wizard.dtd" file to see which XML elements exists for the wizard configuration and how they relate to each other. This file is also used to check the config file on wizard startup. So, if you infringe with those rules, an error message will be thrown.
You can reference another xml config file by the "file" attribut. Take a look at the starting xml file, to see how this is used. An example is:
<file resource="Wizard.Config.Analysis.wizard.config.analysis.xml" />Please note that the resource string has to be given by this special resource path for technical reasons.
A standard page consists of a name, a description, a headline and a task (-description). The name and the description are some kind of meta informations for this pages, which are mainly used for giving these informations in the category page (i.e. the category page uses the name and description values of its child pages to let the user select amongst them) and for the path history. The headline and task values are directly used for the labeling of the page header itself. This values can be given in a translated way by declaring them multiple times with different language paramters:
<name lang="en" >Asymmetric Encryption</name>
<name lang="de" >Asymmetrische Verschlüsselung</name>
<description lang="en" >Selecting this allows you to analyze a ciphertext that was encrypted by a modern asymmetric algorithm. You can choose which asymmetric algorithm you want to use for doing this.</description>
<description lang="de" >Wählen Sie diesen Punkt, um einen chiffrierten Text, der mit einem modernen asymmetrischen Algorithmus verschlüsselt wurde, zu analysieren. Der dafür verwendete Algorithmus kann von Ihnen ausgewählt werden.</description>
<!-- This is the step's headline. It should be short, but precise. -->
<headline lang="en" >Algorithm Selection</headline>
<headline lang="de">Algorithmusauswahl</headline>
<!-- This is the step's description. -->
<task lang="en" >Select an asymmetric encryption/decryption algorithm.</task>
<task lang="de" >Wählen Sie einen asymmetrischen Verschlüsselungs-/Entschlüsselungsalgorithmus.</task>Additionally, the pages have an "image" attribute, which is used to assign an icon to them. this icon will be shown in the path history and in the category selections. You have to give the resource name of an image file that is already integrated in the project for this attribute:
<category image="Wizard">Now follows a detailed description of the usage of the important elements.
A category page is a standard page, which content consists of some other pages. By this, it gives the user the possibility to select one of those different pages. An easy example for a category page with two input pages that can be selected:
<category image="Classic">
<name lang="en" >Classic Encryption</name>
<name lang="de" >Klassische Verschlüsselung</name>
<description lang="en" >Selecting this allows you to analyze a ciphertext that was encrypted by a classic algorithm. You can choose which classic algorithm you want to use for doing this.</description>
<description lang="de" >Wählen Sie diesen Punkt, um einen chiffrierten Text, der mit einem klassischen Algorithmus verschlüsselt wurde, zu analysieren. Der dafür verwendete Algorithmus kann von Ihnen ausgewählt werden.</description>
<!-- This is the step's headline. It should be short, but precise. -->
<headline lang="en" >Algorithm Selection</headline>
<headline lang="de">Algorithmusauswahl</headline>
<!-- This is the step's description. -->
<task lang="en" >Select a classic encryption algorithm.</task>
<task lang="de" >Wählen Sie einen klassischen Verschlüsselungsalgorithmus.</task>
<!-- Caesar input (page 1) -->
<input image="Caesar">
<name lang="en" >Caesar</name>
...
</input>
<!-- Vigenère input (page 2) -->
<input image="Vigenere">
<name lang="en" >Vigenère</name>
...
</input>
</category>The input page is a standard page which can contain exactly one child page element. This child page is the page that is shown in the next step. In addition to the standard page elements, an input page can declare some input elements, which are used to give the user the possibility to influence the underlying template data. There are three kinds of input elements:
* inputBox * comboBox * checkBox
These input elements have special style attributes, which can be used to determine the layout of them on the input page. They have the property "alignment", which can be set to "right", "left", "center" or "stretch". Another property is "width", which can either be set to a pixel size (like "10") or a percentage of the available space (like "10%"). Additionally, these input elements have the attribute "group", which is used to group several elements together, so that they will be layouted in the same horizontal line.
Beside these standard style attributes, there are some more which are special to the special kinds of input elements. For inputBox, there exists the "visibleLines" attribute, which determines which height the element should have. The "presentation" element (see next section below) has the "height" attribute, which determines the height of it (measured in pixel or in percentage).
Beside those style attributes, the inputBox element can be given a "regex" attribut, which determines, which input by the user should be allowed. Again, take a look at the wizard.dtd file to get a good overview of the available elements and attributes.
The following sample shows how to use inputBox and comboBox:
<input image="Caesar">
<name lang="en" >Caesar</name>
<description lang="en" >
Caesar is a classic algorithm to encrypt plaintext or to decrypt ciphertext.
By selecting this, you can analyze some ciphertext that was encrypted with the Caesar algorithm.
</description>
<description lang="de" >
Caesar ist ein klassischer Algorithmus zum Verschlüsseln von Klartext oder Entschlüsseln von chiffrierten Text.
Wählen Sie diesen Punkt, um einen mit dem Caesar-Algorithmus verschlüsselten Text zu analysieren.
</description>
<headline lang="en">Caesar Analysis</headline>
<task lang="en">Please input the ciphertext and text language.</task>
<task lang="de">Bitte geben Sie den chiffrierten Text ein und wählen die Textsprache aus.</task>
<inputBox plugin="Ciphertext" property="Text" alignment="Stretch" visibleLines="5">
<description lang="en">Ciphertext:</description>
<description lang="de">Chiffrierter Text:</description>
<defaultvalue>Place your default value for the inputbox here.</defaultvalue>
</inputBox>
<comboBox plugin="CaesarAnalysisHelper" property="TextLanguage" defaultValue="0" width="20%" alignment="Left">
<description lang="en">Language of the cleartext message:</description>
<description lang="de">Sprache der Klartext-Nachricht:</description>
<item content="German" lang="en"/>
<item content="English" lang="en"/>
<item content="French" lang="en"/>
<item content="Spanish" lang="en"/>
</comboBox>
<sampleViewer image="Caesar" file="Cryptanalysis\Classic\Caesar_Analysis.cwm">
<---- This is the next page ---->
</sampleViewer>
</input>As can be seen in this sample, every input element has a description (which can be given in multiple languages). Also, it has a "plugin" and a "property" attribute. These refer directly to the plugins contained in the template file which will be loaded in the next steps. So, the inputBox element in the example above will set the "Text" property of the plugin named "Ciphertext" to the value given by the user.
It is not so easy to find out, which property you want to set. In order to do this, you have to take a look at the sourcecode of the corresponding plugin. The property attribute references the properties in the main plugin class as well as the properties in the corresponding settings class.
A sampleViewer page has a lot of similarities to the input page. The difference is, that you must proviede a sampleViewer page with a template file. This file will be loaded and run (in the background) as soon as the sampleViewer page is activated. You can use the above described input elements (with the same syntax) to give the user the possibility to watch the current values of the properties of the running plugins. Also, they can be used to give the user the possibility to alter these values. A typical example for this is to let the user alter the value of an input plugin, so that the workspace is evaulated again (take a look at the caesar encryption wizard page to see how this works).
Additionally, a sampleViewer can be provided with an "outputBox" and a "presentation" element. While the outputBox element is just the same as the inputBox element, just in a readonly version, the "presentation" element is something new. It allows you to put the individual presentation of a given plugin from the running template on the sampleViewer page. An example for how to use this is:
<presentation plugin="QuadraticSieve" width="80%" height="80%">
<description lang="en">Factorization:</description>
<description lang="de">Faktorisierung:</description>
</presentation>This is the easiest element, which can be used like a page element (although it isn't a page). It simply loads a given template file in an external workspace manager instance. Example:
<loadSample title="Enigma Analyser" file="Cryptanalysis\Classic\Enigma_Analyzer.cwm"/>You can check the consistency of the wizard config files (i.e. the correctness of the syntax and the cooperation between the referenced plugin properties and the underlying templates) by running a unit test. This unit test can be found in the WizardConfigTest class in the DevTestMethods project. Visual Studio allows you to simply run the unit test by clicking on the intended button.
In this section possible improvements according to a user survey result will be listed soon...