Orion is a cryptography library written in pure Rust

It aims to provide easy and usable crypto while trying to minimize the use of unsafe code

orion

About

. . You can read more about Orion in the wiki.

Currently supports:

  • AEAD: (X)ChaCha20Poly1305.
  • Stream ciphers: (X)ChaCha20.
  • KDF: HKDF, PBKDF2, Argon2i.
  • MAC: HMAC, Poly1305.
  • Hashing: BLAKE2b, SHA2.

Security

This library has not undergone any third-party security audit. Usage is at own risk.

See the SECURITY.md regarding recommendations on correct use, reporting security issues and more. Additional information about security regarding Orion is available in the wiki.

Minimum Supported Rust Version

Rust 1.51 or later is supported however, the majority of testing happens with latest stable Rust.

MSRV may be changed at any point and will not be considered a SemVer breaking change.

Crate Features

By default Orion targets stable Rust with std. To use Orion in a no_std context, you need to specify the dependency as such:

orion = { version = "*", default-features = false }
# Replace * with the most recent version

When Orion is used in a no_std context, the high-level API is not available, since it relies on access to the systems random number generator.

Argon2i is not available with no_std by default, but can be by enabling the alloc feature:

[dependencies.orion]
version = "*" # Replace * with the most recent version
default-features = false
features = ["alloc"]

Documentation

Can be viewed here or built with:

cargo doc --no-deps

Tests and Fuzzing

The wiki has details on how orion is tested. To run all tests:

cargo test

Fuzzing is done using honggfuzz-rs in orion-fuzz. See orion-fuzz on how to start fuzzing orion.

Constant-time execution tests can be found at orion-dudect and orion-sidefuzz.

Benchmarks

An overview of the performance that can be expected from Orion can be seen here.

The library can be benchmarked with Criterion as below. All benchmarking tests are located in benches/.

cargo bench

Changelog

Please refer to the CHANGELOG.md list.

Contributing

Please refer to the guidelines in CONTRIBUTING.md for information on how to contribute to Orion.

License

Orion is licensed under the MIT license. See the LICENSE file for more information.

Issues

Collection of the latest Issues

brycx

brycx

good first issue
0

The Hasher enum for BLAKE2b does not derive any of the common traits found elsewhere for public items. It should at the very least implement Debug and probably also PartialEq.

brycx

brycx

help wanted
0

Portable SIMD has landed in nightly Rust core::simd[1]. We should investigate if using SIMD in Orion is a viable option. For example, ChaCha20 can be vectorized[2], which could provide quite substantial performance benefits.

What needs to be figured out:

  • What is, if there is any, the timeline for stabilization of core::simd and potentially std::simd (?)
  • Will the portable SIMD API require use of unsafe code if utilized within Orion?
  • What other primitives could benefit from vectorization? BLAKE2 is a candidate as well IIRC
  • If simd would require std for some unknown reason, do we want to consider providing vectorized implementations for safe-api only?
  • Will the portable SIMD offered by Rust be portable enough in the sense that we'd be able to remove the current portable non-vectorized implementations?
  • Would the portable SIMD be usable on all platforms we test on currently, including the non-std targets? What would the impact on WASM support be here?

[1]: Most of the work seems to happen over here https://github.com/rust-lang/portable-simd [2]: https://eprint.iacr.org/2013/759.pdf

brycx

brycx

breaking change
1

Since the introduction of serde support, most newtypes implement TryFrom<&[u8]> which simply delegates to from_slice(). This seems a bit redundant, especially if/when moving to Rust 2021 Edition, where TryFrom/TryInto are part of prelude. We could consider removing from_slice in the future and simply provide TryFrom only instead.

brycx

brycx

help wanted
0

Some time back I asked Guido Vranken, the author of cryptofuzz, whether a module for Orion could be added, which was no problem.

I started some minimal work, but unfortunately was thrown out of it. It would still be great to have Orion fuzzed against other crypto libs in OSSFuzz through cryptofuzz. AFAIK, there now exists more Rust-based modules than back then (ring, librustsecpk256, RustCrypto) which can be valuable to refer to if working on a module for Orion.

