hartl3y94 / crypto.rs

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

crypto.rs

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