argonautica-rs
Overview
argonautica is a Rust crate for hashing passwords using the cryptographically-secure Argon2 hashing algorithm.
Argon2 won the Password Hashing Competition in 2015, a several year project to identify a successor to bcrypt, scrypt, and other common cryptographically-secure hashing algorithms.
The argonautica crate was designed:
- to be easy to use,
- to have robust, beginner-friendly documentation, and
- to (as much as possible) follow the Rust API guidelines
argonautica was built with a simple use-case in mind: hashing passwords for storage in a website's database. That said, it's also "feature-complete", meaning anything you can do with the cannonical C implementation of Argon2 you can do with argonautica*.
* Indeed, argonautica has a feature that even the cannonical C implementation lacks, i.e. hashing passwords with secret keys (the C implementation implements this, but does not expose it publicly)
Hashing
Hashing passwords with argonautica is simple. Just instantiate a default
Hasher
, provide it with a password and a secret key, and then
call the hash
method.
extern crate argonautica;
use Hasher;
Verifying
Verifying passwords against a hash is equally as simple. Just instantiate a default
Verifier
, provide it with the password and the hash you would
like to compare, provide it with the secret key that was used to create the hash, and
then call the verify
method.
extern crate argonautica;
use Verifier;
Alternatives
If argonautica isn't your cup of tea, other Rust crates that will do Argon2 hashing for you include argon2rs and rust-argon2. If you're interesting in password hashing with a different algorithm, rust-bcrypt might be worth checking out.
For what it's worth, besides API differences, argonautica has three key features that other crates currently lack:
- The ability to use SIMD instructions (even on stable),
which can lead to significantly faster hashing times
- For example, on default settings, argonautica with SIMD runs over twice as fast as other crates on the developer's early-2014 Macbook, which has access to SIMD instructions through AVX2
- Note: SIMD instructions are specific to your CPU; so if you're compiling for machines other than your own, you should not turn on the SIMD feature
- The ability to hash passwords with a secret key, which not even the C implementation exposes publicly
- The newest Argon2 variant: Argon2id
Configuration
The default configurations for Hasher
and
Verifier
were chosen to be reasonably secure for the general
use-case of hashing passwords for storage in a website database, but if you want to use
argonautica for different reasons or if you just disagree with the chosen defaults,
customizing argonautica to meet your needs should hopefully be as easy and as intuitive
as using the defaults.
Here is an example that shows how to use Hasher
's custom
configuration options. It provides color on each of the options.
extern crate argonautica;
extern crate futures_cpupool;
use Hasher;
use ;
use CpuPool;
Installation
argonautica should be relatively straightforward to include in your Rust project:
- Place
extern crate argonautica;
in your code (typically in eitherlib.rs
ormain.rs
) - In the
[dependencies]
section of yourCargo.toml
, place ...- ... if you're building for your own machine ...
argonautica = { version = "0.2", features = ["simd"] }
, orargonautica = { version = "0.2", features = ["serde", "simd"] }
- ... if you're building for a different machine ...
argonautica = "0.2"
, orargonautica = { version = "0.2", features = ["serde"] }
- ... if you're building for your own machine ...
That said, argonautica uses cc and bindgen to compile the cannonical C implemenation of Argon2 into a static archive during the build process. This means you need a C compiler on your machine in order to build argonautica. More specifically, you need:
- LLVM/Clang (version 3.9 or higher)
argonautica runs on stable Rust version 1.26.0 or greater.
License
argonautica is licensed under either of:
at your option.