THEMIS DOCUMENTATION

Start here

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

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 is Themis: a bird's eye view of Themis.
• Going deeper: an in-depth look at the architecture and construction of Themis.

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

• Building and installing: detailed instructions for when the default installation scenario fails (this is rare, but not impossible).
• Notes on using Themis.
• Language references:
  • Android
  • Swift
  • Objective-C
  • Python
  • PHP
  • Ruby
  • C++
  • Go
  • JavaScript.
• Command Line utilities: for local testing of Secure Cell and Secure Message.
• Migration Guide: check if you're updating Themis version on production environment.
• Advice on key management: something you may find useful.
• Using Themis Server: a brief introduction to Themis Server — an interactive debugging environment for Themis.
• FAQ: Frequently Asked Questions.

If you'd like to contribute to Themis

• Contributing to Themis: how to contribute to Themis.
• Development status: (an incomplete list of) things we're working on.
• Development quickstart: what you need to know to extend Themis.
• Directory structure: what is where.
• Leaving OpenSSL: what's wrong with OpenSSL and why we'd like to leave it.
• Advanced features: notes on introducing advanced and experimental features to Themis.

Quickstart

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.

Availability

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, iOS11 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.

Dependencies

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 https://github.com/cossacklabs/themis.git.
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 repository.

For Ubuntu/Debian

1. Import the public key used by Cossack Labs to sign packages:

wget -qO - https://pkgs.cossacklabs.com/gpg | sudo apt-key add -

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

2. You may need to install the apt-transport-https package before proceeding:

sudo apt-get install apt-transport-https

3. Add Cossack Labs repository to your sources.list. You should add a line that specifies your OS name and the release name:

deb https://pkgs.cossacklabs.com/stable/$OS $RELEASE main

• $OS should be debian or ubuntu.
• $RELEASE should be one of Debian or Ubuntu release names. You can determine this by running lsb_release -cs, if you have lsb_release installed.

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

• Debian "Wheezy" (Debian 7)
• Debian "Jessie" (Debian 8)
• Debian "Stretch" (Debian 9)
• Ubuntu Trusty Tahr (Ubuntu 14.04)
• Ubuntu Xenial Xerus (Ubuntu 16.04)

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

echo "deb https://pkgs.cossacklabs.com/stable/debian stretch main" | \
  sudo tee /etc/apt/sources.list.d/cossacklabs.list

4. Reload local package database:

sudo apt-get update

5. Install the package

sudo apt-get install libthemis

For CentOS / RHEL / OEL

Note: We only build RPM packages for x86_64.

1. Import the public key used by Cossack Labs to sign packages:

sudo rpm --import https://pkgs.cossacklabs.com/gpg

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

2. Create a Yum repository file for Cossack Labs package repository:

wget -qO - https://pkgs.cossacklabs.com/stable/centos/cossacklabs.repo | \
  sudo tee /etc/yum.repos.d/cossacklabs.repo

3. Install the package:

sudo yum install libthemis

You're done!

Also, make sure to check out the installation documentation page and language-specific howtos.

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:

• Python,
• Ruby,
• Go,
• NodeJS,
• PHP.

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: <command: enc | dec > <key> <message> <context>.
Context is optional for Seal and Token Protect mode. In Token Protect mode, 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: <command: enc | dec | sign | verify > <send_private_key> <recipient_public_key> <message>.
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/scell_seal_string_echo.py "enc" "passr" "python seal with context" "somecontext"

Decryption in Seal mode with context:

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

Secure Message

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

python ./tools/python/smessage_encryption.py "enc" "./tests/_integration/keys/client.priv" "./tests/_integration/keys/server.pub" "python secure message"

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

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

Please refer to the tests/_integration/integration_python.sh script to see the 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/server.pub" "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/client.pub" "ICcEJkcAAAAAAQFADAAAABAAAAATAAAADYX8pj+OYfzOxlqeDHnRiYTEA63oeLrBGKH8zzs1Kcd32knF8cI1na24GHl96vg="

Please refer to the tests/_integration/integration_ruby.sh script to see the 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/server.pub" "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/client.pub" "ICcEJkUAAAAAAQFADAAAABAAAAARAAAAyUsE67JJjkkGX2qn1s6cTJRroTxu0df/qDYd18IEOMKz7KAxhC7qboDBsbJP"

