Building Themis from source code #

Building Themis from source is not recommended for casual or first-time use.

Unless you really know what you are doing and why — install prebuilt Themis from packages.

Building Themis Core #

Dependencies #

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 to be installed. One of these libraries is used as a cryptographic backend of Themis.

Note: You need to install the development version of the package (usually called libssl-dev or openssl-devel) as it contains the necessary header files.

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

Note: At the moment, Themis doesn’t support building from source on Apple M1 processors. Please see Homebrew installation instead.

Building with Make #

Start with getting the latest Themis source code from GitHub:

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

followed by a typical UNIX build and installation:

make
sudo 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.

Here are some of the targets supported by the Makefile:

make all — build Themis libraries, but do not install them (default)
make install — build and install Themis Core headers and libraries
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

Configuring the build #

Most of Themis configuration is guessed automatically from your system environment. 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 into the /usr/local hierarchy. To change the installation destination, set the PREFIX variable:

make install PREFIX=/opt/themis

Note: Some systems (e.g., CentOS) do not include the /usr/local hierarchy into their default search paths. On these systems make install will attempt to configure the linker so that it can locate the installed Themis libraries. Please adjust the /etc/ld.so.conf.d/themis.conf file if necesssary.

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

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

Debug builds #

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

make DEBUG=yes

This enables additional runtime assertions, extra error reporting, and disables compiler optimisations.

Sanitizers #

Note: Builds with compiler sanitizers are supported since Themis 0.13.

It is also possible to build Themis with sanitizers if they are supported by the compiler. To enable sanitizers, set the following options for make when building Themis:

WITH_ASAN — Address Sanitizer (pointer safety, memory safety)
WITH_MSAN — Memory Sanitizer (memory safety)
WITH_TSAN — Thread Sanitizer (synchronisation issues)
WITH_UBSAN — Undefined Behavior Sanitizer

Recent versions of GCC and Clang support all sanitizers.

For example, to build with address sanitizer enabled, run:

make all WITH_ASAN=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.

By default, Themis will use the default cryptographic engine for your system. If you need to use a custom-build engine, set the following parameters:

ENGINE — type 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 the libcrypto library

For example:

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

You need to install the development package for the cryptographic engine: the one that includes both the engine binaries and its header files. The package is usually called libssl-dev or openssl-devel.

OpenSSL #

OpenSSL is the default cryptographic engine on most platforms. Themis will automatically detect and use OpenSSL installed in your system. If you wish to explicitly require OpenSSL, set ENGINE=openssl when building Themis.

Note:

Starting from version 0.15.0, Themis supports OpenSSL 3.0. Consider using it instead of OpenSSL 1.1.1, as its end of life is September 2023.

Although as part of our CI, we only test OpenSSL 3.0.2 which comes with Ubuntu Jammy. However, as more distributions start implementing OpenSSL 3.x, the list of tested versions will grow.

BoringSSL #

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.

Note: You still need to install BoringSSL build dependencies. You will typically need to install CMake and Go in addition to Themis dependencies.

Themis uses BoringSSL by default on Android and WebAssembly platforms.

If you wish to use a custom build of BoringSSL, then in addition to the ENGINE variable you need to set the ENGINE_INCLUDE_PATH and ENGINE_LIB_PATH variables as well. Note that both libcrypto.a and libdecrepit.a have to be put into ENGINE_LIB_PATH (BoringSSL builds typically put them into different directories).

Selecting 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 available in your environment.

Themis uses generally good, sane defaults for algorithms and their parameters. If necessary, you can rebuild Themis with different defaults by setting configuration variables.

AUTH_SYM_ALG — authenticated symmetric encryption algorithm
- THEMIS_AUTH_SYM_ALG_AES_256_GCM (used by default)
- THEMIS_AUTH_SYM_ALG_AES_192_GCM
- THEMIS_AUTH_SYM_ALG_AES_128_GCM
SYM_ALG — general symmetric encryption algorithm
- THEMIS_SYM_ALG_AES_256_CTR (used by default)
- THEMIS_SYM_ALG_AES_192_CTR
- THEMIS_SYM_ALG_AES_128_CTR

As for asymmetric algorithms, we’re still working on making them switchable during compilation. However, for RSA you can change the key length at compilation time.

Caution: We strongly insist that using a key length less than 2048 should only be done due to performance considerations, in safe and trusted environments.

RSA_KEY_LENGTH — RSA key length in bits
- 1024
- 2048 (used by default)
- 4096

Building Themis language wrappers #

Language-specific wrappers enable you to use Themis in a particular language. Most of them can be installed with the same Makefile used to build Themis Core.

Check out the corresponding language guide for more details on how to build Themis wrapper for your language.

Note: For server-side development you need to install Themis Core first.

For iOS, Android, and WebAssembly you do not need to build Themis Core separately.