Developer HowTo

1. Developer guidelines

CrypTool 2 (CT2) is built using .NET and the Windows Presentation Foundation (WPF). Here you find a few things need to be considered, before you start writing code and adding to the development of the project. To make this process easier, we invite you to read through this document.

This document shows you how CrypTool 2 plugins and components are built and successfully interact with the application core.

In this first chapter we will describe all steps necessary in order to compile the existing CrypTool 2 on your own computer. The three basic steps are:

• Getting all prerequisites (a Visual Studio and a git client) and installing them
• Accessing and downloading the source code with git client
• Compiling the latest CT2 version of the source code from GitHub

After these steps, you can begin developing your own plugins and components.

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 successfully tested CT2 with Windows 7, Windows 8, Windows 10, and Windows 11.

In order to compile our sources you need a current Microsoft Visual Studio or the free Microsoft Visual Studio Community Edition. Since CT2 needs a current .NET framework version, make sure to select this during the installation process. If you missed to install .NET during the initial installation, you can always use the Visual Studio installer to reinstall .NET framework.

1.2. Clone the GitHub repository and build CrypTool 2

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, it is highly recommended 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 and component implementation

This chapter provides step-by-step instructions for implementing your own CrypTool 2 plugin and component. We 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 CT2, and you have installed the plugin template in the right place, as described in the previous chapter.

2.1. Create a new project

Open the CrypTool 2 solution, right click in the solution explorer on CrypPluginsExperimental 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 (here: Caesar). 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, see Figure 2.1.

Figure 2.1: Creating a new CrypTool 2 plugin project

As the project basics are already correctly set up by the template, you should now be able to compile the new plugin and component. 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's 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's 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 step we will do in our example Caesar.cs is to 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 component won’t show up in the application's user interface, even if everything else is implemented correctly.

A detailed introduction to attributes can be found in the Attributes (C#) article of Microsoft Docs. In short, attributes are used for declarative programming and provide metadata that can be added to the existing .NET metadata.

CrypTool 2 provides an own set of attributes that are used to define the different parts of your component, e.g. inputs and outputs, author, and cipher type. The following attributes are to be defined right before the class declaration.

2.3.1. The [Author] attribute

The [Author] attribute is optional, but should be used. The attribut provides additional information about the plugin developer(s). This information appears in the automatic generated online help of the component. Figure 2.3 shows an example [Author] attribute.

Figure 2.3: The [Author] attribute

All of these elements are optional and may be null:

• author — the name of the component developer.
• email — the email address of the component developer.
• 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 mandatory [PluginInfo] attribute provides necessary information about the component. The information defined in this attribute appears in the component's caption and tool tip. The attribute is defined as follows:

Figure 2.4: Multilingual definition of [PluginInfo] attribute

This attribute has the following parameters:

• resourceFile — 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 Chapter 3).
• caption — the name of the component, or, if using a resource file, the name of the entry in the resource file with the language-dependent caption data. The caption is mandatory.
• toolTip — a description of the component, or, if using a resource file, the name of the etrny in the resource file with the language-dependent tooltip data. The tooltip may be null.
• descriptionUrl — the local path of the user documentation file (XML file, see Chapter 4). The descriptionUrl may be null.
• icons — an array of strings to define all the paths to the icons used in the plugin (i.e. the plugin icon described in Section 2.4).

For your first component, it is recommended to skip the resource file and use English strings for _caption _and toolTip. If you are ready to add multi-language support to your plugin, take a look at Chapter 3.

The descriptionUrl element defines the online help file (custom XML format), e.g. "assemblyname/path/filename.xml". Take a look at Chapter 4 to see how to create an online documentation.

The icons parameter is an array of strings and should be provided in the format:

new[] { "assemblyname/path/filename.png" }

Don’t forget to add all external files (e.g. icon image files) to your project in Visual Studio. See Chapter 2.5 how to do this.

2.3.3. The [ComponentCategory] attribute

In the CrypTool 2 user interface components 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].

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

2.4. Adding parameters to the CaesarSettings class

If your component provides user-configurable parameters (settings), 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.5. Add an icon file

Your component is represented in CT2 in the components list of the WorkspaceManager (graphical editor) by an icon. You should add a custom icon file that represents the function of your component well.

The image file must be quadratic and any resolution is technically acceptable. Once you have saved your icon, you should add it directly to the project or to a subdirectory within 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 component.

Figure 2.6: Selecting the image file

It is 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.6. 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.7. Implement your algorithm

Algorithmic processing should be done in the Execute() method. 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);
  }
}

You must announce all changes to output properties by calling OnPropertyChanged with the correct property name. This step is crucial to correctly pass output data to other components.

You should set the progress of an execution by calling ProgressChanged. You may use interim progress updates for long-running computations in a loop.

You may use GuiLogMessage to show errors, warnings or informational messages to the user.

Figure 2.8: Example log

2.8. Create a CrypTool 2 template

Each plugin should have an associated workflow file to show the algorithm in action in CrypTool 2, which is called a "template". These workflow files are saved as CrypTool Workspace Manager files with file extension .cwm. You can view the example files from other plugins by opening any of the files in the Templates\ folder with CrypTool 2. Figure 2.8 shows an example template. You should provide such a template .cwm file to demonstrate a typical use case of your plugin. Please place it into the Templates\ folder and make sure to commit the file to the git repository.

todo: describe what we WANT in every template, e.g. memo field, multi language (at minimum English), "nice" layout of lines, etc.

Figure 2.9: Example template for the Caesar cipher

3. Internationalization

If you’d like to know how to add multi-language support to your component, please read Internationalization.

4. Documentation

If you’d like to know how to provide a user documentation file (custom XML format), please read Documentation.

5. YouTube Developer Videos

We have a set of developer videos on YouTube, which also demonstrate how to create your own plugin for CrypTool 2. The complete playlist is available here: CrypTool 2 Development – Create your own CrypTool 2 Components

6. Feedback

Your feedback is very important to us. If you have any questions, concerns or suggestions for improvement, please contact us at Contact us.