Crate dryoc

source ·
Expand description

dryoc: Don’t Roll Your Own Crypto™1

dryoc is a pure-Rust, general-purpose cryptography library. It’s also an implementation of libsodium, and designed to be 100% compatible with, and interchangeable with, libsodium’s API.

Doing cryptography properly is hard. While no human is infallible, computers are pretty good at following instructions. Humans are bad at following instructions, but they do a decent job of giving instructions, provided they can effectively communicate intent. Thus, if the instructions humans give the computer are correct, we can be reasonably assured that the operations the computer does are correct too.

This library tries to make it easy to give the computer the correct instructions, and it does so by providing well-known implementations of general-purpose cryptography functions, in an API that’s relatively easy to use, type safe, and hard to use incorrectly.

As the name of this library implies, one should avoid trying to “roll their own crypto”, as it often results in avoidable mistakes. In the context of cryptography, mistakes can be very costly.

The minimum supported Rust version (MSRV) for this crate is Rust 1.51 or newer.

Features

  • 100% pure Rust, no hidden C libraries
  • mostly free of unsafe code2
  • Hard to misuse, helping you avoid common costly cryptography mistakes
  • Many libsodium features implemented with both Classic and Rustaceous API
  • Protected memory handling (mprotect() + mlock(), along with Windows equivalents)
  • Serde support (with features = ["serde"])
  • Portable SIMD implementation for Blake2b (used by generic hashing, password hashing, and key derivation) on nightly, with features = ["simd_backend", "nightly"]
  • SIMD backend for Curve25519 (used by public/private key functions) on nightly with features = ["simd_backend", "nightly"]
  • SHA2 (used by sealed boxes) includes SIMD implementation for AVX2
  • ChaCha20 (used by streaming interface) includes SIMD implementations for Neon, AVX2, and SSE2

To enable all the SIMD backends through 3rd party crates, you’ll need to also set RUSTFLAGS:

  • For AVX2 set RUSTFLAGS=-Ctarget-cpu=haswell -Ctarget-feature=+avx2
  • For SSE2 set RUSTFLAGS=-Ctarget-feature=+sse2
  • For Neon set RUSTFLAGS=-Ctarget-feature=+neon

Note that eventually this project will converge on portable SIMD implementations for all the core algos which will work across all platforms supported by LLVM, rather than relying on hand-coded assembly or intrinsics, but his is a work in progress.

APIs

This library includes both a Classic API, which is very similar to the original libsodium API, and Rustaceous API with Rust-specific features. Both APIs can be used together interchangeably, according to your preferences. The Rustaceous API is a wrapper around the underlying classic API.

It’s recommended that you use the Rustaceous API unless you have strong feelings about using the Classic API. The Classic API includes some pitfalls and traps that are also present in the original libsodium API, and unless you’re extra careful you could make mistakes. With the Rustaceous API, it’s harder to make mistakes thanks to strict type and safety features.

The Rustaceous API is, arguably, somewhat trickier to use, especially if you’re new to Rust. The Rustaceous API requires knowing and specifying the desired type in many cases. For your convenience, type aliases are provided for common types within each module. The Classic API only uses base types (fixed length byte arrays and byte slices).

FeatureRustaceous APIClassic APILibsodium Docs
Public-key authenticated boxesDryocBoxcrypto_boxLink
Secret-key authenticated boxesDryocSecretBoxcrypto_secretboxLink
Streaming encryptionDryocStreamcrypto_secretstream_xchacha20poly1305Link
Generic hashing, HMACGenericHashcrypto_generichashLink
Secret-key authenticationAuthcrypto_authLink
One-time authenticationOnetimeAuthcrypto_onetimeauthLink
Key derivationKdfcrypto_kdfLink
Key exchangeSessioncrypto_kxLink
Public-key signaturesSigningKeyPaircrypto_signLink
Password hashingPwHashcrypto_pwhashLink
Protected memory3protectedN/ALink
Short-input hashingN/Acrypto_shorthashLink

Using Serde

This crate includes optional Serde support which can be enabled with the serde feature flag. When enabled, the Serialize and Deserialize traits are provided for data structures.

Security notes

This crate has not been audited by any 3rd parties. It uses well-known implementations of the underlying algorithms which have been previously verified as using constant-time operations.

With that out of the way, the deterministic nature of cryptography and extensive testing used in this crate means it’s relatively safe to use, provided the underlying algorithms remain safe. Arguably, this crate is incredibly safe (as far as cryptography libraries go) thanks to the features provided by the API of this crate, and those provided by the Rust language itself.

Acknowledgements

Big ups to the authors and contributors of NaCl and libsodium for paving the way toward better cryptography libraries.

  1. Not actually trademarked. ↩

  2. The protected memory features described in the protected mod require custom memory allocation, system calls, and pointer arithmetic, which are unsafe in Rust. Some of the 3rd party libraries used by this crate, such as those with SIMD, may contain unsafe code. In particular, most SIMD implementations are considered “unsafe” due to their use of assembly or intrinsics, however without SIMD-based cryptography you may be exposed to timing attacks. ↩

  3. Currently only available on nightly Rust, with the nightly feature flag enabled. ↩

  4. The Rustaceous API is designed to protect users of this library from making mistakes, however the Classic API allows one to do as one pleases. ↩

Modules

Enums

  • Error
    Errors generated by Dryoc.