Rust-Orion: orion — This library aims to provide easy and usable crypto. 'Usable' meaning exposing high-level API's that are easy to use and hard to misuse.

orion

Build Status Build status Security Audit dudect codecov dependency status Documentation Crates.io Safety Dance MSRV

About

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. You can read more about orion in the wiki.

Currently supports:

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

Security

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

More information about security regarding orion is available in the wiki.

Minimum Supported Rust Version

Rust 1.37 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.

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.

Comments

  • Security audit
    Security audit

    Aug 11, 2018

    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.

    Security 
    Reply
  • Add generated XChaCha20 test vectors
    Add generated XChaCha20 test vectors

    Nov 22, 2018

    Currently XChaCha20 (with IETF ChaCha20) is tested directly with only one RFC test vector. Other than that, it's tested implicitly through XChaCha20Poly1305.

    Like HChaCha20 is tested using test vectors generated with Monocypher, there should be generated test vectors for XChaCha20 as well. These can be generated using Monocypher, libsodium or some other well-tested cryptography library that offers XChaCha20 for that matter.

    good first issue testing 
    Reply
  • Using `Pin` with `SecretKey` and other types that hold secret data
    Using `Pin` with `SecretKey` and other types that hold secret data

    Feb 7, 2019

    Ways to use Pin for types that hold secret data need to be explored, to avoid copies being left around. The ideal scenario is implementing Pin with all types that hold secret data, without any changes to the public API's.

    Security help wanted improvement 
    Reply
  • Add tests for trait implementations on newtypes
    Add tests for trait implementations on newtypes

    Feb 25, 2020

    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.

    good first issue testing 
    Reply
  • Investigate using haybale-pitchfork to test constant-time execution
    Investigate using haybale-pitchfork to test constant-time execution

    Apr 22, 2020

    haybale-pitchfork uses symbolic execution with LLVM IR to verify constant-time execution.

    testing 
    Reply
  • Making the public API more familiar
    Making the public API more familiar

    Oct 19, 2019

    The public API for streaming structs and newtypes could be made more familiar to users that come from other Rust crypto libraries.

    In continuation of trying to make the streaming API more consistent (https://github.com/brycx/orion/pull/87) the general approach seems to be that all one-shot functions are also part of the struct (an example of this is the RustCrypto Digest trait). Maybe the current should be changed to:

    • module::one_shot_function() -> module::Ctx::one_shot_function()
    • module::verify() -> module::Ctx::verify()

    For the newtypes API, to be more consitent with types throughout Rust, we chould change:

    • get_length -> len

    Changing the newtype API seems worthwhile, but it's debatable whether changing the straming struct API will make a noticable difference in usability.

    Breaking change question usability 
    Reply
  • More explicit struct initialization
    More explicit struct initialization

    Aug 31, 2019

    Currently, for a given streaming context Ctx in module foo we have:

    let _: Ctx = foo::init();
    

    This PR changes this to be more explicit:

    let _: Ctx = foo::Ctx::init();
    
    Breaking change improvement 
    Reply
  • Logo proposal
    Logo proposal

    Aug 8, 2018

    Hi, sir. I like to help open source projects. I have an idea for you. Do you want me to design a logo?

    Reply
  • Address #90: Add must_use message to pub Results
    Address #90: Add must_use message to pub Results

    Sep 6, 2019

    • Remove redundant must_use from internal fns
    Reply
  • Add high-level secret-stream API
    Add high-level secret-stream API

    Oct 29, 2019

    Closes #103 and closes #94

    There is one link in the documentation that i can not get to work, i have marked it with a TODO.

    I'm a bit unsure if it is better to have a get_nonce method or if it is better to return Self and the Nonce in the new method.

    Tests a rather minimal for now, but i think this should be fine since its only a thin wrapper around the hazardous API

    Is it useful to expose the option to authenticate additional data? The "normal" AEAD seal function does not do it

    new feature 
    Reply
  • XChaCha20Poly1305 streaming encryption
    XChaCha20Poly1305 streaming encryption

    Sep 9, 2019

    This is the "hazardous" part of the secreat stream API proposed in #94.

    Things that are still missing are:

    • Documentation
    • More tests, especially with wrong inputs
    • An user friendly, "safe" API
    new feature 
    Reply