Easy to use cryptographic framework for data protection: secure messaging with forward secrecy and secure data storage. Has unified APIs across ten platforms.
Branch: master
Clone or download
ilammy Rust API Guidelines compliance (#383)
* Use impl Trait for Secure Comparator

* Drop outdated TODOs

We already handle errors in Secure Cell in acceptable way, there is no
need to panic. Similarly, Secure Comparator has good enough usage
pattern with "is_complete()" so we don't have to handle completion
differently.

* Use impl Trait for key types

* Fix typos in API docs

* Reorder Secure Comparator methods for better API docs

* Add Debug implementation for all public types

* Remove Clone implementation from Secure Message types

They do not really need to be copyable (like Secure Cells). If you need
to have use Secure Messages with the same keys then construct it twice.
However, this should not be necessary in the first place.

* Rename getter for remote peer ID

Rust generally does not use "get" prefixes for getters. Furthermore,
at some distant point we may want to add a getter for our own ID
so give this method a better name.

While we're here, I have noticed that the documentation comment lies.
This method should properly handle the case where peer ID is not known.
Peer IDs can't be empty so an empty result from underlying function
secure_session_get_remote_id() means that there is no peer ID stored
(i.e., the connection has not been negotiated yet).

* Rename getter for comparison result

Similarly, rename the getter without a "get" prefix because Rust APIs
prefer such naming.

* Unsafe impl Send for pointer types

Rust cannot automatically infer thread-safety traits for types which
use raw pointers. Secure Session and Secure Comparator are actually
movable across threads, but not safe for concurrent usage. Reflect
this by implementing Send but not Sync.

* Use ? operator instead of unwrap in API examples

Code snippets from documentation tend to be copy-pasted verbatim so
take care to avoid unexpected panics.
Latest commit 463f105 Feb 15, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Run C++ tests during CI builds (#379) Feb 14, 2019
docs Rust API Guidelines compliance (#383) Feb 15, 2019
gothemis support get_remote_id in gothemis (#272) Dec 29, 2017
gradle/wrapper Simplify Android build and bring up to date (#273) Jan 5, 2018
jni Update BoringSSL submodule config to use Clang and new gradle (#352) Jan 22, 2019
scripts Mozh/t380 php package (#304) Feb 1, 2018
src Rust API Guidelines compliance (#383) Feb 15, 2019
tests Rust API Guidelines compliance (#383) Feb 15, 2019
third_party/boringssl Update BoringSSL submodule config to use Clang and new gradle (#352) Jan 22, 2019
tools Crash triage tool for American Fuzzy Lop (#368) Feb 7, 2019
.gitignore Initial Rust binding (#340) Jan 12, 2019
.gitmodules Simplify Android build and bring up to date (#273) Jan 5, 2018
.travis.yml Add travis ci ios test Feb 6, 2017
CHANGELOG.md Cosmetic changes in the CHANGELOG Feb 5, 2018
CMakeLists.txt cpp tests (#292) Jan 25, 2018
CONTRIBUTING.md Create CONTRIBUTING.md Dec 4, 2017
Cargo.toml Secure Session example code (#381) Feb 15, 2019
Doxyfile Disable Graph building with doxygen Sep 29, 2015
ISSUE_TEMPLATE.md add installation way Dec 21, 2017
LICENSE Update LICENSE May 20, 2015
Makefile Fuzzing with american fuzzy lop (#364) Feb 4, 2019
README.md add more links to examples Oct 22, 2018
build.gradle add android distribution to build.gradle (#361) Feb 2, 2019
gradlew Added gradle wrapper Jun 1, 2015
gradlew.bat Added gradle wrapper Jun 1, 2015
settings.gradle Simplify Android build and bring up to date (#273) Jan 5, 2018
themis.podspec Update Themis.podspec to use bitcode (#355) Jan 24, 2019

README.md

Themis provides strong, usable cryptography for busy people

Themis provides strong, usable cryptography for busy people


GitHub release Circle CI Bitrise Platforms Coverage Status


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 CocoaPods
📱 Objective-C (iOS, macOS) Objective-C Howto docs/examples/objc CocoaPods
☕️ Java / Android Java & Android Howto Java and Android projects
♦️ Ruby Ruby Howto docs/examples/ruby Gem
🐍 Python Python Howto docs/examples/python PyPI
🐘 PHP PHP Howto docs/examples/php
C++ CPP Howto docs/examples/c++
🍭 Javascript (NodeJS) NodeJS Howto docs/examples/js npm
🐹 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:

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:

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 dev@cossacklabs.com.

To talk to the business wing of Cossack Labs Limited, drop us an email to info@cossacklabs.com.

Blog Twitter CossackLabs Medium CossackLabs Join the chat at https://gitter.im/cossacklabs/themis