Please refer to the tests/_integration/integration_go.sh script 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/server.pub" "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/client.pub" "ICcEJkcAAAAAAQFADAAAABAAAAATAAAAf3lRPakq215vCwbkhQ/TO0XnhDFOOSeKvJs+zTczQZtx8I8KZ7QXnIaf5cwVHOM="

Please refer to the tests/_integration/integration_js.sh script 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/server.pub" "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/client.pub" "ICcEJkYAAAAAAQFADAAAABAAAAASAAAA6r2KJ9/xFkzweXwX4to4UnErDqVGa9KWCfjilzjgEkzcWAaIWYb7fimlnMk+xQ=="

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

Themis Server

What is Themis Server

Themis Server is a remote debugging server for Themis. You can find it in the Simulator section of the documentation.

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.

The UI of Themis 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.

When 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.

• Themis Server 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.

Building and Installing

First, download the latest version of Themis:

git clone https://github.com/cossacklabs/themis.git

Go to the Themis source directory and type (depending on your rights, sudo might be necessary):

make install

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. There is not enough specific interaction to do a ./configure scenario. Everything comes prepared in advance!

Makefile includes the following targets:

• install: build and install the necessary headers and libraries in the system;
• themis_shared: only build the shared Themis library;
• themis_static: only build the static Themis library;
• all: build both shared and static Themis libraries;
• test: build and run the core tests suit for Themis;
• test_all: build and run all tests for Themis, except Android/iOS.

Debugging

The default makefile is configured to build both static and shared libraries. By default, libraries build in release mode. To build Themis in debug mode with debug symbols on make stage, you need to set variable DEBUG:

make DEBUG=yes

LibreSSL / OpenSSL

Currently, Themis uses LibreSSL/OpenSSL engine libcrypto as a dependency. In the future, we plan to broaden the support of different crypto implementation libraries (and, in some rare cases, provide our own).

Note: Themis uses BoringSSL with Android, see specific instructions in the corresponding section below.

You need to install both the engine and its development header files. By default, Themis will build with system default libcrypto. If you need to use a custom libcrypto, set these two parameters:

• CRYPTO_ENGINE_INCLUDE_PATH: headers of LibreSSL/OpenSSL;
• CRYPTO_ENGINE_LIB_PATH: compiled libcrypto from LibreSSL/OpenSSL.

You can do this via:

make CRYPTO_ENGINE_INCLUDE_PATH=/opt/include CRYPTO_ENGINE_LIB_PATH=/opt/lib

BoringSSL

Themis currently uses BoringSSL engine libcrypto as a dependency for Android wrapper.

First of all, you need to install the engine itself. Please see instructions at boringssl.googlesource.com.

The process of cloning and compiling the BoringSSL is described next.

Note the copying of build/decrepit/libdecrepit.a into build/crypto folder. This is necessary for the correct compilation of Themis.

export BORINGSSL_HOME=$HOME/boringssl

cd $BORINGSSL_HOME && git clone https://boringssl.googlesource.com/boringssl && mkdir build && cd build && cmake .. && make && cp decrepit/libdecrepit.a crypto/

You need to install both the engine and its development header files. By default, Themis will build with system default libcrypto. If you need to use a custom libcrypto, set these two parameters:

• ENGINE: set boringssl
• CRYPTO_ENGINE_INCLUDE_PATH: headers of BoringSSL;
• CRYPTO_ENGINE_LIB_PATH: folder with compiled libcrypto and libdecrepit.

You can use this make command:

make ENGINE=boringssl ENGINE_INCLUDE_PATH=$BORINGSSL_HOME/boringssl/include ENGINE_LIB_PATH=$BORINGSSL_HOME/boringssl/build/crypto BUILD_PATH=build_with_boringssl all

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 */
              THEMIS_AUTH_SYM_ALG_AES_128_GCM
              THEMIS_AUTH_SYM_ALG_AES_192_GCM

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

 SYM_ALG: THEMIS_SYM_ALG_AES_256_CTR /* used by default */
          THEMIS_SYM_ALG_AES_128_CTR
          THEMIS_SYM_ALG_AES_192_CTR

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

  RSA_KEY_LENGTH: 1024
                 2048 /* used by default */
                 4096

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

About Directory Structure

After the installation, a typical directory structure would look like this:

- /usr/include/
-- soter — Themis header files for soter subsystem
-- themis — Themis header files
- /usr/lib
-- libthemis.a, libthemis.so, libsoter.a, libsoter.so — compiled libraries.

Installing Themis wrappers

