/crypto.rs

The canonical source of cryptographic ground-truth for IOTA projects that use Rust.

Primary LanguageRust

crypto.rs

tests coverage dependency status

A boundary crate of selected implementations of crypto primitives that are considered to be safe to use within the IOTA Foundation.

To be included in this list an implementation must:

  • expose a minimal interface using the simplest possible types with high semantic density
  • be explicit what algorithm they perform (e.g. PBKDF_HMAC_SHA512)
  • use explicit memory allocation whenever possible and prefer no_std
  • be proven by: mathematical proofs, audits, reviews by security experts, mass adoption
  • be tested using independently generated test vectors from well-established reference implementations as well as available test vectors in relevant specifications

List of Algorithms

Type Name Feature Spec/RFC Rust Source Test Source Rating*
ciphers AES-256-GCM aes spec aes-gcm nist ★★★☆☆
ciphers AES-KW aes-kw spec aes-crate nist ★★★☆☆
ciphers XCHACHA20-POLY1305 chacha rfc chacha20poly1305 official ★★★★★
hashes BLAKE2b-256 blake2b rfc blake2 official ★★★★☆
hashes CURL-P curl-p rfc bee-ternary official ★★☆☆☆
hashes SHA2-256 sha spec sha2 nist ★★★★★
hashes SHA2-384 sha spec sha2 nist ★★★★★
hashes SHA2-512 sha spec sha2 nist ★★★★★
keys X25519 x25519 RFC7748 x25519-dalek official ★★★★★
keys PBKDF2-HMAC-SHA256 pbkdf rfc pbkdf2 self ★★★★☆
keys PBKDF2-HMAC-SHA384 pbkdf rfc pbkdf2 self ★★★★☆
keys PBKDF2-HMAC-SHA512 pbkdf rfc pbkdf2 self ★★★★☆
keys BIP-39 bip39 rfc crypto.rs multilang ★★☆☆☆
keys SLIP-10 slip10 rfc crypto.rs self ★★☆☆☆
macs HMAC-SHA2-256 hmac rfc hmac official ★★★★☆
macs HMAC-SHA2-384 hmac rfc hmac official ★★★★☆
macs HMAC-SHA2-512 hmac rfc hmac official ★★★★☆
signatures Ed25519 ed25519 rfc (draft) ed25519-zebra extended ★★★★☆
utility RANDOM random getrandom math ★★★★★

* We have chosen a fully arbitrary rating for each algorithm based on how we generally feel about them.

Usage

Cargo.toml


[dependencies.iota-crypto]
git = "https://github.com/iotaledger/crypto.rs"
# be sure to grab the latest github commit revision hash!!!
rev = "09ff1a94d6a87838589ccf1b874cfa3283a00f26"
features = [ "random", "ed25519", "sha", "hmac", "bip39-en" ]
version = "*"

[features]
default = [ "crypto" ]
crypto = [ "iota-crypto" ]

src/main.rs

use crypto::{
    ciphers::{aes, aes-kw}
    hashes::{blake2b, curl-p, sha}
    keys::{bip39, pbkdf, slip10, x25519}
    macs::hmac
    signatures::ed25519
    utils::random
}

Reference

cargo doc --workspace --no-deps --open

WARNING

This library has not yet been audited for security, so use at your own peril. Until a formal third-party security audit has taken place, the IOTA Foundation makes no guarantees to the fitness of this library for any purposes.

As such they are to be seen as experimental and not ready for real-world applications.

Nevertheless, we are very interested in feedback about the design and implementation, and encourage you to reach out with any concerns or suggestions you may have.

Reviewers

Review the implementation and API seperately. Verify the dependency tree with different feature flags.

Contributors

  • Focusing on providing a variety of test vectors outweighs any concerns regarding the chosen initial implementation (such as performance).
  • Review the imported code

Community Testing of Hardware / OS

  • todo Matrix of tested hardware tbd.

Discussions

If you have questions about how to use this library, or why certain decisions were made, please create a new discussion.

Tests

cargo test --lib --all-features

Doctest

We aim to supply at least one docstest for every interface, so to see real world usage consult the rustdocs.

Bindings

Generally speaking, consuming libraries of this crate are responsible for providing their own bindings and may, if they chose, decide to expose this crates functionality.

License

Apache 2.0