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.
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-https3. 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$OSshould bedebianorubuntu.$RELEASEshould be one of Debian or Ubuntu release names. You can determine this by runninglsb_release -cs, if you havelsb_releaseinstalled.
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.list4. Reload local package database:
sudo apt-get update5. Install the package
sudo apt-get install libthemisNote: 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/gpgNote: 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.repo3. Install the package:
sudo yum install libthemisThat's all! Themis is ready to use. The easiest way is to follow one of the tutorials and examples provided below.
- Fetch the repository: git clone https://github.com/cossacklabs/themis.git.
- Make sure OpenSSL/LibreSSL + OpenSSL/LibreSSL Dev package (libssl-dev) are installed at typical paths:
/usr/lib,/usr/include(/usr/local/*for macOS). - Make sure the typical GCC/clang environment is installed.
- Type 'make install' and you're done (in most of the cases).
- 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.
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 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 |
Themis-based plugins are built to enable Themis' features across various platforms and products:
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.
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.
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 |
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.
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.
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.
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].
