[−][src]Struct jwtvault::prelude::ArgonHasher
One of the two main structs. Use it to turn passwords into hashes
Implementations
impl<'a> Hasher<'a>
[src]
pub fn new() -> Hasher<'static>
[src]
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
: ACpuPool
...- 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
orhash_raw_non_blocking
)
hash_len
:32
bytesiterations
:192
lanes
: The number of logical cores on your machinememory_size
:4096
kibibytesopt_out_of_secret_key
:false
password_clearing
:false
salt
: randomSalt
of length 32 bytes that renews with every hashsecret_key_clearing
:false
threads
: The number of logical cores on your machinevariant
:Variant::Argon2id
version
:Version::_0x13
pub fn fast_but_insecure() -> Hasher<'a>
[src]
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>
[src]
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>
[src]
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>
[src]
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>
[src]
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>
[src]
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>
[src]
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>
[src]
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>
[src]
&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>
[src]
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>
[src]
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>
[src]
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>
[src]
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>
[src]
The primary method (non-blocking version).
pub fn hash_raw(&mut self) -> Result<HashRaw, Error>
[src]
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>
[src]
&mut self
) -> impl Future<Item = HashRaw, Error = Error>
pub fn opt_out_of_secret_key(&mut self, boolean: bool) -> &mut Hasher<'a>
[src]
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>
[src]
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>,
[src]
&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>>,
[src]
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>,
[src]
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>>,
[src]
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>
[src]
Read-only access to the Hasher
's
AdditionalData
, if any
pub fn config(&self) -> &HasherConfig
[src]
Read-only access to the Hasher
's
HasherConfig
pub fn password(&self) -> Option<&Password<'a>>
[src]
pub fn salt(&self) -> &Salt
[src]
pub fn secret_key(&self) -> Option<&SecretKey<'a>>
[src]
Trait Implementations
impl<'a> Debug for Hasher<'a>
[src]
impl<'a> Default for Hasher<'a>
[src]
impl<'a> PasswordHasher<Hasher<'a>> for DefaultVault
[src]
fn hash_user_password<T: AsRef<str>>(
&self,
user: T,
password: T
) -> Result<String, Error>
[src]
&self,
user: T,
password: T
) -> Result<String, Error>
fn verify_user_password<T: AsRef<str>>(
&self,
user: T,
password: T,
hash: T
) -> Result<bool, Error>
[src]
&self,
user: T,
password: T,
hash: T
) -> Result<bool, Error>
impl<'a> PasswordHasher<Hasher<'a>> for ArgonPasswordHasher
[src]
fn hash_user_password<T: AsRef<str>>(
&self,
user: T,
password: T
) -> Result<String, Error>
[src]
&self,
user: T,
password: T
) -> Result<String, Error>
fn verify_user_password<T: AsRef<str>>(
&self,
user: T,
password: T,
hash: T
) -> Result<bool, Error>
[src]
&self,
user: T,
password: T,
hash: T
) -> Result<bool, Error>
impl<'a> Workflow<DefaultHasher, Hasher<'a>> for DefaultVault
[src]
fn login<'life0, 'life1, 'life2, 'async_trait>(
&'life0 mut self,
user: &'life1 str,
pass: &'life2 str,
authentication_token_expiry_in_seconds: Option<i64>,
refresh_token_expiry_in_seconds: Option<i64>
) -> Pin<Box<dyn Future<Output = Result<Token, Error>> + Send + 'async_trait>> where
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Self: 'async_trait,
[src]
&'life0 mut self,
user: &'life1 str,
pass: &'life2 str,
authentication_token_expiry_in_seconds: Option<i64>,
refresh_token_expiry_in_seconds: Option<i64>
) -> Pin<Box<dyn Future<Output = Result<Token, Error>> + Send + 'async_trait>> where
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Self: 'async_trait,
fn renew<'life0, 'life1, 'life2, 'async_trait>(
&'life0 mut self,
user: &'life1 str,
client_refresh_token: &'life2 String,
authentication_token_expiry_in_seconds: Option<i64>
) -> Pin<Box<dyn Future<Output = Result<String, Error>> + Send + 'async_trait>> where
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Self: 'async_trait,
[src]
&'life0 mut self,
user: &'life1 str,
client_refresh_token: &'life2 String,
authentication_token_expiry_in_seconds: Option<i64>
) -> Pin<Box<dyn Future<Output = Result<String, Error>> + Send + 'async_trait>> where
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Self: 'async_trait,
fn logout<'life0, 'life1, 'life2, 'async_trait>(
&'life0 mut self,
user: &'life1 str,
client_authentication_token: &'life2 String
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>> where
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Self: 'async_trait,
[src]
&'life0 mut self,
user: &'life1 str,
client_authentication_token: &'life2 String
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>> where
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Self: 'async_trait,
fn revoke<'life0, 'life1, 'async_trait>(
&'life0 mut self,
client_refresh_token: &'life1 String
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>> where
'life0: 'async_trait,
'life1: 'async_trait,
Self: 'async_trait,
[src]
&'life0 mut self,
client_refresh_token: &'life1 String
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>> where
'life0: 'async_trait,
'life1: 'async_trait,
Self: 'async_trait,
Auto Trait Implementations
impl<'a> RefUnwindSafe for Hasher<'a>
impl<'a> Send for Hasher<'a>
impl<'a> Sync for Hasher<'a>
impl<'a> Unpin for Hasher<'a>
impl<'a> !UnwindSafe for Hasher<'a>
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
V: MultiLane<T>,