This most likely requires a substantial amount of work, familiarity with C++, Rust FFI and should probably be its own repository in this GH organization.

brycx

brycx

bug
2

The following changes in performance of ChaCha20 and related functions have been observed:

rustc 1.41.0 (5e1a79984 2020-01-27), orion 0.15.0:

  • ChaCha20Poly1305: Input 128KiB, Throughput 419.22 MiB/s
  • XChaCha20Poly1305: Input 128KiB, Throughput 419.53 MiB/s

rustc 1.56.0 (09c42c458 2021-10-18), orion 0.16.1:

  • ChaCha20Poly1305: Input 128KiB, Throughput 275.66 MiB/s
  • XChaCha20Poly1305: Input 128KiB, Throughput 275.19 MiB/s

The change in performance was only observed on an Intel(R) Core(TM) i7-4790K CPU machine. No regression was found on the Raspberry Pi 2 Model B V1.1 used to benchmark. When running cargo bench with orion v0.15.0 and rustc 1.56.0 (09c42c458 2021-10-18), the same regressions are shown.

It doesn't seem like any major changes were introduced in the ChaCha20 implementation between these versions, when inspecting git log. This, and that regression persists between different versions of Orion, tells us its most likely due to changes outside of this crate.

Further things to investigate:

  • If the regression persists between rustc versions 1.41.0 to 1.56.0 (regression due to changes in rustc, maybe LLVM upgrades?)
  • If any changes in dependencies, could have caused this
brycx

brycx

breaking change
1

Rust 2021 Edition has been released and we should probably switch to this. Will bump MSRV to 1.56.0 and should be considered a breaking change.

brycx

brycx

new feature
0

I was recently asked whether Orion had plans to support Argon2id. We've never been opposed to this variant in general, but the last time this was investigated was when Argon2i was being implemented.

At that time, there seemed to be no easy way to support the parallelism of Argon2d, without either implementing the threading-logic ourselves or pulling in dependencies with a lot of unsafe code.

I think it would be worthwhile to re-investigate this, to see if anything has changed in terms of how parallelism could be supported.

vlmutolo

vlmutolo

new feature
12

Summary

The Rust ecosystem heavily integrates with std's Read and Write traits. It would be helpful to interoperate with these traits, especially in the context of the aead and hash modules.

Example

Hashing

AEAD

I'm definitely open to suggestions on the API described here. Particularly, I'm not sure if we'd want convenience wrappers around the *_copy functions for the AEAD case. The copy functions are fairly general, and will allow for people to allocate buffers how they want. But there's probably a case to be made to provide a simpler type that just outputs a Vec of encrypted/decrypted data.


In any case, the real advantage of implementing these APIs is that someone could do, for example, the following:

And it would work as expected. The big deal here is that large files should be read and hashed in pieces, which currently requires reaching into the hazardous module and using the "streaming interface" (the update method). This looks something like the following.

So it's longer, has a little more room for user error, and in general we probably just want to support the existing IO traits.

I already started the implementation, and I'll post a draft PR soon.

Also, I considered making AsyncRead and AsyncWrite part of this issue/PR, but that seems like it should be its own thing. There's talk about integrating those traits into the standard library some time soon, so maybe we should hold off until then.

brycx

brycx

new feature
0

We'd like orion to support this by utilizing https://github.com/mit-plv/fiat-crypto. fiat-crypto is able to generate formally verified code which, in other words, means the field arithmetic from fiat-crypto has had its correctness proven by the Coq theorem prover.

Using fiat-crypto means:

  • Greater confidence in the implementations offered by orion
  • Less work required to maintain the implementations
  • Less work required to audit the implementations

