Skip to content

Rust Howto

Karen Sawrey edited this page Apr 8, 2019 · 18 revisions

Using Themis in Rust

Introduction

The Rust-Themis extension provides access to features and functions of Themis cryptographic library for applications written in Rust:

  • Key generation: creation of public/private key pairs, used in Secure Message and Secure Session.
  • Secure Message: secure exchange of messages between two parties. RSA + PSS + PKCS#7 or ECC + ECDSA (based on key choice), AES GCM container.
  • Secure Storage (aka Secure Cell): provides secure storage of record based data through symmetric encryption and data authentication. AES GCM / AES CTR containers.
  • Secure Session: establishment of a session between two peers within which the data can be securely exchanged with higher security guarantees. EC + ECDH, AES container.
  • Secure Comparator: compare the secret between two parties without leaking anything related to the secret: Zero-Knowledge Proof-based authentication system. Hardened Socialist Millionaire Protocol + ed25519.

You can learn more about Themis encryption library in Wiki documentation or on the official Cossack Labs Documentation Server (the most recent version).

Supported versions

Rust-Themis is tested and supported on the stable Rust compiler (Rust 1.31+).

Quickstart

Requirements

Rust-Themis uses pkg-config to locate the core Themis library. Please install pkg-config and make sure it's properly configured (you may need to tweak PKG_CONFIG_PATH if non-standard installation paths are used).

Rust-Themis generates C bindings on the fly with bindgen. Note that it requires libclang to work so you have to install this library. Usually, it's a part of the clang package available for your operating system.

Installing stable version from packages

Rust-Themis wrapper is available on crates.io. In order to use the wrapper, you still need to have the core library installed.

  1. Install Themis Core as a system library using your system's package manager.

    ⚠️ IMPORTANT: Rust-Themis requires core Themis headers to be installed, therefore you need to install the development package: libthemis-dev for Debian and Ubuntu, libthemis-devel for RHEL and CentOS.

  2. Add the following line to your Cargo.toml file:

    [dependencies]
    themis = "0.11"

Building latest version from source

If the stable package version does not suit your needs, you can manually build and install the latest version of Themis from source code.

  1. Build and install Themis Core library into your system.
  2. Add the following line to your Cargo.toml file:
    [dependencies]
    themis = { path = "/path/to/cloned/themis/repo" }

Configuring pkg-config

Currently, it is necessary to tweak pkg-config configuration on CentOS (regardless of the way that you use to install Themis Core). Please set the following environment variable before using Rust-Themis:

export PKG_CONFIG_PATH=/usr/lib/pkgconfig

Importing Themis

Import the necessary functions and you're good to go:

use themis::keygen::gen_ec_key_pair;

Examples

There are some examples in the docs/examples/rust directory. You can run them with Cargo:

cargo run --example keygen

These examples illustrate how to use Themis to build simple applications.

You may also find it helpful to peek into tests if you are not sure how to use the API.

Using Themis

Please refer to the API documentation of the themis crate and the Documentation Server to learn what features are provided by Themis and how to use them in your code.

Developing Themis for Rust

Rust-Themis uses standard Cargo tooling so developing the library itself is equally easy. Check out the latest source code from GitHub:

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

Then you can go ahead and, for example, build and run the test suite:

cargo test

or build and read the latest API documentation:

cargo doc --open

You can test your application with your local working copy of Themis by adding the following override to the application's Cargo.toml file:

[patch.crates-io]
themis = { path = "/path/to/themis/repo" }

We use the following Cargo tools to maintain the quality of the code base:

  • rustfmt: automated code formatting keeps the code style consistent.

  • clippy: static code analyzer detects possible issues early on.

If you wish to help develop and expand Rust-Themis, we strongly advise you to install and use these tools.

Please follow the general contribution process outlined in our guide.

Clone this wiki locally
You can’t perform that action at this time.