theassyrian / themis

Easy to use cryptographic framework for data protection: secure messaging with forward secrecy and secure data storage. Has unified APIs across ten platforms.

Themis provides strong, usable cryptography for busy people

---

Crypto library for storage and messaging for Swift, Obj-C, Android/Java, С++, JS, Python, Ruby, PHP, Go.

Themis is an open-source high-level cryptographic services library for mobile and server platforms, which provides secure data exchange and storage. The current stable release is 0.10.0, dated 6th of February 2018.

Important: If you're upgrading from Themis 0.9.6 or earlier, please see the Migration Guide.

Themis provides four important cryptographic services:

• Secure Message: a simple encrypted messaging solution for the widest scope of applications. Exchange the keys between the parties and you're good to go. Two pairs of the underlying crytosystems: ECC + ECDSA / RSA + PSS + PKCS#7.
• Secure Session: session-oriented, forward secrecy datagram exchange solution with better security guarantees, but more demanding infrastructure. Secure Session can perfectly function as socket encryption, session security, or (with some additional infrastructure) as a high-level messaging primitive. ECDH key agreement, ECC & AES encryption.
• Secure Cell: a multi-mode cryptographic container suitable for storing anything from encrypted files to database records and format-preserved strings. Secure Cell is built around AES in GCM (Token and Seal modes) and CTR (Context imprint mode).
• Secure Comparator: a Zero-Knowledge based cryptographic protocol for authentication and comparing secrets.

Want to go straight to the detailed documentation? Please proceed here.

We created Themis to build other products on top of it - i.e. Acra and Hermes.

Themis works on most operating systems (see Availability) and is available for Swift (iOS, macOS), Objective-C (iOS, macOS), Java+Android, Ruby, Python, PHP, C++, Javascript (NodeJS), Go, Google Chrome.

We're also porting Themis features to different environments where people might need them: Redis module, PostgreSQL module

Themis was designed to provide complicated cryptosystems in an easy-to-use infrastructure, with modern rapid development in mind:

• EASY: Themis does not require users to obsess over parameters, cipher combination, and yet it provides high levels of security.
• DO YOUR THING: Themis allows developers to focus on doing the necessary: developing their applications.
• BEST PRACTICE: Themis is based on the best modern practices in implementing complicated security systems.

Themis relies on the best available open-source implementations of cryptographic primitives (ciphers).

Themis is open source, Apache 2 Licensed.

Quickstart

Install Themis from Cossack Labs repository

Debian / Ubuntu

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 OSs 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),
• Ubuntu Artful Aardvark (Ubuntu 17.10).

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

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

That's all! Themis is ready to use. The easiest way is to follow one of the tutorials and examples provided below.

Install 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).
5. Visit our wiki for the documentation specific to your language of choice and take a look at docs/examples for examples.

It is a really good idea to go and read the docs after installing Themis, but we realise that Fortune favours the brave. Remember that you're always welcome in the documentation Wiki.

Languages

Themis is available for the following languages/platforms:

Platform	Documentation	Examples	Version
🔶 Swift (iOS, macOS)	Swift Howto	docs/examples/swift
📱 Objective-C (iOS, macOS)	Objective-C Howto	docs/examples/objc
☕️ Java / Android	Java & Android Howto	Java and Android projects
♦️ Ruby	Ruby Howto	docs/examples/ruby
🐍 Python	Python Howto	docs/examples/python
🐘 PHP	PHP Howto	docs/examples/php
➕ C++	CPP Howto	docs/examples/c++
🍭 Javascript (NodeJS)	NodeJS Howto	docs/examples/js
🐹 Go	Go-Howto	docs/examples/go
🕸 С++ PNaCl for Google Chrome		WebThemis project

Plugins

Themis-based plugins are built to enable Themis' features across various platforms and products:

• RD_Themis for Redis database
• PG_Themis for PostgreSQL database

Availability

Themis supports the following architectures: x86/x64, armv*, various Android architectures.

It is checked to compile on the latest stable versions of:

• Debian 7-9, CentOS 7, Ubuntu (14.04, 16.04, 17.10), Arch Linux 2014+,
• Windows XP+,
• macOS 10.12+,
• Android 4-8+ / CyanogenMod 11+,
• iOS9—iOS11+, x32/x64.

We plan to expand this list with broader set of platforms. If you'd like to help improve or bring Themis to your favourite platform / language — get in touch.

Tutorials

As long as it remains feasible, we'll be accumulating the list of all our tutorials on how to use Themis in different cases here:

• Releasing Themis into public: usability testing, which goes a bit into how to use Secure Message for iOS and Python. Go directly into corresponding github repository to play with code.
• Building encrypted chat service with Themis and mobile websocket example, which outlines stages necessary to build encrypted chat service around Ruby websocket server with clients in iOS and Android. Github repository with accompanying code.

Sample projects

During the development stage we frequently do Proof-of-Concept projects to test different assumptions. They serve as interesting demos of what Themis is capable of:

Demo	Description	Repo	Blog post
0fc	Anonymous web chat * Python * webthemis (C++ + HTML/JS)	repo	blog post
Sesto	Secure storage * Python * webthemis (C++ + HTML/JS)	repo	blog post
Swift Alps demo	Secure communication (iOS app with Python server based on Secure Session) * Swift * Python	repo	slides
Zero-Knowledge Architectures workshop	iOS app for storing and sharing encrypted notes stored in Firebase database * Swift	repo

Themis Server

If you'd like to experiment with Themis in a more interactive environment, check out Themis Server, interactive debugging environment for Themis. Themis Server can verify and decrypt code encrypted by Secure Cell or Secure Message, and provides a fully-functional backend for Secure Session. Examples for many languages are available in docs/examples/Themis-server.

Contributing to us

If you're looking for something to contribute to and gain eternal respect, just pick the things in the list of issues. Head over to our Contribution guidelines as your starting point.

Documentation

Project's GitHub Wiki contains the ever-evolving official documentation, which contains everything from deployment guidelines to use-cases, with a brief explanation of cryptosystems and architecture behind the main Themis library sandwiched in.

Contacts

If you want to ask a technical question, feel free to raise an issue or write to [email protected].

To talk to the business wing of Cossack Labs Limited, drop us an email to [email protected].