Crate alkali 

Safe, idiomatic Rust bindings to the Sodium cryptographic library.

Sodium is a fast, modern cryptographic library written in C. This crate intends to provide a higher-level API for making use of the cryptographic constructions Sodium provides. These constructions include simple-to-use symmetric and asymmetric authenticated encryption, signatures, hashing, password derivation, and key exchange: In short, the majority of operations required for many modern cryptographic protocols.

The intention for this library is to be a spiritual successor to sodiumoxide, which is now deprecated. Lots of design decisions here were inspired by this library, so thanks to all of its contributors!

Which API Should I Use?

The cryptographic operations in this crate are mostly split into two main modules: symmetric and asymmetric. Symmetric (sometimes called secret-key) operations use a single secret key, shared between every party to a communication. In asymmetric (public-key) operations, every party has their own secret key, used to derive a public-key which is shared with all other parties. Parties need to know each others’ public keys to communicate.

There are also hashing algorithms available in the hash module, and tools for generating unpredictable (random) data in the random module.

Alkali API	Corresponding Sodium API	Purpose
asymmetric::cipher	crypto_box	Encrypt a message for a specific party, so only you + they can decrypt it
asymmetric::kx	crypto_kx	Establish a secret key with another party over an insecure channel
asymmetric::sign	crypto_sign	Sign a message, so that anyone can verify you sent it
asymmetric::seal	crypto_box_seal	Anonymously encrypt a message for a specific party, so only they can decrypt it
hash::generic	crypto_generichash	Calculate the “fingerprint” of a file or message
hash::kdf	crypto_kdf	Derive multiple subkeys from a single high-entropy key
hash::pbkdf	crypto_pwhash	Store a user’s password to verify their identity at a later time, or derive a cryptographic key from a password
hash::short	crypto_shorthash	Calculate a hash for use in a hash table/bloom filter/etc.
symmetric::auth	crypto_auth	Produce an authentication tag for a message which can be verified by trusted parties with whom you share a secret key
symmetric::cipher	crypto_secretbox	Encrypt a message so that trusted parties, with whom you share a secret key, can decrypt it
symmetric::cipher_stream	crypto_secretstream	Encrypt a sequence of messages, or an arbitrarily-long data stream
random	randombytes	Generate unpredictable data suitable for cryptographic use

Build Options

On non-Windows platforms, by default Sodium is compiled from source as part of alkali’s build process (on Windows, pre-compiled binaries are downloaded). This build process can be customised via features and environment variables.

• Sodium is compiled from source included in the libsodium-sys-stable crate, maintained by Frank Denis, who is also the maintainer of Sodium itself. This source may be out of date compared to the latest stable release, so alternatively, the library can be built from the latest stable downloaded from download.libsodium.org by enabling the fetch-latest feature.
• Deprecated and uncommon APIs can be disabled using the minimal feature. Any APIs or algorithms which will be disabled by enabling minimal builds will be marked as such in this documentation.
• Sodium can be built with optimisations for the current platform by enabling the optimized feature.
• Position-Independent Code can be disabled for Sodium’s build by setting the SODIUM_DISABLE_PIE environment variable.

Rather than building Sodium from source, you can also link to an existing shared/static build of Sodium on your system. The use-pkg-config feature will use pkg-config to find libsodium. Alternatively, you can set the SODIUM_LIB_DIR environment variable to specify the location of libsodium on your system. Sodium will be statically linked by default, but you can set SODIUM_SHARED to dynamically link the library. Note that alkali is built assuming that it is linked against Sodium 1.0.18 stable.

Support for no_std environments can be enabled by disabling the std feature. Note that some APIs will be disabled: Those which require std support are marked as such in the documentation.

Serde support can be enabled using the use-serde feature (enabled by default).

Hardened Buffer Types

Throughout this crate, a number of types used to store secret data (keys, seeds, etc.) use a custom allocator from Sodium to manage their memory. They can be used like standard array/slice types, as they implement core::ops::Deref, AsRef, etc., so anywhere where you might be able to use a &[u8], a hardened buffer can also be used. The benefit to using these structs over just using normal arrays/vectors is that they have a number of protections implemented intended to prevent leakage of their contents via side channels.

When these hardened buffer types are dropped, their memory is securely zeroed, so that secrets cannot later be recovered from uninitialised memory. This operation is done in such a way that the compiler will not remove it during optimisation. Memory for these types is allocated at the end of a page, immediately followed by a guard page, so any buffer overflow should be immediately detected and prevented. A canary is also placed before the allocated memory region to detect potential overflows, and another guard page is placed before the canary. The entire region is “locked”, which advises the operating system not to swap it to disk if it would normally do so, and not to include the memory contents in crash reports/core dumps.

Custom hardened types can be created using the hardened_buffer macro, or the anon_buffer macro to produce an anonymous array-like buffer backed by hardened memory.

In the future, we should be able to use the Allocator API to simplify these types, but for the time being, we have to do a fair amount of manual memory management under the hood to enable them to work. Regardless, these implementation details do not require you to do anything differently yourself.

The hazmat Feature

Sodium is generally intended to be difficult to misuse, but some constructions are inherently more prone to misuse/misunderstanding than others, and more care is required to use them securely. As an example, for the crypto_onetimeauth API, using a given key to authenticate more than one message can result in an attacker recovering the key.

In alkali, these modules are feature-gated behind the hazmat feature, and will not be available unless it is enabled. This can be done from Cargo.toml, and is just intended as an extra step to confirm, “Yes, I know what I am doing is error-prone, and I have thoroughly read the accompanying documentation”:

alkali = { version = "0.1", features = ["hazmat"] }

Modules

asymmetric

Asymmetric (public-key) cryptographic operations.

curvehazmat

Low-level Elliptic Curve operations.

encodestd

Binary-to-text encoding/decoding functions.

hash

Hash algorithms.

mem

Hardened memory management utilities.

random

Random data suitable for cryptographic use.

symmetric

Symmetric (secret-key) cryptographic operations.

util

General utilities from Sodium.

Macros

anon_buffer

Create a fixed-size hardened anonymous buffer.

hardened_buffer

Creates a hardened buffer type, for storing sensitive data (keys, passwords, etc).

Enums

AlkaliError

General error type used in alkali.

Constants

SODIUM_LIBRARY_VERSION_MAJOR

SODIUM_LIBRARY_VERSION_MINOR

SODIUM_VERSION_STRING