Developer HowTo

1. Developer Guidelines

CrypTool 2 is built using .NET and the Windows Presentation Foundation (WPF). Before you can start writing code and adding to the development of the project, a few things need to be considered. To make this process easier, please read through this document and follow the instructions closely. This document exists to help get you started by showing you how CrypTool 2 plugins are built in order to successfully interact with the application core. We have tried to be very thorough, but if you encounter a problem or error that is not described here, please let us know. Not only do we want to help get you up and running, but we also want to add the appropriate information to this guide for the benefit of other future developers.

In this first chapter we will describe all steps necessary in order to compile CrypTool 2 on your own computer. This is always the first thing you need to do before you can begin developing your own plugins and extensions. The basic steps are:

• Getting all prerequisites and installing them
• Accessing and downloading the source code with git
• Compiling the latest version of the source code

1.1 Prerequisites

Since CrypTool 2 is based on Microsoft .NET, you will need a Microsoft Windows environment. (Currently no plans exist for porting this project to Mono or other platforms.) We have successfully tested with Windows 7, Windows 8, Windows 10, and Windows 11.

Since you are reading the developer guidelines, you probably want to develop something. Hence, you will need a development environment. In order to compile our sources you need Microsoft Visual Studio or the free Microsoft Visual Studio Community Edition. Make sure to always install the latest service packs for Visual Studio.

In order to run or compile our source code you will need at least the Microsoft .NET. Usually the installation of Visual Studio also installs the .NET framework, but if you do not have the latest version, you can get it for free from Microsoft’s website. Once the framework has been installed, your development environment should be ready for our source code.

1.2 Clone the GitHub repository

Please read the Build instructions how to clone and build your own CT2.

1.3 Download the plugin template

Before you can start implementing a new plugin, you will need to download the CrypTool 2 plugin template. The most current version of this template is located in our CrypTool 2 repository, and can be downloaded here: (todo: add new template).

The template can be installed by (todo: write installation guide for template)

2. Plugin / Component Implementation

In this chapter we provide step-by-step instructions for implementing your own CrypTool 2 plugin. We shall assume that you have already retrieved the CrypTool 2 source code from the GitHub repository, set up Visual Studio or Visual Studio Community to build CrypTool 2, and you have placed the plugin template in the right place.

2.1 Create a new project

Open the CrypTool 2 solution, right click in the solution explorer on CrypPlugins and select Add --> New Project. In the dialog window, select Visual C# --> CrypTool 2 Plugin as project template and enter a unique name for your new plugin project (such as Caesar in our case). The next step is crucial to ensure that your plugin will compile and run correctly: select the subdirectory CrypPluginsExperimental\ as the location of your project:

Figure 2.1: Creating a new CrypTool 2 plugin project

As the project basics are already correctly set up in the template, you should now be able to compile the new plugin. First of all, rename the two files in the solution explorer to something more meaningful, for example Caesar.cs and CaesarSettings.cs. You should choose a descriptive name for your project. Do not delay this for later, since renaming the project later can become cumbersome:

Figure 2.2: Items of a new plugin project

2.2 Adapt the plugin skeleton

If you look into the two C# source files (Figure 2.2), you will notice a lot of comments marked with the keyword HOWTO. These are hints as to what you should change in order to adapt the plugin skeleton to your custom implementation. Most HOWTO hints are self-explanatory and thus we won’t discuss them all.

2.3 Defining the attributes of the Caesar class

The next thing we will do in our example Caesar.cs is define the attributes of our class. These attributes are used to provide necessary information for the CrypTool 2 environment. If they are not properly defined, your plugin won’t show up in the application user interface, even if everything else is implemented correctly.

Attributes are used for declarative programming and provide metadata that can be added to the existing .NET metadata. CrypTool 2 provides a set of custom attributes that are used to mark the different parts of your plugin. These attributes should be defined right before the class declaration

2.3.1 The [Author] attribute

The [Author] attribute is optional, meaning that we are not required to define it. The attribute can be used to provide additional information about the plugin developer (or developers, as the case may be). This information will appear in the TaskPane. We will define the attribute to demonstrate how it should look in case you want to use it in your plugin.

Figure 2.3: The definition for the [Author] attribute

All of these elements are optional and may be null:

• Author — the name of the plugin developer.
• Email — the email address of the plugin developer, should he or she wish to be available for contact.
• Institute — the organization, company or university with which the developer is affiliated.
• URL — the website of the developer or of his or her institution.

2.3.2 The [PluginInfo] attribute

The [PluginInfo] attribute provides necessary information about the plugin, and is therefore mandatory. The information defined in this attribute appears in the caption and tool tip window. The attribute is defined as follows:

Figure 2.4: Multilingual definition of [PluginInfo] attribute

This attribute has the following parameters:

• Resource File — the namespace and class name of an associated resource file .resx. This element is optional and used only if the plugin provides multilingual strings (see also Section 3).
• Caption — the name of the plugin, or, if using a resource file, the name of the field in the file with the caption data. This element is mandatory.
• ToolTip — a description of the plugin, or, if using a resource file, the name of the field in the resource file with the tooltip data. This element may be null.
• DescriptionURL — the local path of the user documentation file (XML file, see Section 4). This element may be null.
• Icons — an array of strings to define all the paths of the icons used in the plugin (i.e. the plugin icon described in Section 2.4). This element may be null.

