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. Install the plugin template

Before you can start implementing a new CT2 plugin, it is highly recommended to install the CrypTool 2 plugin template for Visual Studio. The most current version of this template is located in the git repository. It is located here: CrypPluginTemplate.

The template can be installed by first zipping it into a CrypTool 2 Plugin.zip and then copying the CrypTool 2 Plugin.zip file into the folder:

%USERPROFILE%\Documents\Visual Studio 2022\Templates\ProjectTemplates\C#

The template allows the easy creation of new components using a Visual Studio wizard. When used, the Wizard using the template automatically creates all necessary initial files for a new CT2 plugin and component.

2. Plugin and component implementation

This chapter provides step-by-step instructions for implementing your own CrypTool 2 plugin and component(s). A plugin is a .NET assembly file (dll) containing one or more CT2 components. A CT2 component is a C# class that derives from ICrypComponent.

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 the CrypPlugins folder 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). You should choose a descriptive name for your project. The next step is crucial to ensure that your plugin will compile and run correctly: Select the subdirectory CrypPlugins 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.

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 (Direction.Input) or output (Direction.Output) property:
• 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 Chapter 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 component. If set to true, an input connection is required or else the component will not be executed in the used workspace. 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;
}

An output data property is used to output data in the component. CrypTool 2 does not require implementing public set methods for output properties, as they will never be called from outside the component. Therefore, they can be private.

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

You can basically use any data type. If your component deals with potentially large amounts of binary data, you should 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 is a simplified example of how it could look like:

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 needed 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, informational, or debug messages to the user.

Figure 2.8: Example log

2.8. Create a CrypTool 2 template

Each component should have an associated workspace file (called template) to show the algorithm in action. These template files are saved as CrypTool Workspace Manager files with file extension .cwm. Additionally, a template needs a descriptive XML file and an icon file. You can view the example files from other components by opening any of the files in the Templates subfolders. Figure 2.8 shows an example template. You should provide such a template .cwm file (+ XML and icon) to demonstrate a typical use case of your component. Please place it into the corresponding Templates subfolder.

Figure 2.9: Example template for the Caesar cipher

Our requirements for a new component's template are:

• A template cwm file (your created workspace) with placeholder keys, e.g. names and texts starting with $ and ending with $; these will be replaced based on replacement definitions of the corresponding template xml
• A template xml file containing English replacement definitions (and German, if possible) replacing the placeholder keys
• A template image file (png or jpg)
• All three files (cwm, xml, image) have to have the same name (e.g. "Caesar.cwm", "Caesar.xml", "Caesar.png"); otherwise CT2 does not find the xml for the cwm file
• The template should be "nicely" layoutted, especially the lines between components
• The template has to contain a memo field describing the main idea of the template and its content (e.g. description of the shown cipher)

3. Internationalization

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

4. Documentation

If you 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 and components 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.