Installing Acra from the 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 the key fingerprint, it is: 29CF C579 AD90 8838 3E37 A8FA CE53 BCCA C8FF FACB 2. Add the Cossack Labs repository to your sources.list. You should add a line that specifies your OS name and the release name:| Cossack Labs Documentation Server on Cossack Labs
AcraServer configuration # Here we describe how to set up AcraServer to reach a state where it can process queries. List of all command line flags for AcraServer is located here. Configuration file # There are two ways of configuring AcraServer: via command line flags via configuration file The YAML file is passed with --config_file=path/to/config.yml flag. To use this file as configuration source, you simply move flags into it, --foo=1 will become foo: 1 and --bar=test will become bar: "test".| Cossack Labs Documentation Server on Cossack Labs
AcraTranslator configuration # Here we describe how to set up AcraTranslator to reach a state where it can process queries. List of all command line flags for AcraTranslator is located in Configuring and maintaining. Configuration file # There are two ways of configuring AcraTranslator: via command line flags via configuration file The YAML file is passed with --config_file=path/to/config.yml flag. To use this file as configuration source, you simply move flags into it, --foo=1 will become fo...| Cossack Labs Documentation Server on Cossack Labs
Certificate generation with OpenSSL # Here you will see few tips about how certificates can be generated using openssl CLI tool. This is more like a collection of tips, and it doesn’t pretend to be exhaustive. In production settings, make sure at least that: your private keys are kept safe; certificate extensions are properly configured; apps that use these certificates are properly configured. A lot of things require attention in order to work as expected and remain secure.| Cossack Labs Documentation Server on Cossack Labs
Client side encryption with AcraConnector and AcraWriter # AcraConnector is deprecated since 0.91.0 and is not available since 0.92.0. Use TLS between client application and AcraServer / AcraTranslator instead. AcraWriter is available in Acra Enterprise Edition only. This guide describes the process of setting up and configuring AcraConnector and AcraWriter to encrypt data on client-side application before sending to the database. This is a general guide, the language and framework of client ...| Cossack Labs Documentation Server on Cossack Labs
Encryptor config # This config is responsible for configuration of proactive security controls of AcraServer. AcraServer supports several types of storages for encryptor_config loading: HashiCorp Consul KV storage and Filesystem. Storage type can be specified via --encryptor_config_storage_type=<filesystem|consul> flag. To configure filesystem as storage type, specify --encryptor_config=<path> CLI parameter or encryptor_config key in YAML configuration file for AcraServer. For HashiCorp Consu...| Cossack Labs Documentation Server on Cossack Labs
Frequently Asked Questions # When will there be a platform X, language Y ready # We don’t have an exact roadmap of availability, but we will cover most of the platforms we initially aimed at in the first couple of releases. If your favourite language is unavailable, it was either intentional — some languages and infrastructures have limitations that limit the ability to interface the objects properly — or it’s just not on our roadmap and your feedback might change that.| Cossack Labs Documentation Server on Cossack Labs
Installing Themis from packages # Installing Themis Core # The core library is available via Cossack Labs package repositories. Follow the instructions below for your operating system. In case you experience issues during installation, refer to Troubleshooting installation page which contains the wisdom of ages. Debian, Ubuntu # Supported systems: Debian 10 “Buster” Debian 11 “Bullseye” Debian 12 “Bookworm” Ubuntu 20.04 LTS “Focal Fossa” Ubuntu 22.04 LTS “Jammy Jellyfish” ...| Cossack Labs Documentation Server on Cossack Labs
Installing Hermes from repository # To see Hermes-core working, you need to perform the following actions. Hermes-core is available for the following versions of operating systems: *.deb: Debian: Wheezy, Jessie, Stretch; Ubuntu: Trusty Tahr, Xenial Xerus, Yakkety Yak, Zesty Zapus. *.rpm: CentOS: 7. Installing for Debian / Ubuntu # Import the public key used by Cossack Labs to sign packages: wget -qO - https://pkgs.| Cossack Labs Documentation Server on Cossack Labs
Integrating Acra with Django app: short tutorial # AcraWriter is available in Acra Enterprise Edition only. This tutorial outlines a typical process of integrating Acra into a Python web app. More specifically – an app running on Django framework. It is based on the popular example where many Django users start their development journey with – djangoproject.com repository. We will be integrating AcraWriter to protect blog posts. This tutorial assumes that you have both AcraServer and Post...| Cossack Labs Documentation Server on Cossack Labs
Integrating Acra with Ruby on Rails app: short tutorial # AcraWriter is available in Acra Enterprise Edition only. This tutorial outlines a typical process of integrating Acra into a Ruby web app (more specifically, an app running on Ruby on Rails framework). It is based on the popular example where many Ruby users start their development learning with – rubygems.org repository. Here we will integrate AcraWriter to protect the gem descriptions.| Cossack Labs Documentation Server on Cossack Labs
Inventory of Acra keys # Acra uses many keys, but the key hierarchy is built to satisfy both security and usability requirements. Depending on how many features, ClientIDs, and Acra services you use, your system will operate minimum of 2 keys (one Acra Master key and one storage symmetric key) to hundreds. The key hierarchy is illustrated in the table below (with abbreviations used: AS – AcraServer; AT – AcraTranslator; AC – AcraConnector; service means one instance of AcraServer/AcraTr...| Cossack Labs Documentation Server on Cossack Labs
Key generation # During the initial setup of Acra you will need to generate new keys for all components involved. Acra Master Key(s). Storage keys and searchable encryption keys. At least for one client ID or zone ID. Storage keys are the ones responsible for data encryption. There are two kinds of crypto containers (AcraStructs and AcraBlocks) and two different kinds of keys for them (storage symmetric keys and storage asymmetric keys).| Cossack Labs Documentation Server on Cossack Labs
list # list is acra-keys subcommand used for describing keys of the keystore versions v1|v2. Command line flags # General flags # --rotated-keys List rotated keys if present in keystore (available since 0.95.0). TLS (available since 0.96.0) # --tls_auth=<mode> Set authentication mode that will be used for TLS connection. 0 — do not request client certificate, ignore it if received; 1 — request client certificate, but don’t require it; 2 — expect to receive at least one certificate to ...| Cossack Labs Documentation Server on Cossack Labs
Logging formats # Acra services write logs to stderr. If you need to redirect logs to a file or to a log collector service, please redirect stderr. Plaintext # Nothing fancy – the most human-readable format. If you are running Acra in a terminal, log lines will be colored for extra readability. time="2021-07-01T19:34:14+03:00" level=info msg="Starting service acra-server [pid=304870]" version=0.85.0 time="2021-07-01T19:34:14+03:00" level=info msg="Validating service configuration..." time="...| Cossack Labs Documentation Server on Cossack Labs
Migration from keystore v1 to v2 # In order to migrate from keystore version 1 to version 2, use acra-keys utility. acra-keys migrate \ --src_keystore=v1 --src_keys_dir ".acrakeys" \ --dst_keystore=v2 --dst_keys_dir ".acrakeys.v2" You need to put the Acra Master Key to the source keystore into SRC_ACRA_MASTER_KEY and the destination Acra Master Key into DST_ACRA_MASTER_KEY. New keystore will be created at .acrakeys.v2. Note: You can use the --dry_run option to test the migration and be sure t...| Cossack Labs Documentation Server on Cossack Labs
Model, process, entity # The following descriptions are aimed at helping you understand the general concept of Hermes. Hermes model # The main goal of Hermes is to cryptographically enforce the data access control policy and to minimise the risks of compromisation of a single Hermes’ component (or a subset of such components). Such enforcements are achieved by: reducing the risk of potential damage from a security breach by distributing the components of Hermes; limiting/blocking the exposu...| Cossack Labs Documentation Server on Cossack Labs
Python tutorial for Hermes-core # In this tutorial, we are going to launch storage entities for data, public and encryption keys, and will save/delete/edit the data with the help of a Hermes-core console app, as well as grant/revoke access to the data for other users. All this will be carried out cryptographically. Launching the storage entities # The infrastructure of Hermes-core is divided into 3 parts (you can read more about each entity in Abstract entities and in the scientific paper on ...| Cossack Labs Documentation Server on Cossack Labs
Security logging # Acra services log tons of activities – incoming connections, SQL firewall actions, encryption/decryption errors, key accesses and many more. Logs from AcraServer and AcraTranslator follow the same structure and format, but can have slightly different content (for example, AcraTranslator won’t have SQL Request Firewall related logs, since it doesn’t have integrated SQL Request Firewall module.) Acra services support logging in different formats (including CEF), and can...| Cossack Labs Documentation Server on Cossack Labs
Soter library # Soter is a cross-platform multipurpose cryptographic library that serves as a backbone for Themis. It provides a set of highly secure cryptographic primitives through a well-defined, consistent, and simple interface. To name just a few things you can get with Soter (as the rabbit hole of its true capabilities runs much, much deeper): cryptographic primitives necessary for building robust secure solutions intuitive, well-defined interface for cryptographic functions compile-tim...| Cossack Labs Documentation Server on Cossack Labs
status # status is acra-tokens subcommand used for getting output of token storage statistics. Command line flags # General configuration # --accessed_after=<date> Limit action to tokens accessed after specified date. --accessed_before=<date> Limit action to tokens accessed before specified date. --created_after=<date> Limit action to tokens created after specified date. --created_before=<date> Limit action to tokens created before specified date. TLS (available since 0.| Cossack Labs Documentation Server on Cossack Labs
Themis and OWASP # Themis is recommended by OWASP as data encryption library for mobile platforms.| Cossack Labs Documentation Server on Cossack Labs
TLS # Acra services such as AcraServer and AcraTranslator support TLS connection from client applications. It means that client application sends data in a plaintext to AcraServer/AcraTranslator to encrypt, and the only protection layer the data has – is TLS. Apart from the fact that the transport layer will be encrypted, TLS has another important role: client authentication and key selection. TLS certificate presented to AcraServer or AcraTranslator will prove that it’s indeed a legitima...| Cossack Labs Documentation Server on Cossack Labs
Migration guide # Please read the migration guide if at some point you used Acra version 0.77.0 - in Acra 0.80.0 some radical renaming was applied throughout. The migration guide of moving from Acra 0.77.0 to Acra 0.80.0. We did a global renaming of Acra components and configuration parameters for most of them. We believe that updated naming will decrease confusion about components' functions and will make Acra setup and usage easier.| Cossack Labs Documentation Server on Cossack Labs
Updating Themis 0.9.6 ⟹ 0.10.0 # This is a migration guide on moving from Themis 0.9.6 to Themis 0.10.0. Secure Cell compatibility # In Themis 0.10.0 we fixed an issue with incompatibility (#279) between 32-bit and 64-bit platforms when using Secure Cell. The issue was in Themis Core library which applied to every language wrapper. In short, the plaintext encrypted on 32-bit platforms couldn’t be decrypted on 64-bit platforms and vice versa.| Cossack Labs Documentation Server on Cossack Labs
US crypto export regulations for Themis # When you distribute apps via platforms like App Store or Google Play, the binaries are typically hosted on servers located within US, owned by US companies. United States laws treat this activity as export, which is heavily regulated for cryptography. However, typical Themis use cases fall under “open source” exceptions. This makes compliance much easier if your app is open source as well.| Cossack Labs Documentation Server on Cossack Labs
Vertical scaling # CPU cores # When switching from one CPU core to two on AcraServer machine, the performance is roughly doubled. So it is recommended to give AcraServer machine at least two of them. Acra supports parallelism well, therefore, to maintain a high level of performance, it is recommended to increase the number of cores in accordance with the increase in the number of parallel client connections and the overall load.| Cossack Labs Documentation Server on Cossack Labs
Abstract entities # Hermes-core is divided into the 2 core pieces: Backend or Server-side (Server/storage), which is outlined in this document, Hermes-core server and Hermes-core transport. Frontend or Client-side (Client), which is outlined in a Hermes-core client. Storage # Storage entity must have 3 separate parts (the parts can be allocated in virtually any way, but an active compartmentalisation on the database’s side adds an extra layer of security):| Cossack Labs Documentation Server on Cossack Labs
Launching Acra from Docker images # You can use containers with Acra. Acra works well with Docker. Precautions # Storing keys safely when using Docker is problematic. Docker is immutable while Zones/keys are not. This means that you might want to attach some storage and end up making the keys accessible to attackers. There are multiple ways to solve this problem, and it can be addressed in a convenient and secure fashion depending on your specific infrastructure.| Cossack Labs Documentation Server on Cossack Labs
AcraBlock # AcraBlock is a symmetric cryptographic container, it is more compact than AcraStruct. Acra uses an envelope encryption strategy: plaintext data is encrypted using data encryption key (DEK), and then DEK is encrypted using key encryption key (KEK). AcraBlock uses AES-256-GCM-PKCS#7 for both encryption procedures. See Cryptography and key management / Application level encryption. AcraBlock supports key rotation: it’s possible to rotate only KEK without re-encrypting the data (kno...| Cossack Labs Documentation Server on Cossack Labs
AcraConnector (deprecated since 0.91.0) # Starting from version 0.91.0 Acra only supports TLS as a transport security. Refer to TLS section to read how to configure TLS connection. AcraConnector is a proxy-daemon component that lives nearby client application (perfectly, on the same server / VM). AcraConnector is an optional components created purely to improve transport security and authentication between client application and AcraServer/AcraTranslator. AcraConnector creates a secure connec...| Cossack Labs Documentation Server on Cossack Labs
AcraWriter # AcraWriter is available in Acra Enterprise Edition only. AcraWriter — a client-side library that only encrypts the data into Acra’s encryption envelopes (AcraStructs and AcraBlocks). AcraWriter is available for Ruby, Python, Go, NodeJS, iOS (Objective-C/Swift) and Android (Java, Kotlin). AcraWriter only encrypts data, it cannot decrypt it. Application uses AcraWriter SDK to encrypt data on application side, and sends it to the database directly. Later, application reads the d...| Cossack Labs Documentation Server on Cossack Labs
Installing JavaThemis for Android development # JavaThemis for Android is available in the Maven Central repository. Usually you want to install the stable package to benefit from automatic dependency management and security updates. However, you can also build and install the latest JavaThemis from the source code. Important: If your application uses Themis and you want to submit it to the Google Play, there are certain requirements towards declaring use of any cryptography.| Cossack Labs Documentation Server on Cossack Labs
Installing JavaThemis for Android development # JavaThemis for Android is available in the Maven Central repository. Usually you want to install the stable package to benefit from automatic dependency management and security updates. However, you can also build and install the latest JavaThemis from the source code. Important: If your application uses Themis and you want to submit it to the Google Play, there are certain requirements towards declaring use of any cryptography.| Cossack Labs Documentation Server on Cossack Labs
Cryptographically signed audit logging # To ensure that security log is secure itself, Acra provides cryptographic protection/validation of exported logs to prevent tampering. Acra’s audit log covers access, security events, ties sessions to consumers and extends application-level audit log with strong evidence. Acra supports secure and verifiable logging for AcraServer, AcraTranslator. It is designed to prevent unnoticeable tampering of log messages and log files of the mentioned services....| Cossack Labs Documentation Server on Cossack Labs
Keystore backups # It is important to keep backup copies of Acra keystore because this is one thing that if lost can make your data completely inaccessible to anyone. Keystore contents are also very sensitive because if leaked, your data may become completely accessible to anyone. Therefore, it is crucial to make and store backups of the keystore securely. Acra has a number of tools to help you with this task.| Cossack Labs Documentation Server on Cossack Labs
Benchmarking recommendations # It may be quite easy to end up making wrong conclusions about performance bottleneck after running benchmarks. Here are some recommendations to take into account when measuring performance with Acra: Make sure you created all needed indexes in a database (for encrypted columns, see searchable encryption). Make sure you reuse connections to AcraServer, otherwise the application will spend a lot of time just waiting for the connection to be created (this also crea...| Cossack Labs Documentation Server on Cossack Labs
Building Hermes # You need to start with installing the libraries and utilities that we’re going to need. For Debian the command is: sudo apt-get update && sudo apt-get install build-essential libssl-dev git We need build-essential for building binary libraries and libssl-dev as backend for Themis. Let’s download and install Themis into your system: git clone https://github.com/cossacklabs/themis cd themis make && sudo make install cd .. Now you should download and install Hermes-core:| Cossack Labs Documentation Server on Cossack Labs
Installing ThemisPP # ThemisPP is available as a system package for Linux and macOS. Usually you want to install the stable package to benefit from automatic dependency management and security updates. However, you can also build and install the latest ThemisPP from the source code. Installing stable version on Linux # The easiest way to install ThemisPP on Linux is to use package repositories for your system. We build packages for a multitude of Linux distributions.| Cossack Labs Documentation Server on Cossack Labs
Client ID # Every application wishing to interact with AcraServer should provide an identifier called client ID. Based on the client ID, AcraServer will choose corresponding encryption keys to process client requests. To pass client ID from application to AcraServer you should make AcraServer derive identifier from client TLS certificate. Also, one can avoid doing it and set static client ID with --client_id flag to Acra. For AcraTranslator, however, there is one more method: specifying clien...| Cossack Labs Documentation Server on Cossack Labs
Client ID # Every application wishing to protect their data with AcraTranslator should provide an identifier called client ID. Based on the client ID, AcraTranslator will choose corresponding encryption keys to process client requests. The way how application can pass client ID to AcraTranslator depends on API type: gRPC or HTTP. gRPC API # By default, application have to specify client ID in every request was sent to AcraTranslator except when --acratranslator_client_id_from_connection_enabl...| Cossack Labs Documentation Server on Cossack Labs
Cryptography donors # “So do you roll your own crypto?” # If you’re reading this section, you might already know the short answer: No. We don’t roll our own crypto. Themis relies on algorithm implementations that come from platform providers and open-source projects. We believe that anyone in their right mind should use well-known, audited implementations of well-known and proven cryptographic ciphers for their core security needs. We’ve built Themis to have easy-to-use large buildi...| Cossack Labs Documentation Server on Cossack Labs
Themis development security practices # Our approach to testing Themis: Every Themis PR is checked with CircleCI, Bitrise, and GitHub Actions, which run a set of tests on the whole code base across 13 languages. Every major Themis release is tested by our internal systems, by building it on a number of platforms (including intentionally broken builds with wrong parameters). Every time some new security-related features are introduced to Themis, they undergo a brief 3rd-party code review.| Cossack Labs Documentation Server on Cossack Labs
disable # disable is acra-tokens subcommand used for disabling tokens and preventing their use. Command line flags # General configuration # --accessed_after=<date> Limit action to tokens accessed after specified date. --accessed_before=<date> Limit action to tokens accessed before specified date. --created_after=<date> Limit action to tokens created after specified date. --created_before=<date> Limit action to tokens created before specified date. TLS (available since 0.| Cossack Labs Documentation Server on Cossack Labs
generate # generate is acra-keys subcommand used for generating keys (for both v1, v2 keystore versions). Command line flags # General flags # --client_id=<id> 🔴 Use provided ClientID as identifier to generate keys or keypairs. --tls_cert=<path> (deprecated since 0.96.0) Path to TLS certificate to use as ClientID identifier. Works only when passed empty ClientID: --client_id="". Use --tls_client_id_cert instead. --tls_client_id_cert=<path> Path to TLS certificate to use as ClientID identif...| Cossack Labs Documentation Server on Cossack Labs
Installing GoThemis # GoThemis can be installed with the usual go get. Additionally, Themis Core library has to be installed in your system as well. Themis Core is available as a system package for Linux and macOS. Usually you want to install the stable package to benefit from automatic dependency management and security updates. However, you can also build and install the latest GoThemis from the source code. Installing stable version on Linux # The easiest way to install Themis on Linux is ...| Cossack Labs Documentation Server on Cossack Labs
Go tutorial for Hermes-core # In this tutorial, we are going to launch storage entities for data, public and encryption keys, and will save/delete/edit the data with the help of a Hermes-core console app, as well as grant/revoke access to the data for other users. All this will be carried out cryptographically. Launching the storage entities # The infrastructure of Hermes-core is divided into 3 parts (you can read more about each entity in Abstract entities and in the scientific paper on Herm...| Cossack Labs Documentation Server on Cossack Labs
Hermes-core client # The Client for Hermes-core needs to have access to all the 3 Stores (Data store, Credential store, Keystore). The key (token) used by the Client must be present in the Credential store on the Server side of Hermes-core to allow for further operations on documents. It’s also recommended that you take a look at the example Clients written in C, Python, and Go before proceeding with building your own.| Cossack Labs Documentation Server on Cossack Labs
Horizontal scaling # Generally, Acra has no problems with horizontal scaling. You will most likely want one AcraServer per one database instance. We got docker-compose-based demo with two PostgreSQL+AcraServer instances and haproxy balancer and a simple app.| Cossack Labs Documentation Server on Cossack Labs
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.| Cossack Labs Documentation Server on Cossack Labs
Integrating Acra with Django app: step-by-step tutorial # AcraWriter is available in Acra Enterprise Edition only. Zones are deprecated since 0.94.0, will be removed in 0.95.0. This tutorial is an extensive step-by-step guide for those who have never used Themis and Acra before. There is also a much shorter version for the experienced Acra users. If it’s your very first encounter with Acra, keep reading. Intro # Acra is a database security suite, which protects you against data leaks and ma...| Cossack Labs Documentation Server on Cossack Labs
Integrating Acra with Ruby on Rails app: step-by-step tutorial # AcraWriter is available in Acra Enterprise Edition only. Zones are deprecated since 0.94.0, will be removed in 0.95.0. This tutorial is an extensive step-by-step guide for those who have never used Themis and Acra before. There is also a much shorter version for the experienced Acra users. If it’s your very first encounter with Acra, keep reading.| Cossack Labs Documentation Server on Cossack Labs
KMS # As Acra stores all intermediate keys encrypted, it needs Acra Master Key to decrypt them. KMS is used to store Acra Master Key. While KMS can be used to store all the intermediate keys, we strongly don’t recommend it, as it might be quite expensive and might become performance bottleneck. KMS' functionality # Most Acra services and tools, like AcraServer, AcraTranslator and AnyProxy, can read Acra Master Key from environment variable, but they can read it from KMS as well.| Cossack Labs Documentation Server on Cossack Labs
KMS integration # KMS plays an important role for providing cryptographic keys security. Currently, Acra uses KMS to load Acra Master Key used for intermediate keys encrypting / decrypting. Since safety of Acra’s cryptographic keys directly depends on safety of Acra Master Key, Acra has strong requirements to KMSs and their security guarantees. Refer to Acra in depth / Key storage and KMS to learn more about general key storage requirements.| Cossack Labs Documentation Server on Cossack Labs
Logging error codes # Most errors logged by Acra have their own error code. Error codes for different events in Acra services are divided by groups and service. List of basic error codes and their groups: Code Error Group 100 EventCodeGeneral General 505 EventCodeErrorCantStartService Processes 510 EventCodeErrorCantInitKeyStore Keys 540 EventCodeErrorCantConnectToDB Database 560 EventCodeErrorCensorQueryIsNotAllowed Acracensor 700 EventCodeErrorTranslatorCantHandleHTTPRequest AcraTranslator ...| Cossack Labs Documentation Server on Cossack Labs
Installing JsThemis # JsThemis is available on npm and can be installed with the usual npm install. Additionally, Themis Core library has to be installed in your system as well. Themis Core is available as a system package for Linux and macOS. Usually you want to install the stable package to benefit from automatic dependency management and security updates. However, you can also build and install the latest JsThemis from the source code.| Cossack Labs Documentation Server on Cossack Labs
TLS certificate validation using OCSP # OCSP-related flags and their description. Works for acra-connector, acra-server and acra-translator. --tls_ocsp_url=<url> URL of OCSP service. Empty by default. Should point to HTTP server that accepts application/ocsp-request MIME type and responds with application/ocsp-response. For acra-server it will work like --tls_ocsp_client_url and --tls_ocsp_database_url passed simultaneously with same value. For acra-connector and acra-translator (that can onl...| Cossack Labs Documentation Server on Cossack Labs
Installing PHPThemis # PHPThemis is available as a system package for Linux. Usually you want to install the stable package to benefit from automatic dependency management and security updates. However, you can also build and install the latest PHPThemis from the source code. Installing stable version on Linux # The easiest way to install PHPThemis on Linux is to use package repositories for your system. We build packages for a multitude of Linux distributions.| Cossack Labs Documentation Server on Cossack Labs
Installing PyThemis # PyThemis is available on PyPi and can be installed with the usual pip install. Additionally, Themis Core library has to be installed in your system as well. Themis Core is available as a system package for Linux and macOS. Usually you want to install the stable package to benefit from automatic dependency management and security updates. However, you can also build and install the latest PyThemis from the source code.| Cossack Labs Documentation Server on Cossack Labs
Installing Themis for React Native # React Native Themis is available on npm and can be installed using npm install. Install React Native Themis via npm for your project: npm install --save react-native-themis or yarn add react-native-themis Install Pods for iOS: cd ios pod install Once React Native Themis is installed, you can try out code examples.| Cossack Labs Documentation Server on Cossack Labs
Installing RbThemis # RbThemis is available on RubyGems and can be installed with the usual gem install. Additionally, Themis Core library has to be installed in your system as well. Themis Core is available as a system package for Linux and macOS. Usually you want to install the stable package to benefit from automatic dependency management and security updates. However, you can also build and install the latest RbThemis from the source code.| Cossack Labs Documentation Server on Cossack Labs
Installing RustThemis # RustThemis is available on crates.io. Additionally, Themis Core library has to be installed in your system as well. Themis Core is available as a system package for Linux and macOS. Usually you want to install the stable package to benefit from automatic dependency management and security updates. However, you can also build and install the latest RustThemis from the source code. RustThemis uses pkg-config to locate Themis Core, if available.| Cossack Labs Documentation Server on Cossack Labs
Secure Cell # Secure Сell is a high-level cryptographic container aimed at protecting arbitrary data stored in various types of storages (e.g., databases, filesystem files, document archives, cloud storage, etc.). It provides a simple way of securing your data using strong encryption and data authentication mechanisms, with easy-to-use interfaces for a broad range of use cases. Availability in Themis # Secure Cell is available in all languages supported by Themis:| Cossack Labs Documentation Server on Cossack Labs
Installing Themis for iOS and macOS # Themis can be installed with SPM, CocoaPods and Carthage. Usually you want to install the stable package to benefit from automatic dependency management and security updates. It is also possible to build the latest version of Themis from source, but it is highly non-trivial. Please drop us an email if you need assistance. Installing with SPM # Themis is available via SPM (Swift Package Manager).| Cossack Labs Documentation Server on Cossack Labs
Installing Themis for iOS and macOS # Themis can be installed with SPM, CocoaPods and Carthage. Usually you want to install the stable package to benefit from automatic dependency management and security updates. It is also possible to build the latest version of Themis from source, but it is highly non-trivial. Please drop us an email if you need assistance. Installing with SPM # Themis is available via SPM (Swift Package Manager).| Cossack Labs Documentation Server on Cossack Labs
Threat models and security guarantees # Acra is built to provide selective encryption only to the records that require such protection. Thus, such records are sensitive assets that are subject to certain risks and threats, which Acra helps to mitigate. Depending on the environment where Acra runs and the dataflow of sensitive data, threat models and mitigations are different. Acra is built as modular system that allows to achieve different security guarantees.| Cossack Labs Documentation Server on Cossack Labs
Troubleshooting installation # Troubleshooting installation on Ubuntu # Expired Let’s Encrypt root certificate # If you see errors like “Certificate verification failed” or “gpg: no valid OpenPGP data found” when installing Themis Core on Ubuntu, make sure that OS uses the latest Let’s Encrypt root certificate. $ sed -i 's|mozilla/DST_Root_CA_X3.crt|!mozilla/DST_Root_CA_X3.crt|' /etc/ca-certificates.conf $ update-ca-certificates| Cossack Labs Documentation Server on Cossack Labs
Installing WasmThemis # WasmThemis is available on npm and can be installed with the usual npm install. Usually you want to install the stable package to benefit from automatic dependency management and security updates. However, you can also build and install the latest WasmThemis from the source code. Installing stable version with npm # Just run the following line to install WasmThemis for your project: npm install wasm-themis Once WasmThemis is installed, you can try out code examples.| Cossack Labs Documentation Server on Cossack Labs
What is Acra? An overview. # Acra is an application-level encryption and data security toolkit for modern distributed applications. Acra allows app developers to encrypt sensitive data, manage the keys, apply tokenization, data masking, request filtering, generate audit logs and security events, automate reactions on security boundary. In short, Acra provides you with means to protect the data, detect incidents and respond to them. Acra is written in Go, aimed for modern cloud applications th...| Cossack Labs Documentation Server on Cossack Labs
What is Hermes? An overview. # Hermes — cryptographic framework for building multi-user end-to-end encrypted data storage and sharing/processing with zero leakage risks from storage and transport infrastructure (so called end-to-end encrypted zero knowledge architectures). Hermes acts as a protected data circulation layer with cryptographic access control for your distributed application, with zero security risk of data exposure from servers and storage. Hermes allows deploying end-to-end e...| Cossack Labs Documentation Server on Cossack Labs
Installing Acra from sources # In most cases, you don’t want to install Acra from sources, use packages or Docker instead. These are the instruction for installation of AcraServer from the Cossack Labs' GitHub repository for Acra. You will need the same set of dependencies for each component. Installing the dependencies # Install the dependencies for Acra: Debian / Ubuntu sudo apt-get install git libssl-dev make build-essential RHEL / CentOS / OEL| Cossack Labs Documentation Server on Cossack Labs
Acra on DigitalOcean Marketplace # We always strive to make high-end security tools available to the general developer audience in a convenient fashion. Only by making data security accessible, we can ensure real security of sensitive data everywhere. As another step towards our mission, we are proud to announce that Acra encryption suite is now available as 1-Click App running in a Droplet on DigitalOcean Marketplace. See our blog post for more details.| Cossack Labs Documentation Server on Cossack Labs
AcraReader # AcraReader is available in Acra Enterprise Edition only. AcraReader — a client-side library that only decrypts the data from Acra’s encryption envelopes (AcraStructs and AcraBlocks). AcraReader is available for Ruby, Python, Go, NodeJS, iOS (Objective-C/Swift) and Android (Java, Kotlin). AcraReader only decrypts data, it cannot encrypt it. Application uses AcraReader SDK to decrypt encrypted data on application side. Typically, AcraReader is used for building fully or partial...| Cossack Labs Documentation Server on Cossack Labs
AcraStruct # AcraStruct is an asymmetric cryptographic container. In a nutshell, it encrypts data using symmetric encryption, and then encrypts the key using asymmetric encryption. AcraServer and AcraTranslator can encrypt/decrypt AcraStructs, but the main gem of AcraStructs is client-side encryption. Due to the asymmetric nature, client application can generate AcraStructs (encrypt data into AcraStructs) without risks, as only Acra’s public key is exposed. AcraStruct supports key rotation:...| Cossack Labs Documentation Server on Cossack Labs
AcraStructs vs AcraBlocks # Acra services support two types of cryptographic containers: AcraStruct and AcraBlock. Plaintext data is encrypted using one container or another. Then, encrypted data is stored in the database and decrypted back by AcraServer/AcraTranslator when needed. Always prefer using AcraBlocks except when data is encrypted on client-side using AcraWriter. AcraStructs use asymmetric cryptography and are generally slower. Read more on When use AcraBlocks and when AcraStructs.| Cossack Labs Documentation Server on Cossack Labs
API design and processes # Hermes-core API is a convenient library, which exposes the high-level functions of Hermes-core to consumer applications. Internally, it is a small wrapper around the Hermes-core remote APIs: it serialises requests from the consumer applications and forwards them to Hermes-core via communication channels. Since the requests may contain sensitive data, the communication channel between Hermes API and Hermes-core should be encrypted and mutually authenticated. This can...| Cossack Labs Documentation Server on Cossack Labs
Building example apps # The Hermes-core application architecture requires the four main system components: Credential Store, Data Store, Keystore, Client. Hermes-core repository currently includes usage examples in C, Python, and Go for Client side and an example in C for Credential/Data/Keystore. The examples in Hermes-core use the file system as a storage entity (backend) for Credential store, Keystore, and Data store. The examples use simple TCP/IP socket communication as transport layer.| Cossack Labs Documentation Server on Cossack Labs
C tutorial for Hermes-core # In this tutorial, we are going to launch storage entities for data, public and encryption keys, and will save/delete/edit the data with the help of a Hermes-core console app, as well as grant/revoke access to the data for other users. All this will be carried out cryptographically. Launching the storage entities # The infrastructure of Hermes-core is divided into 3 parts (you can read more about each entity in Abstract entities and in the scientific paper on Hermes):| Cossack Labs Documentation Server on Cossack Labs
Example projects with ThemisPP # Once you have installed ThemisPP, it’s time to give it some action! Code samples # Some code samples for Themis features are available at docs/examples/c++ on GitHub: file encryption using Secure Cell a simple chat server and client using Secure Message and Secure Session You can also take a look at unit tests in ThemisPP source code. What’s next # Read the feature guide to learn how to use Themis features effectively in C++.| Cossack Labs Documentation Server on Cossack Labs
Command-line utilities # Some of the language wrappers for Themis are supplied with console utilities. They help to understand the specific mechanics of encryption/decryption processes. The command-line tools can encrypt and decrypt data through Secure Cell or Secure Message modes on your local machine using the command line. The tools are located in the tools directory, one for each supported language. You will need to install an appropriate Themis language wrapper to use a tool.| Cossack Labs Documentation Server on Cossack Labs
Client-side encryption # This feature is available in Acra Enterprise Edition only. As we describe in Acra in depth / Architecture, data encryption can happen in client application using AcraWriter SDK. AcraWriter SDK allows client application to encrypt data into AcraStructs/AcraBlocks and then send encrypted. It means that even if a client application doesn’t use TLS or works in a hostile environment, the data is still sent encrypted. Application can send it directly to the database omitt...| Cossack Labs Documentation Server on Cossack Labs
Contributing to Themis # Themis is an open-source, Apache 2 licensed software, maintained by Cossack Labs for building reliable cryptography in our products: Acra, Hermes and Toughbase. You can hack it in any way you want and contribute things back if you need something more than what we provide. As a development company, we focus on implementing features that are important to our products but would gladly spend some time to make Themis useful for everybody.| Cossack Labs Documentation Server on Cossack Labs
Credits and honourable mentions # Significant contributions to Themis encryption library have been made by Ignat Korchagin (@ignatk) and Andrey Mnazakanov (@mnaza). As for 2021, Themis is supported by core crew: @radetsky as React Native engineer. @iamnotacake as hands-on software engineer. @ilammy who joined as a Rust contributor, but ended up bringing joy and order to the whole repository. @vixentael who joined as a mobile developer, but is maintaining Themis for many years now.| Cossack Labs Documentation Server on Cossack Labs
TLS certificate validation using CRL # Only CRL v1 with basic fields is currently supported. This means Acra will be able to download CRL, verify it, and search for a certificate serial number there. But more advanced features like CRL extensions (including delta CRLs) are not handled yet. CRL-related flags and their descriptions. Works for acra-connector, acra-server and acra-translator. --tls_crl_url=<url> URL of the Certificate Revocation List (CRL) to use.| Cossack Labs Documentation Server on Cossack Labs
Data migration # How to prepare a database to work with AcraServer. Data migration strategies in general # Any data migration strategies have two main steps: (1) migrate data schema and (2) encrypt existing data. Schema migration includes changing column’s types to binary (bytea/blob) for using data encryption via Acra (not required for tokenization). There are several approaches for schema migration: A. Stop application and producing data, change column’s types with ALTER TABLE, resume t...| Cossack Labs Documentation Server on Cossack Labs
enable # enable is acra-tokens subcommand used for enabling back once disabled tokens and allowing their use. Command line flags # General configuration # --accessed_after=<date> Limit action to tokens accessed after specified date. --accessed_before=<date> Limit action to tokens accessed before specified date. --created_after=<date> Limit action to tokens created after specified date. --created_before=<date> Limit action to tokens created before specified date.| Cossack Labs Documentation Server on Cossack Labs
Getting started # Availability # Themis supports following CPU architectures: x86_64/i386, ARM, various Android architectures. We build and verify Themis on the latest stable OS versions: Debian (9, 10), CentOS (7, 8), Ubuntu (16.04, 18.04, 20.04) macOS (10.12–10.15, 11.*) Android (7–12) iOS (11–15) Windows (experimenal MSYS2 support) We plan to expand this list with a broader set of platforms. If you’d like to help improve or bring Themis to your favourite platform or language — ge...| Cossack Labs Documentation Server on Cossack Labs
Example projects with GoThemis # Once you have installed GoThemis, it’s time to give it some action! Code samples # Some code samples for Themis features are available at docs/examples/go on GitHub: key generation utilities data encryption using Secure Cell message encryption using Secure Message a simple chat server and client using Secure Session password authentication using Secure Comparator You can also take a look at unit tests in GoThemis source code.| Cossack Labs Documentation Server on Cossack Labs
Hermes-core server # Hermes-core might be also described as a wrapper around a database where the exact database type used does not matter. We’ve designed Hermes-core to be used in a fashion where different stores (Credential store, Data store, and Keystore) can be local, remote, unified, or have intentionally different architectures. They are passed to Hermes-core as parameters, and if the implementation fits the interface, anything can be used for storing Hermes-core’s data, including w...| Cossack Labs Documentation Server on Cossack Labs
Installing JavaThemis for desktop development # JavaThemis is available in the Maven Central repository. Additionally, Themis JNI library has to be installed in your system as well. Themis JNI library is available as a system package for Linux and macOS. Usually you want to install the stable package to benefit from automatic dependency management and security updates. However, you can also build and install the latest version of JNI library from the source code as well.| Cossack Labs Documentation Server on Cossack Labs
Installing JavaThemis for desktop development # JavaThemis is available in the Maven Central repository. Additionally, Themis JNI library has to be installed in your system as well. Themis JNI library is available as a system package for Linux and macOS. Usually you want to install the stable package to benefit from automatic dependency management and security updates. However, you can also build and install the latest version of JNI library from the source code as well.| Cossack Labs Documentation Server on Cossack Labs
Key management # Note: We strongly advise that you read this section first, before proceeding to any of our language-specific how-tos. It will help you to avoid some typical mistakes. In the current version of Themis, key management is left to the discretion of the end-user. However, we’ve got some helpful tips for those willing to develop in a truly secure way. According to the Kerckhoffs’s principle, cryptosystems should be treated as secure as the keys.| Cossack Labs Documentation Server on Cossack Labs
Key storage # Key storage’s functionality # Acra needs a place for storing intermediate keys (intermediate keys used for all the encryption, masking, tokenization, crypto-signed audit logging and so on). All these keys are encrypted with the Acra Master Key, so it’s OK to store them in some storage available for many hosts. Managing keys becomes harder as the number of them increases, that’s why you may want to find the best key storage for your purposes.| Cossack Labs Documentation Server on Cossack Labs
Example projects with JsThemis # Once you have installed JsThemis, it’s time to give it some action! Code samples # Some code samples for Themis features are available at docs/examples/js on GitHub: key generation utilities data encryption using Secure Cell message encryption using Secure Message a simple chat server and client using Secure Session password authentication using Secure Comparator You can also take a look at unit tests in JsThemis source code.| Cossack Labs Documentation Server on Cossack Labs
Example projects with PHPThemis # Once you have installed PHPThemis, it’s time to give it some action! Code samples # Some code samples for Themis features are available at docs/examples/php on GitHub: data encryption using Secure Cell message encryption using Secure Message a simple chat server and client using Secure Session You can also take a look at unit tests in PHPThemis source code. Debugging aids # There are command-line utilities that you can run from GitHub source code at tools/php.| Cossack Labs Documentation Server on Cossack Labs
Acra, PKI / CA and secure deployment # We strongly recommend following the best security practices while deployment and using the public key infrastructure (PKI) to provide transport data encryption and authentication between Acra’s components. This page contains some useful information about the PKI and links to related resources. The central component of any PKI is the Certificate Authority (CA). The CA acts as an arbitrator or a third party, whilst the trust relations are established bet...| Cossack Labs Documentation Server on Cossack Labs
Example projects with PyThemis # Once you have installed PyThemis, it’s time to give it some action! Code samples # Some code samples for Themis features are available at docs/examples/python on GitHub: key generation utilities data encryption using Secure Cell message encryption using Secure Message a simple chat server and client using Secure Session password authentication using Secure Comparator You can also take a look at unit tests in PyThemis source code.| Cossack Labs Documentation Server on Cossack Labs
read # read is acra-keys subcommand used for reading keys from keystore in a plaintext. Command line flags # General flags # --private 🔴 Read private key of the keypair. --public 🔴 Read public key of the keypair. TLS (available since 0.96.0) # --tls_auth= Set authentication mode that will be used for TLS connection. 0 — do not request client certificate, ignore it if received; 1 — request client certificate, but don’t require it; 2 — expect to receive at least one certificate to...| docs.cossacklabs.com
AcraTranslator, an API service # AcraTranslator is an API server, that exposes most of Acra’s features as HTTP or gRPC API with client SDKs and traffic protection. This element of Acra is necessary in the use-cases when applications store the encrypted data as separate blobs (files that are not in a database - i.e. in the S3 bucket, local file storage, etc.). By its nature, AcraTranslator is a separate daemon that runs in an isolated environment (separate virtual machine or physical server).| docs.cossacklabs.com
AcraServer, an SQL database proxy # How AcraServer works # AcraServer is also known as SQL Proxy. It’s an SQL database proxy that exposes Acra’s functionality by parsing SQL traffic between an app and a database and applying security functions where appropriate. If you’d like to encrypt the data between your app and SQL database “transparently on-a-fly” then AcraServer should be your main choice. AcraServer sits between your application and MySQL/PostgreSQL database and does the fol...| docs.cossacklabs.com