For your first plugin, it’s recommended to skip the resource file and use English strings for Caption and ToolTip. If you’re ready to add multi-language support to your plugin, take a look at Section 3.

The DescriptionURL element defines the location path of the user documentation file (custom XML format), e.g. "assemblyname/path/filename.xml". Take a look at Section 4 to see how to create a documentation file.

The Icons parameter is an array of strings and should be provided in format: new[] { "assemblyname/path/filename.png" }

Don’t forget to add all files to your project in Visual Studio. See Section 2.4 how to do this.

2.3.3 Set algorithm category

In the CrypTool 2 user interface plugins are grouped by their algorithm category, for example hash function, symmetric cipher, and so on. To set the category, you must specifiy the attribute [ComponentCategory]. Multiple categories are allowed.

[ComponentCategory(ComponentCategory.CiphersClassic)]
public class ExamplePluginCT2 : ICrypComponent
{ 
   // implementation of the class
}

2.3.4 Adding parameters to the CaesarSettings class

If your component provides user-configurable parameters, you can set them up in the settings class derived from ISetting. This comprises text input fields, number fields, combo boxes, radio buttons and so on. Take a look at CaesarSettings.cs to see some examples for user-configurable parameters.

If you don’t want to provide any parameters, delete the class and return null for the Settings property:

public ISettings Settings
{
   get { return null ; }
}

2.4 Add an icon file

Your component is represented in the CrypTool 2 user interface by an icon. You should add a custom icon file, but if you don’t, the template uses a generic default one.

The proper image size is 40x40 pixels, but since the image will be rescaled if necessary, any size is technically acceptable. Once you have saved your icon, you should add it directly to the project or to a subdirectory with it. Right-click on your plugin project or any subfolder and select Add --> Existing Item.

Figure 2.5: Adding an existing item

Choose Image Files as the file type and select your newly-created icon for your plugin.

Figure 2.6: Selecting the image file

It’s necessary to set the icon file as a Resource in the file properties. Right-click on your icon file, click Properties and set the Build Action to Resource.

Figure 2.7: Go to Properties, select Build Action to Resource

2.5 Input and output connectors

Next we will define some class properties to be used as data input and output connectors of the component. Each property is defined by a [PropertyInfo] attribute:

• direction — defines whether this property is an input or output property:
  • Direction.Input
  • Direction.Output
• caption — a short caption of the data property shown in the editor. May be either a text or a key referring to a multilingual resource file (see Section 3).
• tooltip — similar as a caption, but more descriptive. May be either a text or a key referring to a multilingual resource file.
• mandatory — this flag determines whether an input must be attached by the user to use the plugin. If set to true, an input connection will be required or else the plugin will not be executed in the workflow chain. If set to false, connecting an input is optional. As this only applies to input properties, if the direction has been set to Direction.Output, this flag will be ignored.

Here is an example:

[PropertyInfo(Direction.InputData , "Text input ", "Input a string to be processed by the Caesar cipher", false )]
public string InputString
{
  get;
  set;
}

The output data property (which handles the input data after it has been encrypted or decrypted) may look as follows. CrypTool 2 does not require implementing set methods for output properties, as they will never be called from outside the plugin (it won’t hurt, though).

[PropertyInfo(Direction.OutputData , "Text output", "The string after processing with the Caesar cipher", false )]
public string OutputString
{
  get;
  set;
}

You can basically use any data type. If your component deals with potentially large amounts of binary data, you may want to use the ICryptoolStream data type instead of byte[]. You will need to include the namespace Cryptool.PluginBase.IO. Here’s an example how to use ICryptoolStream for an output property:

[PropertyInfo(Direction.OutputData, "CryptoolStream output", "The raw CryptoolStream data after processing with the Caesar cipher", false)]
public ICryptoolStream OutputData
{
  get
  {
    if (OutputString != null )
    {
      return new CStreamWriter( Encoding.UTF8.GetBytes(OutputString));
    }
    return null;
  }
}

2.6 Implement your algorithm

Algorithmic processing should be done in the Execute() function. Here’s a boilerplate example of how it could look like (example simplified for demonstration purposes):

public void Execute()
{
  if (string.IsNullOrEmpty( InputString ))
  {
    return;
  }
  try
  {
    ProgressChanged (0, 100); // set progress bar to 0%
    if(settings.Action == CaesarMode.Encrypt)
    {
      OutputString = Encrypt(InputString);
    }
    else
    {
      OutputString = Decrypt(InputString);
    }
    ProgressChanged(100, 100) ; // set progress bar to 100%
    OnPropertyChanged("OutputString"); // push output to editor
  }
  catch(Exception ex)
  {
    // log error to CrypTool 2 log
    GuiLogMessage(string.Format("Failure: {0}", ex. Message), NotificationLevel.Error);
  }
}