Start here

Welcome to the official documentation for Themis encryption library. This is a fully searchable general documentation for Themis. We also advise you to check out the Advanced section and Tutorials & How-Tos section on the main Themis documentation page.

Themis Server section (with the links duplicated in the Documentation Server header) contains an interactive emulator and is aimed at helping engineers understand Themis. It can come in handy if you're just starting out with Themis.

About Themis

Themis is an open-source high-level cryptographic services library for mobile and server platforms, which provides secure data exchange and storage.

If you'd like to understand a thing or two about Themis, see:

What's inside Themis

  • Soter: core crypto library: the underlying cryptographic primitive layer in Themis.
  • On cryptographic donors: making sure our solutions are based only on high-quality verified code through utilising the existing open-source cipher implementations.
  • Cryptosystems: what they are and how they create Themis Objects (a general explanation).
    • Secure Message: asymmetric encryption for data transfer.
    • Secure Session: asymmetric encryption based on ephemeral keys.
    • Secure Cell: container for symmetric/storage encryption.
    • Secure Comparator: Zero Knowledge Protocol (ZKP) implementation (comparing shared secret, without revealing it to potentially dishonest party).

On using Themis

If you'd like to contribute to Themis


Themis is a high-level cryptographic library.

Themis allows you to protect data at rest (in your database, files, or wherever you store it in your application) and data in motion (i.e. travelling between client and server, server and server, application and application, a smart coffee machine and a smart vacuum cleaner).

Themis is a portable, cross-platform implementation of several cryptosystems:

  • Secure Message: general purpose cryptographic system aimed at securing communication between two parties;
  • Secure Session: cryptographic system aimed at maintaining a messaging session between two peers, with the session-wise protection of their data exchange;
  • Secure Cell: cryptographic system aimed at storing data encrypted with a symmetric key, with additional security guarantees;
  • Secure Comparator: Zero-Knowledge Proof-based protocol built around SMP with ECC math, augmented with additional checks and features;

... all wrapped as nice high-level objects that are easy to use in your favourite environment.

Themis is (c) 2014-2018 Cossack Labs Limited. Themis is licensed under Apache license 2.0.


Themis supports Linux, Windows, macOS, iOS, and Android on i386/x86_64, arm, and various Android architectures.

The latest Themis release was tested on these OS:

  • Linux:

    • Debian 7, Debian 8, Debian 9 on i386/x86_64;
    • CentOS 6*, CentOS 7 on x86_64;
    • Ubuntu 14.04, Ubuntu 16.04 (as well as on Ubuntu 16.10 and Ubuntu 17.04 while they lased) on i386/x86_64.
  • Windows:

    • MS Windows 7*, 10* on x86_64;
    • MS Windows 8* on i386/x86_64.
  • macOS:

    • 10.10*, 10.11* on x86_64;
    • 10.12, 10.13 on x86_64.
  • Android:

    • Android 4.4*, Android 5.0* on arm64;
    • Android 6, 7, 8 on arm64.
  • iOS:

    • iOS8*, iOS9* on armv7, armv7s, arm64;
    • iOS10 - iOS12 on arm64.

* — previous versions of Themis (0.9.4) were tested on these operational systems, too. We cannot guarantee that it's still supported, but there are no known current issues.

Themis is available as the original C library and has Python, Objective-C, Ruby, PHP, NodeJS, C++, GoLang, Java Native, and Android wrappers.


Themis currently depends on libcrypto engine from BoringSSL / LibreSSL / OpenSSL. Some language-specific wrappers rely on ecosystem-specific tools, which is described in the corresponding high-level language references.

Getting Themis

