What is Themis Server

Themis Server (aka Interactive Simulator) is a remote debugging server for Themis. It acts as an interactive emulator and is aimed at helping engineers understand Themis. It can come in handy if you're just starting out with Themis. Using the Themis Serer, you can avoid spending a lot of time and effort building your own client and server, making sure you get the keys right, etc. Using a simple 'remote party simulator' you can try out Secure Session and Secure Message in an interactive mode and use copying and pasting to test encryption/decryption of containers with Secure Cell.

When would you need Themis Server?

  • When you want to try Themis without building a lot of code.
  • When you need to understand if you're using Themis the right way.
  • When you have problems in your code and are flexible enough to adapt it to talk to our server. Its log console and output could be used to test against the "canonic" implementation.

Registration

To use the interactive simulator for Themis, you need to register (or login if you have already registered) using your email address (don't worry, no spam from us):

1a. Click "Register" in the top right corner of Documentation Server (and skip over to Step 3 if you've already registered).

1b. Alternatively, go to the Themis Server (Interactive Simulator) page and start the registration from there. This is what you'll see:

2. Register using your email address and create a password (we're feeling awkward reminding you about it, but you should use a unique strong password, always).

3. Login using your password and email address.

4. Go to the Themis --> Themis Server tab in the Documentation server header:

5. Use the Interactive Themis Server simulator.

The UI of Themis Server is gradually (albeit constantly) evolving. Don’t be surprised to find out that some buttons have moved around a little. The core functionality of Themis Server remains the same.

Getting started

Interface overview

There are a few sections in the screenshot above that might be useful to people who use Themis in their apps, or who would like to get a quick status overview of the project:

The header menu takes you to three different sections of Themis Server:

For every section of Themis Server Data Simulator, there is an "assistant" mode, which provides extra verbosity for any field and is on by default. It can be turned off (or back on) by clicking the "assistant" mode status icon - lightbulb in a circle next to the Data Simulator mode title.

Verbosity mode is on when the lightbulb assistant indicator is blue:

Verbosity mode is off when the lightbulb assistant indicator is grey:

Interactive Simulator

The Themis Interactive Server Simulator allows your code to connect to our server in real-time and use debug console (appears at the bottom of the screen) to actually test it.

When you log in, Themis Server generates you a new JSON endpoint (an address to which you can talk via HTTP RESTful API) if there is no active session at the point. It also generates a server key.

The server can either generate a client keypair or pick the client public key you've entered. Currently, Themis Server only works with EC keys (for a number of reasons), but one can easily modify the key type in Themis just to test things.

Pasting keys:

Generating keys:

To switch between "pasting" and "generating" the keys, click the "Paste/Generate" switch. It should change its position (left/right) and colour (blue for "Paste" mode, green for "Generate" mode).

You can re-generate the server keypair and you can show or hide logs using the corresponding buttons.

To talk to the server, you need to write a client application, which will: send encrypted test messages encoded in base64,
decode received messages from base64, then decrypt them.

To start or stop Secure Session or Secure Message on our server side, use the corresponding buttons (see the screenshot above).

Important note! Once a day the session is resent on our side so you'll get a warning _"You must start session on https://docs.cossacklabs.com/interactive-simulator/setup/" meaning that you need to press the appropriate "Start Secure Session" or "Start Secure Message" button again for it to work.

When the server successfully decodes a message, it will send back the same message in reverse, e.g. 'tset' for 'test'. Once you've successfully connected to the server, you'll see debug console at the bottom of the screen

Snippets

In https://github.com/cossacklabs/themis/tree/master/docs/examples/Themis-server there are very simple examples for every language Themis supports. These examples are aimed at Themis server specifically: they are base64-friendly and have all the primitives to talk to the server API.

Data simulator

Data simulator ("Datasim") allows you to copy/paste base64-encoded objects containing Secure Cell and Secure Message. It is used for debugging either of the following modes: Secure Cell or Secure Message.

Secure Cell

Note: Make sure you're logged in before you start!

Go to Secure Cell Datasim page.

Pick Secure Cell Mode in the 2nd level menu, input the parameters, and encrypt/decrypt messages. Follow the on-screen instructions. It's a pretty straightforward procedure.

Secure Message

Note: Make sure you're logged in before you start!

Go to Secure Message Datasim page.

Paste the client public key and generate (or regenerate) the server key and proceed. As you can see, the sign mode only adds a signature to the message, without altering its contents. Follow the on-screen instructions. It's a pretty straightforward procedure.

Additional info

  • Themis Server Simulator was created to aid the debugging of Themis-based applications and learning Themis. It is not suitable for industrial use and can sometimes be down (most probably because we're working on improving it).
  • By giving us your proper e-mail, you won't get any spam from us. We're only sending out really important announcements relevant for every Themis user. If we can avoid disturbing you — we'll use other channels.
  • If you have any problems using Themis or Themis Server, let us know.