Struct argonautica::Hasher

pub struct Hasher<'a> { /* fields omitted */ }

One of the two main structs. Use it to turn passwords into hashes

Methods

impl<'a> Hasher<'a>

pub fn new() -> Hasher<'static>

Creates a new Hasher with a sensible default configuration for the average machine (e.g. an early-2014 MacBook Air).

Note: If you are using this library to hash user passwords for storage in a database, it is recommended that you adjust these settings for your machine (primarily iterations, and memory_size) until the time it takes to hash a password is approximately 300-500 milliseconds.

There is a script in the examples directory that will show you the various configuration options for your machine that produce hashing times between 300 and 500 milliseconds (Don't forget to run it with the --release and --features="simd" flags). Alternatively, you can clone the repository and run the benchmark suite with cargo bench --features="benches simd" -- inputs, which will take longer but which runs many iterations for each configuration scenario; so it provides information about distributions of running time (e.g. mean, 95% confidence intervals, etc.) as opposed to just point estimates.

Here are the default configuration options:

• backend: Backend::C
• cpu_pool: A CpuPool ...
  • with threads equal to the number of logical cores on your machine
  • that is lazily created, i.e. created only if / when you call the methods that need it (hash_non_blocking or hash_raw_non_blocking)
• hash_len: 32 bytes
• iterations: 192
• lanes: The number of logical cores on your machine
• memory_size: 4096 kibibytes
• opt_out_of_secret_key: false
• password_clearing: false
• salt: random Salt of length 32 bytes that renews with every hash
• secret_key_clearing: false
• threads: The number of logical cores on your machine
• variant: Variant::Argon2id
• version: Version::_0x13

pub fn fast_but_insecure() -> Hasher<'a>

Creates a new Hasher that is fast but highly insecure. If for some reason you'd like to use Argon2 for hashing where security is not an issue, you can use this configuration. It sets hash length to 32 bytes (256 bits), uses only 1 iteration, sets memory size to the minimum of 8 * the number of lanes, uses a deterministic salt of the minimum length of 8 bytes, and opts out of a secret key. All other configuration options are the same as the defaults. On the developer's early-2014 Macbook Air, this configuration hashes the full text of Shakespear's Hamlet in approximately 1 millisecond (on average). MD5 does it in about half the time and sha2 with the SHA-256 algorithm performs about the same as argonautica

pub fn configure_backend(&mut self, backend: Backend) -> &mut Hasher<'a>

Allows you to configure Hasher with a custom backend. The default backend is Backend::C, which is currently the only backend supported. A Rust backend is planned, but is not currently available. If you configure a Hasher with Backend::Rust it will error when you call hash, hash_raw or their non-blocking equivalents

pub fn configure_cpu_pool(&mut self, cpu_pool: CpuPool) -> &mut Hasher<'a>

Allows you to configure Hasher with a custom CpuPool. The default Hasher does not have a cpu pool, which is only needed for the hash_non_blocking and hash_raw_non_blocking methods. If you call either of these methods without a cpu pool, a default cpu pool will be created for you on the fly; so even if you never configure Hasher with this method you can still use the non-blocking hashing methods. The default cpu pool has as many threads as the number of logical cores on your machine

pub fn configure_hash_len(&mut self, hash_len: u32) -> &mut Hasher<'a>

Allows you to configure Hasher to use a custom hash length (in number of bytes). The default is 32.

See configuration example for a more detailed discussion of this parameter

pub fn configure_iterations(&mut self, iterations: u32) -> &mut Hasher<'a>

Allows you to configure Hasher to use a custom number of iterations. The default is 192.

See configuration example for a more details on this parameter

pub fn configure_lanes(&mut self, lanes: u32) -> &mut Hasher<'a>

Allows you to configure Hasher to use a custom number of lanes. The default is the number of physical cores on your machine.

See configuration example for a more details on this parameter

pub fn configure_memory_size(&mut self, memory_size: u32) -> &mut Hasher<'a>

Allows you to configure Hasher to use a custom memory size (in kibibytes). The default is 4096.

See configuration example for a more details on this parameter

pub fn configure_password_clearing(&mut self, boolean: bool) -> &mut Hasher<'a>

Allows you to configure Hasher to erase the password bytes after each call to hash, hash_raw, or their non-blocking equivalents. The default is to not clear out the password bytes (i.e. false). If you set this option to true, you must provide Hasher with a mutable password, e.g. a password constructed from a String, Vec<u8>, &mut str, &mut [u8], etc. as opposed to one constructed from a &str, &[u8], etc., or else hashing will return an Error.

See configuration example for a more details on this parameter

pub fn configure_secret_key_clearing(     &mut self,     boolean: bool ) -> &mut Hasher<'a>

Allows you to configure Hasher to erase the secret key bytes after each call to hash, hash_raw, or their non-blocking equivalents. The default is to not clear out the secret key bytes (i.e. false). If you set this option to true, you must provide Hasher with a mutable secret key, e.g. a secret key constructed from a String, Vec<u8>, &mut str, &mut [u8], etc. as opposed to one constructed from a &str, &[u8], etc., or else hashing will return an Error.

See configuration example for a more details on this parameter

pub fn configure_threads(&mut self, threads: u32) -> &mut Hasher<'a>

Allows you to configure Hasher to use a custom number of threads. The default is the number of physical cores on your machine. If you choose a number of threads that is greater than the lanes configuration, Hasher will use the minimum of the two.

See configuration example for a more details on this parameter

pub fn configure_variant(&mut self, variant: Variant) -> &mut Hasher<'a>

Allows you to configure Hasher to use a custom Argon2 variant. The default is Variant::Argon2id. Do not use a different variant unless you have a specific reason to do so.

See configuration example for a more details on this parameter

pub fn configure_version(&mut self, version: Version) -> &mut Hasher<'a>

Allows you to configure Hasher to use a custom Argon2 version. The default and latest (as of 5/18) is Version::_0x13. Do not use a different version unless you have a specific reason to do so.

See configuration example for a more details on this parameter

pub fn hash(&mut self) -> Result<String, Error>

The primary method (blocking version).

After you have configured a Hasher to your liking and provided it will all the data you would like to hash, e.g.

• a Password,
• a Salt (note: it is recommened you use the default random salt),
• a SecretKey,
• AdditionalData (optional),

call this method in order to produce a string-encoded hash, which is safe to store in a database and against which you can verify passwords later

pub fn hash_non_blocking(     &mut self ) -> impl Future<Item = String, Error = Error>

The primary method (non-blocking version).

Same as hash except it returns a Future instead of a Result

pub fn hash_raw(&mut self) -> Result<HashRaw, Error>

Like the hash method, but instead of producing an string-encoded hash, it produces a HashRaw struct that contains all the components of the string-encoded version, including the raw hash bytes and the raw salt bytes. In general, you should prefer to use the hash method instead of this method

pub fn hash_raw_non_blocking(     &mut self ) -> impl Future<Item = HashRaw, Error = Error>

Same as hash_raw except it returns a Future instead of a Result

pub fn opt_out_of_secret_key(&mut self, boolean: bool) -> &mut Hasher<'a>

As an extra security measure, if you want to hash without a secret key, which is not recommended, you must explicitly declare that this is your intention by calling this method and setting the opt_out_of_secret_key configuration to true (by default, it is set to false); otherwise hashing will return an error when you fail to provide a secret key

pub fn to_owned(&self) -> Hasher<'static>

Clones the Hasher, returning a new Hasher with a static lifetime. Use this method if you would like to move a Hasher to another thread

pub fn with_additional_data<AD>(     &mut self,     additional_data: AD ) -> &mut Hasher<'a> where     AD: Into<AdditionalData>,

Allows you to add some additional data to the Hasher that will be hashed alongside the Password and other pieces of data you would like to hash (i.e. the Salt and an optional SecretKey).

Including additional data in your hash is not very common; so it is unlikely you will need to use this method. If, however, you do add additional data, note that it is like a secret key in that it will be required later in order to verify passwords, and it is not stored in the string-encoded version of the hash, meaning you will have to provide it manually to a Verifier

pub fn with_password<P>(&mut self, password: P) -> &mut Hasher<'a> where     P: Into<Password<'a>>,

Allows you to provide a Hasher with the password you would like to hash. Hashing requires a password; so you must call this method before calling hash, hash_raw, or their non-blocking version

pub fn with_salt<S>(&mut self, salt: S) -> &mut Hasher<'a> where     S: Into<Salt>,

Allows you to provide Hasher with a custom Salt to include in the hash. The default Hasher is configured to use a random Salt of 32 bytes; so there is no need to call this method. If you would like to use a random Salt of different length, you can call this method with Salt::random(your_custom_length_in_bytes). Using a deterministic Salt is possible, but discouraged

pub fn with_secret_key<SK>(&mut self, secret_key: SK) -> &mut Hasher<'a> where     SK: Into<SecretKey<'a>>,

Allows you to provide Hasher with a secret key that will be used to create the hash. The secret key will not be included in the hash output, meaning you must save it somewhere (ideally outside your code) to use later, as the only way to verify passwords against the hash later is to know the secret key. This library encourages the use of a secret key

pub fn additional_data(&self) -> Option<&AdditionalData>

Read-only access to the Hasher's AdditionalData, if any

pub fn config(&self) -> &HasherConfig

Read-only access to the Hasher's HasherConfig

pub fn password(&self) -> Option<&Password<'a>>

Read-only access to the Hasher's Password, if any

pub fn salt(&self) -> &Salt

Read-only access to the Hasher's Salt

pub fn secret_key(&self) -> Option<&SecretKey<'a>>

Read-only access to the Hasher's SecretKey, if any

Trait Implementations

impl<'a> Default for Hasher<'a>

fn default() -> Hasher<'static>

Same as the new method

impl<'a> Debug for Hasher<'a>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.