(the same motivation for #198)

Based on popularity and usage in for example TLS 1.3, the curve that will be supported is Curve25519. Additionally, this will also mean X25519 in terms of ECDH and Ed25519 in terms of EdDSA. Both these are also used in TLS 1.3. Using X25519 also allows us to build a higher-level key-exchange API that is compatible with libsodium's.

Initial work for X25519 and integration of fiat's Curve25519 arithmetic has been started in #197.

This will serve more as a tracking issue, since this will require a substantial amount of work.

TODO:

  • Finish X25519 implementation in #197
  • Implement Ed25519
  • Add fuzzing targets for both (hazardous + high-level) in https://github.com/orion-rs/orion-fuzz
  • X25519 and Ed25519 additions in the wiki, README (security section needs updates perhaps), crate meta-data, etc
  • High-level key-exchange API
  • High-level digital signatures API
  • Extensive documentation for hazardous and high-level additions
  • We could also add orion in the fiat-crypto usage tracker https://github.com/mit-plv/fiat-crypto/issues/902 once implementations exist
brycx

brycx

dependencies
4

See issues regarding the dalek-cryptography organization:

I'm not sure I'm comfortable continuing to rely on the subtle crate. The above seem to be somewhat opposing statements of what has happened, though I still feel weird about the removal of crate owners, even if "warranted" by the maintainer of the org. IMHO, the thing should have happened with more transparency to begin with (like they should've made an announcement).

Currently, I'm leaning towards switching to subtle-ng.

brycx

brycx

testing
0

To check that all newtypes (SecretKeys, Poly1305, etc.) implement the correct traits, new testing functions are needed.

For example fn test_traits_secret_key<Secret: Debug + Drop + PartialEq>() {} could be used to check that a secret key implements the needed traits in a test like so:

brycx

brycx

security
10

Before a stable version of orion is released, an audit should be done. Preferably of the whole library, though it may end up only being partly. This depends on the financial means available.

Edit: I currently have no idea about when I would be able to afford this.

Versions

Find the latest versions by id

0.17.1 - Jan 30, 2022

Changelog:

See CHANGELOG.md.

0.17.0 - Nov 24, 2021

Changelog:

See CHANGELOG.md.

0.16.1 - Nov 03, 2021

Changelog:

See CHANGELOG.md.

0.16.0 - Mar 28, 2021

Changelog:

See CHANGELOG.md.

0.15.6 - Feb 09, 2021

Changelog:

See CHANGELOG.md.

0.15.5 - Oct 13, 2020

Changelog:

See CHANGELOG.md.

0.15.4 - Sep 25, 2020

Changelog:

See CHANGELOG.md.

0.15.3 - Aug 08, 2020

Changelog:

See CHANGELOG.md.

0.15.2 - Jun 07, 2020

Changelog:

See CHANGELOG.md.

0.15.1 - Mar 09, 2020

Changelog:

See CHANGELOG.md.

0.15.0 - Feb 25, 2020

Changelog:

See CHANGELOG.md.

0.14.5 - Jan 25, 2020

Changelog:

  • Fix nightly build breakage

0.14.4 - Aug 21, 2019

Changelog:

  • Reduce the amount of allocations throughout most of orion.
  • Vectorize the ChaCha20 implementation providing ~6% performance improvement for (X)ChaCha20Poly1305 and ~11.5% for (X)ChaCha20.
  • Documentation improvements.

0.14.3 - Jul 31, 2019

Changelog:

  • Improved performance for ChaCha20Poly1305/XChaCha20Poly1305 when AAD is empty.
  • Refactoring of streaming contexts used by SHA512, BLAKE2b and Poly1305.
  • Implement PartialEq<&[u8]> for all newtypes and provide documentation for usage of such (by @vlmutolo).
  • Switched to stable rustfmt.
  • Fix use of now deprecated (since v0.1.7) getrandom errors.
  • Updated fuzzing targets in orion-fuzz.

0.14.2 - Jun 10, 2019

Changelog:

  • Improved performance on all implementations, most notably: ~30% in ChaCha20/XChaCha20 and ~20% in ChaCha20Poly1305/XChaCha20Poly1305.
  • Updated zeroize dependency.
  • Testing WebAssembly (wasm32-unknown-unknown) support in CI.
  • Improved documentation.

0.14.1 - May 27, 2019

Changelog:

  • Update zeroize dependency.
  • Improvements to documentation.

0.14.0 - May 04, 2019

  • [Breaking change] Function as_bytes() for public newtypes are replaced with AsRef<> trait implementations. This means all as_bytes() calls need to be replaced with as_ref().

  • [Breaking change] The SecretKey for BLAKE2b is longer padded with zeroes to the length of the blocksize. Thus, the SecretKey no longer has a get_original_length() function, but the same result will be represented by the get_length() function instead.

  • [Breaking change] All calls to as_ref() and unprotected_as_bytes() return the newtypes data with what it was initialized, regardless of padding. (With the exception of HMAC)

  • [Breaking change] All calls to get_length() return the length of the newtype with what is what initialized, regardless of padding. (With the exception of HMAC)

  • [Breaking change] All newtypes that offer generate() now panic if the RNG fails to initialize of read from its source. This also means that newtype generate() functions, that do not take in a size parameter, no longer return a Result.

  • [Breaking change] ValidationCryptoError and FinalizationCryptoError have been removed. Though this doesn't mean that there is less information available, see issue here.

  • [Breaking change] Support for cSHAKE256 has been dropped, also meaning orion no longer depends on tiny-keccak. 8% decrease in unsafe code in dependencies.

  • All fuzzing targets in fuzz that used libFuzzer have been deprecated in favor of those in orion-fuzz using honggfuzz-rs.

  • Improvements to fuzzing targets in orion-fuzz.

  • Automated testing in CI, for constant-time execution.

  • Added From<[u8; C]> trait implementations for C-length fixed-sized newtypes, so that the caller may avoid using Result when not working with slices.

  • [Breaking change] Module hazardous::constants has been removed and all types made private. Only a select number of constants have been re-exported in their respective modules. See here for more information.

  • It is now strictly advised agianst using orion in debug mode, for what is meant to be production use. Using opt-level = 0 with orion, is also advised against. See security section.

  • rand_os has been replaced with getrandom.

  • Improvements to documentation examples as they no longer use .unwrap() but ? instead.

0.13.4 - Apr 01, 2019

Changelog:

  • Fix build for latest nightly.

0.13.3 - Mar 31, 2019

Changelog:

  • Updated zeroize to 0.6.0.
  • Added a small number of tests.
  • Improvement to constant-time interfaces (#66).

0.13.2 - Mar 13, 2019

Changelog:

  • PBKDF2 and BLAKE2b now panic on lengths exceeding (2^32-1) * 64 and 2*(2^64-1), respectively.
  • ChaCha20 length constrictions are now equivalent to those of the RFC and panics on trying to process more than 2^32-1 keystream blocks.
  • Documentation improvements.
  • OpenSSL test vectors for BLAKE2b.

Note: Strictly speaking, the first two changes are breaking, but because of the unlikeliness that this has an effect on anybody, they were not marked as such.

0.13.1 - Feb 16, 2019

Changelog:

  • Documentation improvements (#60).

0.13.0 - Feb 10, 2019

Changelog:

  • [Breaking change]: orion::hazardous::hash::sha512 previously used the same Digest as BLAKE2b. This is no longer the case, making it impossible to specify a non fixed-length hash as Digest with SHA512.
  • [Breaking change]: HLEN constant renamed to SHA512_OUTSIZE and SHA2_BLOCKSIZE constant renamed to SHA512_BLOCKSIZE.
  • Added POLY1305_OUTSIZE constant.
  • Improved documentation for high-level Password, SecretKey in hazardouss hmac and blake2b, as well as Password in pbkdf2 of hazardous.
  • Added AppVeyor builds and testing for Windows MSVC with Visual Studio 2017.

0.12.6 - Feb 08, 2019

Changelog:

  • Switched to zeroize in favor of clear_on_drop, such that using orion on stable Rust no longer requires a C compiler.
  • Fuzzing with honggfuzz-rs.

0.12.5 - Feb 04, 2019

Changelog:

  • Refactored HMAC and improved performance for PBKDF2 by ~50%.
  • Removed byteorder dependency using instead the endianness conversion functions that came with Rust 1.32.

0.12.4 - Jan 30, 2019

Changelog:

  • Fixes a bug where hashing, with BLAKE2b, over 2^64-1 bytes of data would cause an overflowing addition on debug builds.

  • Fixes a bug where hashing, with SHA512, over 2^64-1 bytes of data would not result in the counter being correctly incremented.

  • Added property-based testing, using QuickCheck, to most of the library and improved testing for the library in general.

  • PartialEq is now implemented for orion::kdf::Salt and Nonce in both chacha20 and xchacha20.

  • Added get_length() for blake2b::Digest.

  • Updated fuzzing dependencies.

0.12.3 - Jan 29, 2019

Changelog:

  • Improved compilation time.
  • Bugfix #50.
  • Update byteorder and serde_json dependencies (fixes build-failures related to rand_core).

0.12.2 - Jan 26, 2019

Changelog:

  • Fix a bug that lead to panics when using out parameters, with seal()/open() in hazardous, with a length above a given point.

0.12.1 - Jan 16, 2019

Changelog:

  • Switched rand dependency out with rand_os.

0.12.0 - Dec 29, 2018

Changelog:

  • [Breaking change]: All high-level functions now return a Result.
  • [Breaking change]: Password in pbkdf2, SecretKey and hmac() of hmac and extract() of hkdf in hazardous now return a Result.
  • [Breaking change]: Limit all generate() taking a length parameter, and orion::kdf calls to a length of less than u32::max_value() as maximum.
  • [Breaking change]: orion::kdf and orion::pwhash take a new Password parameter that is heap-allocated and returns a Result.
  • Removed sha2 dependency and ring dev-dependency. sha2 has been replaced with orion's own SHA512 implementation.
  • Added support for BLAKE2b and SHA512.
  • Updated to Rust 2018 Edition.
  • Better performance for HMAC, HKDF and PBKDF2.

Thanks to @gabelanglais for valuable feedback, especially on the API design.

0.11.2 - Dec 22, 2018

Changelog:

  • Bugfix: #46.
  • Updated subtle dependency.

Information - Updated Apr 28, 2022

Stars: 403
Forks: 24
Issues: 15

Repositories & Extras

A (mostly) pure-Rust implementation of various common cryptographic algorithms

Rust-Crypto seeks to create practical, auditable, pure-Rust implementations of common cryptographic

A (mostly) pure-Rust implementation of various common cryptographic algorithms

Rustls is a modern TLS library written in Rust

ring for cryptography and rustls-pemfile crate

Rustls is a modern TLS library written in Rust

Mundane is a Rust cryptography library backed by BoringSSL that is difficult

to misuse, ergonomic, and performant (in that order)

Mundane is a Rust cryptography library backed by BoringSSL that is difficult

Rustls is a modern TLS library written in Rust

ring for cryptography and rustls-pemfile crate

Rustls is a modern TLS library written in Rust

A (mostly) pure-Rust implementation of various common cryptographic algorithms

Rust-Crypto seeks to create practical, auditable, pure-Rust implementations of common cryptographic

A (mostly) pure-Rust implementation of various common cryptographic algorithms

This repository holds a Rust port of Google's Tink cryptography library

This repository holds a Rust port of Google's RustCrypto crates – this repo focuses on making

This repository holds a Rust port of Google's Tink cryptography library

A cryptography library that is mainly implemented in Rust

I aim to implement bindings to other languages such as C/C++ and Python

A cryptography library that is mainly implemented in Rust

Libsm is an open source pure rust library of China Cryptographic Algorithm Standards

It is completed by a collaborative effort between the Cryptape Technology LLC

Libsm is an open source pure rust library of China Cryptographic Algorithm Standards

Cryptographic algorithms in pure Rust

The main interface to these crates is the RustCrypto traits

Cryptographic algorithms in pure Rust

A collection of cryptography functions written in Rust

rustup -- curl --proto '=https' --tlsv1

A collection of cryptography functions written in Rust
Facebook Instagram Twitter GitHub Dribbble
Privacy