Installing language-specific wrappers is done after you've installed the main library itself. Please check corresponding language tutorials for more details.

Python wrapper installation

Note: You'll need to add sudo if you're installing it system-wide, not just in a dedicated user environment.

Just type:

pip install pythemis

PHP wrapper installation

In the Themis source directory, type:

make phpthemis_install

This will build phpthemis.so extension for php. Now add the following to php.ini:

extension=phpthemis.so

Ruby wrapper installation

If Themis is already installed, type in console:

 sudo gem install rubythemis

In some environments rubythemis will install the main Themis library itself, but if it fails, or if Themis is not installed yet, you can install both Themis and rubythemis wrapper via make - just go to the Themis root directory and type:

make rubythemis_install

C++ wrapper installation

To install ThemisPP, type:

make themispp_install

NodeJS wrapper installation

To install jsthemis, type:

npm install jsthemis

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 github.com/cossacklabs/themis/gothemis/...

Android wrapper installation

Themis uses BoringSSL with Android.

First of all, compile BoringSSL on your machine, as mentioned above.

Note: Don't forget to copy $BORINGSSL_HOME/build/crypto/decrepit/libdecrepit.a into $BORINGSSL_HOME/build/crypto folder.

To build BoringSSL for Android, use the following instructions. When using Debian, you might also have to install some of the tools listed here, notably cmake, build-essential, ninja-build.

Note: If you feel confused building BoringSSL, you might check the instructions provided below (this is what we use).

cd $BORINGSSL_HOME/boringssl && mkdir build-x86 && cd build-x86 && cmake -DANDROID_ABI=x86 -DCMAKE_TOOLCHAIN_FILE=../third_party/android-cmake/android.toolchain.cmake -DANDROID_NATIVE_API_LEVEL=26 -GNinja .. && ninja -j 20

cd $BORINGSSL_HOME/boringssl && mkdir build-armeabi-v7a && cd build-armeabi-v7a && cmake -DANDROID_ABI=armeabi-v7a -DCMAKE_TOOLCHAIN_FILE=../third_party/android-cmake/android.toolchain.cmake -DANDROID_NATIVE_API_LEVEL=26 -GNinja .. && ninja -j 20

cd $BORINGSSL_HOME/boringssl && mkdir build-arm64-v8a && cd build-arm64-v8a && cmake -DANDROID_ABI=arm64-v8a -DCMAKE_TOOLCHAIN_FILE=../third_party/android-cmake/android.toolchain.cmake -DANDROID_NATIVE_API_LEVEL=26 -GNinja .. && ninja -j 20

However, consider checking the latest instructions version we use in the circle.yml file.

Themis for Android uses Gradle build system. A Gradle wrapper is included in the root directory of the project.

You should install the latest Android SDK and Android NDK.

Next, specify the paths to your SDK and NDK for Gradle:

export ANDROID_HOME=/path/to/android/sdk
export ANDROID_NDK_ROOT=/path/to/android/ndk
export ANDROID_NDK=$ANDROID_NDK_ROOT

Finally, build Themis with BoringSSL (both Java and Native part):

./gradlew --info -Pboringssl_path=$BORINGSSL_HOME/boringssl build

It will build AAR (Android library project) ready for use in your application. AAR libraries are located in the build/outputs/aar/ folder.

If you want to use SecureSocket and SecureServerSocket classes, make sure you have declared the INTERNET permission in your AndroidManifest.xml.

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

./gradlew --info -Pboringssl_path=$BORINGSSL_HOME/boringssl connectedAndroidTest

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

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.

Interoperability

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.

Architecture

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

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

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:

• Secure Message;
• Secure Session;
• Secure Cell;
• Secure Comparator.

Algorithms

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 a specific language. Currently we support:

• Java/Android;
• Objective-C (iOS/OSX);
• Swift (iOS/OSX);
• Python;
• PHP;
• Ruby;
• С++;
• GoLang;
• JavaScript (NodeJS).

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 libcrypto.so 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.

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

Preparation

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.

Language

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

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;
• tools — command 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,
• SHA / HMAC, ECDSA, ECDH.

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 by Ignat Korchagin (secumod) and Andrey Mnazakanov (mnaza).

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

• deszip for updating jsthemis (#326);
• ilammy for making rust-themis wrapper, and improving Themis core;
• valeriyvan for numerous updates in iOS wrapper and examples;
• bryongloden for numerous changes and suggestions;
• maybe you?

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

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

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.