You can fetch Themis from GitHub:

  1. Fetch the repository: git clone
  2. Make sure OpenSSL/LibreSSL + OpenSSL/LibreSSL Dev package (libssl-dev) are installed at typical paths: /usr/lib, /usr/include (/usr/local/* for macOS).
  3. Make sure the typical GCC/clang environment is installed.
  4. Type 'make install' and you're done (in most of the cases).

Or you can install Themis from the Cossack Labs own repositories.

Installing Themis from repositories

The easiest way to install Themis is to use package repositories. Themis Core library can be installed into your system from Cossack Labs repositories. High-level language wrappers can be installed from language-specific repositories.

Most language wrappers (except mobile) require the core Themis library to be installed in the system. Make sure to install the core library and its dependencies before installing language wrappers.

Package repositories contain stable versions of Themis, prebuilt and packaged for the most widely-used systems.

If you need the latest development version of Themis, do not wish to use the repositories for installing Themis, or your system is not supported yet, you can build and install Themis from GitHub source code.

Installing Themis Core

The core library is available via Cossack Labs package repositories. Please follow the instructions below for your operating system.

Debian, Ubuntu

Supported systems:

  • Debian 8 "Jessie"
  • Debian 9 "Stretch"
  • Ubuntu 14.04 LTS "Trusty Tahr"
  • Ubuntu 16.04 LTS "Xenial Xerus"
  • Ubuntu 18.04 LTS "Bionic Beaver"

1. Import Cossack Labs public key

You need to import the public key used by Cossack Labs to sign packages:

wget -qO - | sudo apt-key add -

NOTE: If you wish to validate the key fingerprint, it is:
29CF C579 AD90 8838 3E37 A8FA CE53 BCCA C8FF FACB

2. Make sure APT supports HTTPS

You should install HTTPS support for APT if it is not installed already:

sudo apt-get install apt-transport-https

3. Add Cossack Labs repository to your sources.list

Create a new *.list file under /etc/apt/sources.list.d directory (for example, /etc/apt/sources.list.d/cossacklabs.list). Put the following line into the list file:



  • $OS_NAME should be debian or ubuntu
  • $RELEASE should be Debian or Ubuntu release name (like stretch). You can determine this by running lsb_release -cs, if you have lsb_release installed.

We currently build packages for the following OS_NAME and RELEASE combinations:

  • debian jessie — Debian 8 "Jessie",
  • debian stretch — Debian 9 "Stretch",
  • ubuntu trusty — Ubuntu 14.04 LTS "Trusty Tahr",
  • ubuntu xenial — Ubuntu 16.04 LTS "Xenial Xerus",
  • ubuntu bionic — Ubuntu 18.04 LTS "Bionic Beaver".

For example, if you are running Debian 9 "Stretch", run:

echo "deb stretch main" | \
  sudo tee /etc/apt/sources.list.d/cossacklabs.list

4. Reload local package database

sudo apt-get update

5. Install Themis package

sudo apt-get install libthemis


Supported systems:

  • CentOS 7

NOTE: We build RPM packages only for x86_64, 32-bit systems are not supported.

1. Import Cossack Labs public key

You need to import the public key used by Cossack Labs to sign packages:

sudo rpm --import

NOTE: If you wish to validate the key fingerprint, it is:
29CF C579 AD90 8838 3E37 A8FA CE53 BCCA C8FF FACB

2. Add Yum repository for Cossack Labs

The easiest way is to download the *.repo file from our server:

wget -qO - | \
  sudo tee /etc/yum.repos.d/cossacklabs.repo

3. Install Themis package

sudo yum install libthemis


Themis is available on macOS via Homebrew.

Supported systems:

  • macOS 10.12 Sierra,
  • macOS 10.13 High Sierra,
  • macOS 10.14 Mojave.

1. Add Cossack Labs tap

brew tap cossacklabs/tap

2. Update local formula database

brew update

3. Install Themis

brew install libthemis

Congratulations! You're done!

Installing Themis wrappers

Installing language-specific wrappers is done after you've installed the core library itself. Please check out the corresponding language guides for more details on how to install Themis wrapper for your language:

You may also want to check out the Building and installing chapter of the documentation if you do not wish to use the repositories for installation and prefer to do everything manually.

Building and Installing

Do you really need to build Themis from source code

The easiest way to install Themis is to use package repositories. Themis Core library can be installed into your system from Cossack Labs repositories. High-level language wrappers can be installed from language-specific repositories.

Package repositories contain stable versions of Themis, prebuilt and packaged for the most widely-used systems. If you need the latest development version of Themis or if you don't want to install Themis using repositories, you can build and install Themis from GitHub source code.

Most language wrappers (except those for mobile) require Themis Core library to be installed in the system. Make sure to install the core library and its dependencies before installing the language wrappers.

If your system or package manager is not supported yet, please let us know via

Themis with Docker

If you're building Themis on your machine to use it with Android, you may consider an alternative variant and build Themis with Docker. If you have Docker and you just want to build Themis quickly (and especially if you want to build Themis for Android), you can use our prebuilt android-build image. Use:

docker run --rm -it -v $(pwd):/projects cossacklabs/android-build bash -c 'git clone && cd themis'

This command will download and run ubuntu:16.04 image with pre-installed compilers, OpenSSL, and BoringSSL libraries – comes very handy when you don't want to build on your real machine.

Building Themis on your machine


To build Themis on your own machine, you will need some common UNIX build tools:

  • C compiler: GCC or Clang,
  • GNU make.

Themis also requires either OpenSSL, LibreSSL, or BoringSSL package to be installed for you to be able to use one of them as a cryptographic backend.

Attention! You need to install the developer version of the package (usually suffixed with -dev or -devel) as it contains the necessary header files.

In either case, we strongly recommend that you use the most recent version of these packages.

Building Themis core

No matter what you have selected on the previous step – your own machine or Docker – you need to start with getting the latest version of Themis from GitHub:

git clone

From the source directory, type:

make install

(Depending on your rights, sudo might be necessary for installation.)

This should work for most common tasks you would want to use Themis for.

Makefile targets

Themis comes with a Makefile that should serve you well for all the typical use cases and goals.

Here are some of the targets supported by the Makefile:

  • make install — build and install Themis Core headers and libraries in the system,
  • make all — build Themis libraries, but do not install them,
  • make themis_shared — only build the shared Themis library,
  • make themis_static — only build the static Themis library,
  • make test — build and run Themis Core test suite,
  • make clean — remove the build directory with intermediate files.

Makefile configuration

Most of Themis configuration is guessed automatically from your system environment. There is no separate ./configure step, everything comes prepared in advance!

However, if you wish to customise some build and installation aspects, Themis Makefile supports a number of configuration variables.

Installation prefix

By default, Themis is installed to the /usr hierarchy (/usr/local on macOS).
To change the installation destination, set the PREFIX variable:

make install PREFIX=/opt/themis

This is what a typical directory structure would look like after a successful installation:

/usr              - installation prefix
├── include
│   ├── themis            - header files
│   │   ├── themis.h
│   │   └── ...
│   └── soter
│       └── ...
└── lib
    ├── pkgconfig         - pkg-config support files
    │   ├── libthemis.pc
    │   └── libsoter.pc
    ├── libthemis.a       — compiled libraries
    ├── libsoter.a

Debug builds

By default, Themis libraries are built in release mode. To build Themis in debug mode with debug symbols, set the DEBUG variable:

make DEBUG=yes

Cryptographic backends

Currently, Themis supports OpenSSL-like cryptographic engines (libcrypto):

In the future, we plan to broaden the support of different crypto implementation libraries (and, in some rare cases, provide our own).

You need to install both the engine and its development header files. The packages are usually called libssl and libssl-dev (or -devel).

By default, Themis will build with system default cryptographic engine. If you need to use a custom libcrypto, set these parameters:

  • ENGINE: name of the engine to use (openssl, libressl, boringssl)
  • ENGINE_INCLUDE_PATH: path to the directory with openssl header files
  • ENGINE_LIB_PATH: path to the directory with libcrypto library

For example:

make install \
    ENGINE=libressl \
    ENGINE_INCLUDE_PATH=/opt/libressl-2.8.3/include \


You can opt for BoringSSL by setting ENGINE=boringssl. This will build and use the BoringSSL version embedded into Themis, you don't need to do anything else.
For Android wrapper, Themis currently uses BoringSSL engine by default.

If you wish to use a custom build of BoringSSL, start with reading the instructions at In addition to the ENGINE variable, you need to set the ENGINE_INCLUDE_PATH and ENGINE_LIB_PATH variables, too.
Note that both libcrypto.a and libdecrepit.a have to be put in ENGINE_LIB_PATH.

Selecting the default algorithm parameters

Themis is designed to be algorithm-agnostic thanks to its special abstraction layer, Soter. It could be built with custom ciphers or cipher implementations specific to your regulatory needs or to the available implementations in your environment. There are two ways you can alter these parameters: for the symmetric algorithm, there is a variable that points libsoter to a specific function picked at the compilation point.

Authenticated symmetric algorithm (only AES in GCM mode is currently available):

AUTH_SYM_ALG: THEMIS_AUTH_SYM_ALG_AES_256_GCM /* used by default */

General symmetric algorithm (only AES in CTR mode is currently available):

 SYM_ALG: THEMIS_SYM_ALG_AES_256_CTR /* used by default */

As for asymmetric algorithms, we're still working on making them switchable in compilation. Currently, for most of the asymmetric operations, the algorithm is selected by the key type you feed into it (either RSA or EC key, defined during the key generation point).

However, for RSA you can change the key length at compilation time (we strongly insist that using a key length less than 2048 should only be done due to performance considerations, in safe environments):

                 2048 /* used by default */

Custom destinations

By default, Themis is installed to /usr/lib and /usr/include folder. To change the prefix of target folders, use parameter PREFIX:

make install PREFIX=/opt

Building Themis wrappers

Instructions for building wrappers assume that you have a working installation of the relevant language toolchains available via standard system paths.

Android wrapper installation

Using Docker

If you have Docker and you just need to build Themis quickly, you can use our prebuilt android-build image:

docker run --rm -it -v $(pwd):/projects cossacklabs/android-build bash -c 'git clone && cd themis && git submodule update --init && ./gradlew assembleRelease'

It will create AAR (Android library project) in the build/outputs/aar/ folder. Link this aar file manually into your application.

Manually from sources

Themis for Android uses Gradle build system.
A Gradle wrapper is included in the root directory of the project. Like the rest of the modern Android ecosystem, Themis uses BoringSSL as its cryptographic backend. BoringSSL is included as a submodule in the Themis repository.

You should install the latest Android SDK tools or Android Studio. You don't need full Android Studio to build Themis, just the command line SDK tools.

Make sure to specify the correct path to your Android SDK:

export ANDROID_HOME=/path/to/android/sdk

Make sure your SDK has the necessary build tools and Android NDK:

$ANDROID_HOME/tools/bin/sdkmanager --update
$ANDROID_HOME/tools/bin/sdkmanager 'build-tools;27.0.3' \
                                   'platforms;android-27' \

Since BoringSSL is included as a submodule, make sure all the Git submodules are initialised in your working copy:

git submodule update --init

Build Themis for Android:

./gradlew --info assembleRelease

It will create AAR (Android library project) in the build/outputs/aar/ folder. Link this aar file manually into your application.

To run Android tests, make sure ADB is enabled in settings, connect your device(s) and run:

./gradlew --info connectedAndroidTest

Java wrapper installation

Build jni library

Please make sure you have correctly installed JDK and configured JAVA_HOME before building Themis for Java. You can learn more about how to get and install JDK in Oracle documentation.

After building and installing the core library, use the following line to build the JNI wrapper:

make themis_jni

This will produce the shared library in the build directory (build by default).

To build JNI code for Java, the build system needs to know the location of the jni.h header. By default, it will be looking for the file in ${JAVA_HOME}/include directory. You may specify a different location by setting the JDK_INCLUDE_PATH environment variable.

On macOS, you might need to explicitly specify path to Java headers with CFLAGS:

# Example path to JAVA_HOME
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-11.0.2.jdk/Contents/Home

export CFLAGS="-I$JAVA_HOME/include -I$JAVA_HOME/include/darwin"
make themis_jni

Copy Themis Java files from themis/src/wrappers/themis/java. Paste them into your project src folder.

Copy libthemis_jni library to your project lib folder, link it as lib to your project.

See Themis Java examples for illustration.

iOS/OSX wrapper installation

Themis for iOS/OSX uses Cocoapods dependency manager.

To add Themis support to your Xcode project, add the next line to Podfile:

pod 'themis'

and run

pod install

C++ wrapper installation

After building and installing the core library, use the following line to install ThemisPP:

make themispp_install

You can then run ThemisPP test suite to verify the installation:

make themispp_test test_cpp

NodeJS wrapper installation

To install jsthemis, type:

    npm install jsthemis

PHP wrapper installation

After building and installing the core library, use the following line to install PHPThemis:

make phpthemis_install

This will build and install to the standard Zend extension directory.

You will need to add the following line to your php.ini file in order to enable Themis extension:

You can then verify if PHPThemis is correctly installed using

php --ri phpthemis

PHPThemis test suite can be run in the following manner:

make prepare_tests_all test_php

Go wrapper installation

Make sure that Themis is installed because Gothemis is a wrapper for Themis (uses CGO). Make sure that you have a working Go installation and your $GOPATH is set properly. Then just "go get" the code:

go get -u

Python wrapper installation

After building and installing the core library, use the following line to install PyThemis:

make pythemis_install

You can then run PyThemis test suite to verify the installation:

make prepare_tests_all test_python

Ruby wrapper installation

After building and installing the core library, use the following line to install RubyThemis:

make rbthemis_install

If you want to install RubyThemis into the user folder, use GEM_INSTALL_OPTIONS:

GEM_INSTALL_OPTIONS=--user-install make rbthemis_install

You can then run RubyThemis test suite to verify the installation:

make prepare_tests_all test_ruby

Rust wrapper installation

Rust-Themis wrapper is available on In order to use the wrapper, you still need to have the core library installed.

1. Install Themis Core as a system library using your system's package manager.

⚠️ IMPORTANT: Rust-Themis requires core Themis headers to be installed, therefore you need to install the development package: libthemis-dev for Debian and Ubuntu, libthemis-devel for RHEL and CentOS.

2. Add the following line to your Cargo.toml file: toml [dependencies] themis = "0.11"

Key management

We strongly advise that you read this section first, before proceeding to any of our language-specific how-tos. It will help you avoid some typical mistakes.

In the current version of Themis, key management is left to the discretion of the end user. However, we've got some helpful tips for those willing to develop in a truly secure way. And the highest level of cryptography is negligible if your keys are not protected well.

Generating keys

A good key should be as random as possible.

Do not "construct" keys yourself and don't use "secret strings" as keys. If possible, use a strong random number generator for key generation. If possible, verify your random number generator using some statistical test suite (currently we use NIST STS to check RNGs). While passing statistical tests does not guarantee that your RNG is good, failing them surely proves it is bad and predictable.

In a perfect world, the way to generate long-term keys (any key used more than once is considered to be a long-term key) is to use a dedicated machine or device placed in a separate room, not connected to any network (even private or corporate), which only allows authorised personnel to administer it. Of course, in a real world, the implementation of the "perfect world" scheme will end up being somewhat simplified due to practical considerations.

Note: If, despite all the warnings, you really need to use a secret password, at least pass it through a key derivation function (a one-way hash function that will make it look like a random key).

Storing keys in your application

Generally, we recommend using ephemeral (one-time) keys for encryption whenever possible, and only use signature keys as long-term keys. Regardless of the key type, applications must not store the keys in plaintext ("as is") in persistent storage. While using well-defined policy and operating system access control mechanisms to limit access to the key files is a good (and absolutely necessary) thing to do, storing them in an encrypted form makes the overall security level of your solution much higher.

The simplest way (that requires little effort and no infrastructure) you can choose is to use some kind of a master password to encrypt all your keys in the application. The master password can be passed as some parameter on application startup, and you can use Secure Cell to protect all your keys and other sensitive data.

Signature keys vs encryption keys

Do not use the same asymmetric keys for both signature and encryption (or key agreement). While mathematically they are the same thing (and you may be tempted to simplify your key management scheme) their purpose is what makes them different:

  • Encryption (or key agreement) keys are used to protect data (or other keys). Losing such a key will definitely lead to losing all the data protected with this key. That's why you would probably like to keep several copies of this key on different backup media. Also, access to this key may be granted to several people (i.e. a backup security officer needs to access the key when the primary administrator is on an unexpected sick leave). So, the main aspects of this type of key are: it is replicated, allows shared usage, and it is critical not to lose it.

  • Signature keys, on the other hand, are used to prove an identity (of a person or a computing node) in various authentication mechanisms. Losing such a key will not result in losing the data. These keys can be replaced relatively easily: just notify all the verifying parties that they should not trust the old key anymore and that they should trust the new key instead. Through careful use of timestamps, they can still trust the old data that was signed by the old key before the notification. But since such key represents an identity, sharing or replicating it increases security risks because each user of the key may impersonate this identity. That is why you would probably want to limit the number of potential users of signature keys. For signature keys that represent a person's identity, there should be only one user — the person whose identity the key is representing. For machine keys, we recommend that no more than two people that are very trusted within their security domain possess a single key. So, in most cases, the signature keys are: non-replicable, single-use, replaceable, are relative safely to lose.

As you may see, contradicting use cases and scenarios are what makes those keys different, so keep it in mind while designing your key hierarchy and key management scheme. Also, don't forget to store those keys in an encrypted form regardless of the key type.

Exchanging and transmitting keys over the network

The first recommendation may seem obvious: do not send the keys in plaintext over a network. Always encrypt the keys. The second recommendation, which is unfortunately often overlooked, is: even if you only exchange public keys, you should ensure their integrity and authenticity because if you fail to do it, a man-in-the-middle (MiTM) attacker will take over all your communications.

Relying on integrity through encryption is a bad practice, so please use a separate integrity mechanism.

Both Secure Message and Secure Session provided by Themis ensure confidentiality, integrity, and authenticity of the transmitted data, which means they can be used to send/receive keys.

Encrypt/Decrypt Console Utils

Some of the specific language wrappers for Themis are supplied with console utilities. They help understand the specific mechanics of encryption/decryption processes for those languages.

Encryption and decryption of data are straightforward processes that can be carried out through Secure Cell or Secure Message modes on your local machine using the command line.

The console utils are located in the tools folder, for each language separately. We mainly created these tools for integration testing and you can check out their usage in tests/_integration folder. We thought it would be useful to provide the information about usage examples here in the documentation, too.

Availability of console utils

The console utilities are currently available for the following language wrappers:

Basic usage of console utils

  1. Clone the Themis repository, install the corresponding Themis wrapper (please see Using Themis if you're unsure about how to do it), navigate to the repository root folder.

  2. Utils files are located in tools/<language> folder.

For Secure Cell, utils use the following files for encryption and decryption:

  • scell_seal_string_echo for Seal mode;
  • scell_context_string_echo for Context Imprint mode;
  • scell_token_string_echo for Token Protect mode.

Basic usage is:

./tool <command> <key> <message> <context>

where command is either enc or dec.

Context is optional for Seal and Token Protect mode. In Token Protect mode, the message consists of two parts: <message,token>.

For Secure Message, use a single file:

  • smessage_encryption for encryption, decryption, signing, and verifying the signature.

The basic usage is:

./tool <command> <sender_private_key> <recipient_public_key> <message>

where command is one of enc, dec, sign, verify.

You can find the test keys in tests/_integration/keys folder.

Python console utils

Please read the instructions above and install pythemis before you proceed.

Secure Cell

Encryption in Seal mode with context:

python ./tools/python/ "enc" "passr" "python seal with context" "somecontext"

Decryption in Seal mode with context:

python ./tools/python/ "dec" "passr" "AAEBQAwAAAAQAAAAGAAAAFhQO4ScxW1ZLYV4zqe+29FAfestnSKom9oYMk9nPwS97DPXrUr1ZIwtvY4glUKJSV4a1pw=" "somecontext"

Secure Message

Encryption using the client private key and the server public key:

python ./tools/python/ "enc" "./tests/_integration/keys/client.priv" "./tests/_integration/keys/" "python secure message"

Decryption using the server private key and the client public key.

python ./tools/python/ "dec" "./tests/_integration/keys/server.priv" "./tests/_integration/keys/" "ICcEJkkAAAAAAQFADAAAABAAAAAVAAAAsb/7tN9DX3/nrsnZKkRySQ6pICyC3wWatfQU6nb08lTs3hRS92nDkY+4c1VLLw1QpA=="

Please refer to the tests/_integration to see examples for other Secure Cell modes and Secure Message signing/verifying.

Ruby console utils

Please read the instructions above and install rubythemis.

Secure Cell

Encryption in Seal mode with context:

ruby ./tools/ruby/scell_seal_string_echo.rb "enc" "passr" "ruby seal with context" "somecontext"

Decryption in Seal mode with context:

ruby ./tools/ruby/scell_seal_string_echo.rb "dec" "passr" "AAEBQAwAAAAQAAAAFgAAAHxOPRMVS3cX3FAkO4BtUJpWOXUoMgjawelrRHkNdLfO9E16FNs/FavEdOmCnWJpbqZO" "somecontext"

Secure Message

Encryption using the client private key and the server public key:

ruby ./tools/ruby/smessage_encryption.rb "enc" "./tests/_integration/keys/client.priv" "./tests/_integration/keys/" "ruby secure message"

Decryption using the server private key and the client public key.

ruby ./tools/ruby/smessage_encryption.rb "dec" "./tests/_integration/keys/server.priv" "./tests/_integration/keys/" "ICcEJkcAAAAAAQFADAAAABAAAAATAAAADYX8pj+OYfzOxlqeDHnRiYTEA63oeLrBGKH8zzs1Kcd32knF8cI1na24GHl96vg="

Please refer to the tests/_integration to see examples for other Secure Cell modes and Secure Message signing/verifying.

Go console utils

Please read the instructions above and install gothemis.

Secure Cell

Encryption in Seal mode with context:

go run ./tools/go/scell_seal_string_echo.go "enc" "passg" "go seal with context" "somecontext"

Decryption in Seal mode with context:

go run ./tools/go/scell_seal_string_echo.go "dec" "passg" "AAEBQAwAAAAQAAAAFAAAAMYo3143Bw7KLWEzQmDfyN2KlYhpUSODIoJUZBju/bRarRny9xGpOUKSCn0YCrRzbg==" "somecontext"

Secure Message

Encryption using the client private key and the server public key:

go run ./tools/go/smessage_encryption.go "enc" "./tests/_integration/keys/client.priv" "./tests/_integration/keys/" "go secure message"

Decryption using the server private key and the client public key.

go run ./tools/go/smessage_encryption.go "dec" "./tests/_integration/keys/server.priv" "./tests/_integration/keys/" "ICcEJkUAAAAAAQFADAAAABAAAAARAAAAyUsE67JJjkkGX2qn1s6cTJRroTxu0df/qDYd18IEOMKz7KAxhC7qboDBsbJP"

Please refer to the tests/_integration to see examples for other Secure Cell modes and Secure Message signing/verifying.

NodeJS console utils

Please read the instructions above and install Themis for NodeJS.

Secure Cell

Encryption in Seal mode with context:

node ./tools/js/scell_seal_string_echo.js "enc" "passr" "node seal with context" "somecontext"

Decryption in Seal mode with context:

node ./tools/js/scell_seal_string_echo.js "dec" "passr" "AAEBQAwAAAAQAAAAFgAAAIHy2sPH+MjuQSyPuoo9UMsR5GfxFDJ39i3s5ql1jWo/K+W7wcOCaD4BvKpLkLnn0Tnq" "somecontext"

Secure Message

Encryption using the client private key and the server public key:

node ./tools/js/smessage_encryption.js "enc" "./tests/_integration/keys/client.priv" "./tests/_integration/keys/" "node secure message"

Decryption using the server private key and the client public key.

node ./tools/js/smessage_encryption.js "dec" "./tests/_integration/keys/server.priv" "./tests/_integration/keys/" "ICcEJkcAAAAAAQFADAAAABAAAAATAAAAf3lRPakq215vCwbkhQ/TO0XnhDFOOSeKvJs+zTczQZtx8I8KZ7QXnIaf5cwVHOM="

Please refer to the tests/_integration to see examples for other Secure Cell modes and Secure Message signing/verifying.

Rust console utils

Please read the instructions above and install RustThemis dependencies before you proceed.

Secure Cell

Encryption in Seal mode with context:

cargo run --package themis-integration-tools --bin scell_seal_string_echo \
    enc "password" "message" "context"

Decryption in Seal mode with context:

cargo run --package themis-integration-tools --bin scell_seal_string_echo \
    dec "password" "AAEBQAwAAAAQAAAABwAAANuJ36S+78xLzw32Ld1MmR+W6XIPhXGVnu0b91EENhu7zJFA" "context"

Secure Message

Encryption using the client private key and the server public key:

cargo run --package themis-integration-tools --bin smessage_encryption \
    enc ./tests/_integration/keys/client.priv ./tests/_integration/keys/ \
    "Rust Secure Message"

Decryption using the server private key and the client public key.

cargo run --package themis-integration-tools --bin smessage_encryption \
    dec ./tests/_integration/keys/server.priv ./tests/_integration/keys/ \

Please refer to the tests/_integration to see examples for other Secure Cell modes and Secure Message signing/verifying.

PHP console utils

Please read the instructions above and install phpthemis.

Secure Cell

Encryption in Seal mode with context:

php -f ./tools/php/scell_seal_string_echo.php "enc" "passwd" "php->php seal with context" "context"

Decryption in Seal mode with context:

php -f ./tools/php/scell_seal_string_echo.php "dec" "passwd"  "AAEBQAwAAAAQAAAAGgAAAMvV3yLodj8YwJYl+fK/1XEaLksRltmFS832Ny5BKcM438EdNEWJQmR36azwLLUsFkzqxgcEXg==%" "context"

Secure Message

Encryption using the client private key and the server public key:

php -f ./tools/php/smessage_encryption.php "enc" "./tests/_integration/keys/client.priv" "./tests/_integration/keys/" "php secure message"

Decryption using the server private key and the client public key.

php -f ./tools/php/smessage_encryption.php "dec" "./tests/_integration/keys/server.priv" "./tests/_integration/keys/" "ICcEJkYAAAAAAQFADAAAABAAAAASAAAA6r2KJ9/xFkzweXwX4to4UnErDqVGa9KWCfjilzjgEkzcWAaIWYb7fimlnMk+xQ=="

Please refer to the tests/_integration to see examples for other Secure Cell modes and Secure Message signing/verifying.

Soter library

Soter is a cross-platform multipurpose cryptographic library that serves as a backbone for Themis. It provides a set of highly secure cryptographic primitives through a well-defined, consistent, and simple interface.

To name just a few things you can get with Soter (as the rabbit hole of its true capabilities runs much much deeper):

  • necessary cryptographic primitives for building robust secure solutions with high level of security;
  • intuitive, well-defined interface for cryptographic functions;
  • compile-time support for different (interchangeable) underlying cryptographic (donor) implementations (libraries and platform-specific functions);
  • object-oriented design.

Soter does not provide all the possible existing cryptoalgorithms. Instead, we tried to select the best ones for our cryptosystems (and future features) and provide a simple way of using them even for an inexperienced user. Also, we tried to provide the freedom in choosing the underlying cryptographic implementation for each of them.

The code is cleanly split into the generic part and the implementation-specific (and/or platform-specific) part, so moving the library to a different crypto implementation is very easy. Every function can be re-implemented using different cryptographic libraries. Appropriate source files are selected for compilation through compile-time switches. Thus, every instance of Soter library can be tweaked to support any platform-preferred implementation of the algorithms while still providing a consistent interface for its users.

We're currently using LibreSSL/OpenSSL's libcrypto, but plan to replace it in the future releases.

Themis in depth

Themis consists of two large parts:

  • Soter library: the backbone of all the Themis' operations, Soter is a cryptographic abstractions library that acts as an active interface between implementations of crypto-primitives and the main code.
  • Themis library: the actual cryptographic procedures, built on top of the cryptographic abstractions provided by Soter.

Under the hood

The idea behind Themis is simple: wrap complicated multi-step procedures with shared data (like end-to-end perfect forward secrecy messaging with session control) into simple objects and make these objects available through simple interfaces.


Same generation versions (versions that are using the same crypto engine) of Themis across different platforms are guaranteed to be compatible. For different versions, check corresponding build flags in the makefile. Although different platforms might have different implementations of cryptographic primitives, our pluggable cryptographic stack will take care of all the differences.


The architecture of Themis is layered to ensure high portability as well as ease of use. Every layer provides some level of abstraction to upper layers. Below is a high-level overview of Themis:

Low-level cryptographic bindings

At the lowest level, there are bindings to popular cryptographic libraries and APIs. They provide implementations of the necessary core cryptographic primitives and allow our stack to operate in different environments. This simplifies the process of porting to new platforms as only bindings with corresponding donor libraries have to be updated. We usually follow best practices and sensible recommendations of each platform maintainer and try to utilise cryptographic implementations native to each platform.


Soter provides an abstraction layer for Themis by wrapping all the different low-level cryptographic implementations into consistent cryptographic interfaces. These interfaces share the same signatures and behaviour across all the supported platforms and environments. This allows our stack to interoperate between instances in different environments. Also, we tried to make our interfaces easier to use and more secure.


Themis provides a set of high-level cryptographic operations wrapped into a full cryptosystem. Each operation is a carefully selected combination of cryptographic primitives for providing security for different scenarios and use cases. We believe there is no single-best generic solution to every security problem. Instead, we've picked common scenarios for a set of use cases that Themis' users (including us) are likely to stumble upon and polished up the cryptosystems to support a broad range of similar use cases.

So far, there are 4 services with separate cryptosystems available in Themis:


The cryptographic algorithms used by Themis by default are:

  • АES256-GCM+ for symmetric encryption (and AES256-CTR in the context-imprint mode of Secure Cell);
  • ECDH with EC-NID_X9_62_prime256v1 curve for asymmetric key agreement;
  • RSA 2048bit for asymmetric encryption.

High-level language bindings (wrappers)

We want Themis to be as easy to use as it is secure. We understand that the effort of adopting an "alien" module into your well-established codebase may negate all the potential benefits it brings. So, with a diverse set of high-level language bindings (wrappers), we try to bring Themis closer to your application's architecture and language coding style and minimise the efforts necessary on your side.

While maintaining a general common object model across all the covered languages, we try to tailor each binding to make Themis look most natural in each specific language. Currently we support:

Themis Server

Themis Server (aka Interactive Simulator) is an interactive simulator that can be used as a remote debugging server for Themis. It is aimed at helping engineers understand Themis. It can come in handy if you're just starting out with this encryption library.

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.

The modes of work for Interactive simulator are:

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):

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

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. Use Interactive Themis Server simulator.

Read more about the purpose and usage of Themis Server.

Frequently Asked Questions

Q: When will there be a platform X, language Y ready

A: We don't have an exact roadmap of availability, but we will cover most of the platforms we initially aimed at in the first couple of releases. If your favourite language is unavailable, it was either intentional (some languages and infrastructures have limitations that limit the ability to interface the objects properly) or it's just not on our roadmap and your feedback might change that. Drop us a line.

Q: Why Open Source?

A: Quoting Bruce Schneier: "In the cryptography world, we consider open source necessary for good security; we have for decades. Public security is always more secure than proprietary security. It's true for cryptographic algorithms, security protocols, and security source code. For us, open source isn't just a business model; it's smart engineering practice."

Q: Can I use Themis for commercial purposes?

A: The basic version of Themis is free, licensed under Apache 2 license, and yes, you can build commercial software using Themis. All the core features of Themis will always be free and open-source.

We are planning to offer additional, enterprise-development friendly infrastructure sometime in the future (once we are certain and comfortable using it ourselves during our own development) for a reasonable price.

If you would like to request specific features, get support for your language of choice, access our knowledge base and expert team, etc., we plan to provide commercial licenses somewhere along the way, with nifty additional features. Meanwhile, we're available for consulting you on using Themis for better protection of your privacy or product — just write us a message and we'll see where we can go from there.

Q: Do you roll your own crypto?

A: No. Themis relies on external cryptographic backends for implementation of cryptographic algorithms. Although some of us have a history of implementing ciphers in a proprietary environment, and these implementations have successfully passed governmental certifications, we still think that using widely accepted implementations is much better: more hungry sceptic eyes are looking at their possible faults every day and more hands are attempting every possible attack on these implementations.

As a basic choice for sourcing crypto primitives, we are using from OpenSSL/LibreSSL/BoringSSL, which is one of the most frequently used and audited open-source implementations of cryptographic primitives. We strongly suggest you use the LibreSSL version (now set at the default build choice), which is free from the shortcomings of OpenSSL (i.e. tons of poor legacy code).

Q: What sets Themis apart from other cryptographic libraries?

We provide targeted cryptosystems instead of assorted variants of "encrypt X with algorithm Y". The cryptosystems in Themis are aimed at a broad range of use cases, and their implementation is specifically hardened against risks and threat vectors of those use cases.

We're also very flexible in implementations: our architecture allows swapping algorithms underneath the cryptosystems, easily adapting platform-specific implementations (including hardware ones). Such flexibility allows us to build multi-platform solutions easily, utilising the best of available tools and minimising the risks of error propagation.

Q: Why should I use Themis' Secure Session, not SSL/TLS protection?

A: In fact, Secure Message / Secure Session objects sit on a different layer than SSL/TLS. You should use SSL/TLS to connect two Internet hosts with a Secure Session and exchange encrypted traffic based on a requisite all parties trust (i.e. a certificate bound to a network address). However, you can't connect two mobile phones that are communicating through a cloud of servers and relaying their messages and a number of balancing hosts, to exchange protected messages with SSL (well, actually you can, but after a certain amount of hacking).

That's where Secure Session is useful — when security and network transport are programmatically decoupled, and you need to enable remote parties, located in complicated environments, to be able to talk with authentication and encryption. And, if you didn't know, SSL/TLS is so full with problems that it's reasonable to think twice before actually entrusting anything but traffic protection to it. We even wrote a small blog post enumerating various problems we see in the SSL/TLS stack.

Themis and GDPR

As a cryptographic services library for mobile and server platforms, which provides secure data exchange and storage, Themis can help you reach better compliance with the General Data Protection Regulation (GDPR) as a "state of the art" encryption tool.

To find out about the exact ways Themis can help secure the users' data in your product(s)/infrastructure, apply for the DataGuardian Assistance Program.

You may also want to read about the way our encryption proxy Acra can help you meet the demands of several GDPR articles at once.

On security reviews and testing

On cryptography

This distribution includes cryptographic software. The country in which you currently reside may have restrictions on the import, possession, use, and/or re-export to another country, of encryption software. BEFORE using any encryption software, please check your country's laws, regulations, and policies concerning the import, possession, or use, and re-export of encryption software, to see if this is permitted. See for more information.

The U.S. Government Department of Commerce, Bureau of Industry and Security (BIS), has classified this software as Export Commodity Control Number (ECCN) 5D002.C.1, which includes information security software using or performing cryptographic functions with asymmetric algorithms. The form and manner of this distribution make it eligible for export under the License Exception ENC Technology Software Unrestricted (TSU) exception (see the BIS Export Administration Regulations, Section 740.13) for both object code and source code.

Reviews and testing

Each change in Themis core library is being reviewed and approved by our internal team of cryptographers and security engineers. For every release, we perform internal audits by cryptographers who don't work on Themis.

We use a lot of automated security testing, i.e. static code analysers, fuzzing tools, memory analysers, unit tests (per each platform), integration tests (to find compatibility issues between different Themis-supported languages, OS and x86/x64 architectures). Read more about our security testing practices in a blog post.

If you believe that you've found a security-related issue, please drop us an email to Bug bounty program may apply.

Additional resources

Our own experimental Themis-based projects

Useful resources

Contributing, contacts, assistance

Contributing to Themis

Themis is an open-source, Apache 2 licensed software, maintained by Cossack Labs for building reliable cryptography in our products: Acra, Hermes and Toughbase. You can hack it any way you want and contribute things back if you need something more than what we provide. As a development company, we focus on implementing features that are important to our products but would gladly spend some time to make Themis useful for everybody.

Every commit that goes into the master branch is audited and reviewed by somebody from Cossack Labs, don't be surprised if the review takes longer than you expect.

"I'd like to help somehow, but don't know what will be useful. What should I do?"

There's a Development status block, which displays what we're working on right now and what critical stuff is not there yet. If you'd like to take over any of those tasks, get in touch or just raise an issue and work on it.

If you'd like to do independent parts (implement new procedures/objects, do a language wrapper or a set of examples for languages or architectures we don't have and don't even plan yet) — just go ahead and let us know when you finish.

If you'd like to participate in the core development more closely, get in touch.

Development status

If you're looking for something to contribute to and gain eternal respect, just pick the things in the list of issues and let us know via email / through Gitter, or raise an Issue to make sure nobody's on it yet.

Issues marked as 'enhancement' are a great place to start.

Development quickstart


  1. Read the Themis architecture in depth documentation block, make sure that you understand everything (or at least you start thinking you understand everything).
  2. Get familiar with the directory structure and the way the system builds.
  3. Brace yourself for a lengthy session of reading the sources.


  • We wrote Themis in portable C code so please try to stick to the coding style you see.
  • We achieve OOP-like patterns of passing object context back and forth through all calls of related functions (object methods). The first parameter in every call is an object context pointer. Each object has a "constructor" — object_create method that allocates an object in the memory, initialises it, and returns the pointer for context. Each object also has a "destructor" — object_destroy method that uses object context pointer and correctly destroys its members and frees the memory. Please use this pattern if you'd like to go deeper into the core code.
  • We wrote high-level wrappers and examples in the way we think would be the most beneficial for the end-users. However, we're boring system-level programmers who could've missed some important style-related things. So feel free to introduce stylistic changes to anything in the high-level area, just make sure that they work the way they were supposed to initially.

Typical change procedure

  1. Check out the latest version of the code with git fetch or do a fork on GitHub.
  2. Modify the source to fix or improve something. Supply the change with a test, if you can.
  3. Create a diff of your work and send it to us as a patch or create a pull request if you're on GitHub.
  4. Wait for the team members to review, accept or discuss the changes you're proposing.

In a perfect world, you would also raise an issue in GitHub Issues to make sure no duplicate work takes place, but that's up to you :)

Submitting apps to the App Store

If you’re using Themis as your means of encryption within your iOS/macOS app that you’re submitting to the App Store, your encryption falls under the “open source” exception (although if your app is not open source/distributed free of charge, we strongly recommend that you seek legal advice).

Themis is a free cryptographic library that builds on the existing, community-tested cryptographic instruments (OpenSSL, LibreSSL, BoringSSL, depending on the target platform). It is open source and Apache 2-licensed, with its full source code publicly available online on GitHub.

This means you should indicate that you’re using encryption and only submit annual self-classification reports. Read more about Apple regulations on cryptography.

Directory Structure

Everything in this repository is distributed across the following directories:

  • docs — that's what you're reading now;
  • docs/examples — example uses for Themis;
  • gradle/wrapper — Gradle wrapper for Android version;
  • jni — components of the Android wrapper;
  • src/soter — Soter sources;
  • src/themis — Themis sources;
  • src/wrappers/themis — high-level language wrappers for Themis;
  • tests — tests;
  • toolscommand line utilities for local testing of Secure Cell and Secure Message;
  • third_party/boringssl — submodule of BoringSSL.

Crypto engine dependencies

All the files in the root directory of Soter — src/soter are engine-independent. Files that depend on the sources of crypto engine are in the corresponding subfolder of Soter (look into openssl for LibreSSL/OpenSSL crypto engine and into boringssl for BoringSSL respectively).

The crypto engine is selected during the build phase of Themis by setting ENGINE variable in Makefile. The following values are supported: openssl (default option), libressl, and boringssl. Please check out a detailed document on building and installing Themis in the corresponding section.

To add support for the new crypto engine to Themis:
- write engine wrapper with Soter interface (see src/soter/soter.h);
- put it in the engine subfolder in Soter's root directory;
- add the following engine-selecting block to makefile:

    ifeq ($(ENGINE),engine)
        CRYPTO_ENGINE_DEF = #engine defines if needed
        CRYPTO_ENGINE_PATH=#engine files path name

On leaving OpenSSL

We rely on the following list of crypto-primitives and ciphers for Themis:

  • AES,
  • RSA,
  • ChaCha,
  • KDF,
  • Rand,

We consider OpenSSL, LibreSSL, and BoringSSL to be crypto engines that fully support these crypto-primitives and ciphers on Linux, macOS, Windows, iOS and Android. However, we're planning to move away from OpenSSL everywhere some day and use BoringSSL as a default crypto engine on every platform supported by Themis.

We shall accumulate various sources of algorithms for different platforms to roadmap the migration away from the libcrypto dependency soon.

You can out check our plans concerning the support and migration to BoringSSL in the list of issues.

Advanced features of Themis

Themis has a number of advanced features that are still work-in-progress. As they mature to be tried, they're merged into the mainline Themis code. Since these features are experimental and contain our own cryptographic math or cryptosystem implementation, we cannot deliver them as out-of-the-box usable procedures like well-proven cryptosystems behind Secure Cell, Secure Message, and Secure Comparator.

To make sure that no experimental code bleeds into the mainline math and mainline code, we've come up with three preventive measures:

  • all the experimental code is included via conditional inclusions in the source files;
  • certain compilation flags need to be specified while building the binaries for these conditional includes to happen;
  • the build targets for experimental features are binaries with different names.

We intentionally avoid mentioning these features in the main documentation until they're proven and well tested, but we see the point and the practical benefit in presenting them to the cryptographic community within the general Themis infrastructure to ensure that the real-world implementation, not a dry lab test species, gets evaluated.

Credits and honourable mentions


Significant contributions to Themis encryption library have been made by Ignat Korchagin (secumod) and Andrey Mnazakanov (mnaza).

A special thank you goes to the awesome contributors that help us make Themis better:

Reserve your place in history, do a pull request! <3


Themis is widely-used for both non-commercial and commercial projects. We've mentioned some of the public projects in a blog post in December 2018:

  • GoClinic - healthcare information exchange platform from the Netherlands created for safe, effective, expedient, and long-term successful treatment of hospital patients. Special thank you goes to @popaaaandrei.
  • kit - personal organiser mobile app for iOS and Android for secure storage of logins, passwords, dates, and notes with the help of end-to-end encryption. Themis is used for encrypting all the data that is shared between the users.
  • Gochat by @ys1382 - open source secure chat written in Go, which uses Themis as the encryption engine. If you want to improve your Go knowledge – consider reading its code.
  • Hashblock-exchange - Hyperledger Sawtooth-based blockchain application where Themis is used for encrypting/decrypting using EC key-pairs of transaction content on the block.

Other known projects that just recently got onto our radars


Want to be featured on our blog and get in the list of contributors, too? Write us about the project you’ve created using Themis!

Where we use Themis

We are using Themis (as crypto primitive for Acra) on our own web resources to provide encryption for the contact information belonging to our subscribers (their names and email addresses).

The information is encrypted on the app’s side (non-transparent encryption is used). The encryption process is very similar to the one described in “Using Acra to Protect Your Django App” tutorial.

We use and recommend you using the most recent version of Themis, building it from the stable branch, for the best results.

Getting in touch

  • Requests/bugfixes/queries should go through GitHub Issues.
  • To get in touch with the developers, use this email at your own discretion :). Make sure you've tried reaching out through GitHub Issues first before writing a direct email.
  • To talk to the business wing of Cossack Labs Limited, drop us an email.
  • In-depth discussions, help in using Themis, and possible ways of collaboration could be found in our Google Group, and real humans still visit it from time to time, but we recommend that you use modern means of communication like email or GitHub Issues.

Implementation assistance and support

If you would like to receive a one-time customized assistance in implementing Themis for the needs of your app/service, consider applying for our DataGuardian Assistance Program.

Commercial support

At Cossack Labs, we offer professional support services for Themis and applications using Themis.

This support includes, but is not limited to the library integration, with a focus on web and mobile applications; designing and building end-to-end encryption schemes for mobile applications; security audits, for in-house library integrations or high-level protocol; custom application development that requires cryptography; consulting and training services.

Drop us an email to or check out the DataGuardian assistance program.