argon2-1.2.0: Haskell bindings to libargon2 - the reference implementation of the Argon2 password-hashing function

Safe Haskell | None
Language | Haskell2010

Crypto.Argon2

Contents

- Computing hashes
- Verification
- Configuring hashing
- Exceptions

Description

Crypto.Argon2 provides bindings to the reference implementation of Argon2, the password-hashing function that won the Password Hashing Competition (PHC).

The main entry points to this module are `hashEncoded`, which produces a crypt-like ASCII output; and `hash` which produces a `ByteString` (a stream of bytes). Argon2 is a configurable hash function, and can be configured by supplying a particular set of `HashOptions` - `defaultHashOptions` should provide a good starting point. See `HashOptions` for more documentation on the particular parameters that can be adjusted.

For access directly to the C interface, see Crypto.Argon2.FFI.

Synopsis

- hashEncoded :: HashOptions -> ByteString -> ByteString -> Text
- hash :: HashOptions -> ByteString -> ByteString -> ByteString
- verify :: Text -> ByteString -> Bool
- data HashOptions = HashOptions {
  - hashIterations :: !Word32
  - hashMemory :: !Word32
  - hashParallelism :: !Word32
  - hashVariant :: !Argon2Variant
  }
- data Argon2Variant
  - = Argon2i
  - | Argon2d
- defaultHashOptions :: HashOptions
- data Argon2Exception
  - = Argon2PasswordLengthOutOfRange !CSize
  - | Argon2SaltLengthOutOfRange !CSize
  - | Argon2MemoryUseOutOfRange !Word32
  - | Argon2IterationCountOutOfRange !Word32
  - | Argon2ParallelismOutOfRange !Word32
  - | Argon2Exception !Int32

# Computing hashes

hashEncoded Source #

Arguments

:: HashOptions | Options pertaining to how expensive the hash is to calculate.
-> ByteString | The password to hash. Must be less than 4294967295 bytes.
-> ByteString | The salt to use when hashing. Must be less than 4294967295 bytes.
-> Text | The encoded password hash.

Encode a password with a given salt and `HashOptions` and produce a textual encoding of the result.

hash Source #

Arguments

:: HashOptions | Options pertaining to how expensive the hash is to calculate.
-> ByteString | The password to hash. Must be less than 4294967295 bytes.
-> ByteString | The salt to use when hashing. Must be less than 4294967295 bytes.
-> ByteString | The un-encoded password hash.

Encode a password with a given salt and `HashOptions` and produce a stream of bytes.

# Verification

verify :: Text -> ByteString -> Bool Source #

Verify that a given password could result in a given hash output. Automatically determines the correct `HashOptions` based on the encoded hash (as produced by `hashEncoded`).

# Configuring hashing

data HashOptions Source #

Parameters that can be adjusted to change the runtime performance of the hashing.

Constructors

HashOptions |

Fields

- hashIterations :: !Word32

  The time cost, which defines the amount of computation realized and therefore the execution time, given in number of iterations.

  `ARGON2_MIN_TIME` <= `hashIterations` <= `ARGON2_MAX_TIME`

- hashMemory :: !Word32

  The memory cost, which defines the memory usage, given in kibibytes.

  max `ARGON2_MIN_MEMORY` (8 * `hashParallelism`) <= `hashMemory` <= `ARGON2_MAX_MEMORY`

- hashParallelism :: !Word32

  A parallelism degree, which defines the number of parallel threads.

  `ARGON2_MIN_LANES` <= `hashParallelism` <= `ARGON2_MAX_LANES` && `ARGON_MIN_THREADS` <= `hashParallelism` <= `ARGON2_MAX_THREADS`

- hashVariant :: !Argon2Variant

  Which version of Argon2 to use.

Instances

Bounded HashOptions Source # |
Methods minBound :: HashOptions # maxBound :: HashOptions #
Eq HashOptions Source # |
Methods (==) :: HashOptions -> HashOptions -> Bool # (/=) :: HashOptions -> HashOptions -> Bool #
Ord HashOptions Source # |
Methods compare :: HashOptions -> HashOptions -> Ordering # (<) :: HashOptions -> HashOptions -> Bool # (<=) :: HashOptions -> HashOptions -> Bool # (>) :: HashOptions -> HashOptions -> Bool # (>=) :: HashOptions -> HashOptions -> Bool # max :: HashOptions -> HashOptions -> HashOptions # min :: HashOptions -> HashOptions -> HashOptions #
Read HashOptions Source # |
Methods readsPrec :: Int -> ReadS HashOptions # readList :: ReadS [HashOptions] # readPrec :: ReadPrec HashOptions # readListPrec :: ReadPrec [HashOptions] #
Show HashOptions Source # |
Methods showsPrec :: Int -> HashOptions -> ShowS # show :: HashOptions -> String # showList :: [HashOptions] -> ShowS #
Generic HashOptions Source # |
Associated Types type Rep HashOptions :: * -> * # Methods from :: HashOptions -> Rep HashOptions x # to :: Rep HashOptions x -> HashOptions #
type Rep HashOptions Source # |

type Rep HashOptions = D1 (MetaData "HashOptions" "Crypto.Argon2" "argon2-1.2.0-34BCT97DazHC6hmlmEfz20" False) (C1 (MetaCons "HashOptions" PrefixI True) ((:*:) ((:*:) (S1 (MetaSel (Just Symbol "hashIterations") NoSourceUnpackedness SourceStrict DecidedUnpack) (Rec0 Word32)) (S1 (MetaSel (Just Symbol "hashMemory") NoSourceUnpackedness SourceStrict DecidedUnpack) (Rec0 Word32))) ((:*:) (S1 (MetaSel (Just Symbol "hashParallelism") NoSourceUnpackedness SourceStrict DecidedUnpack) (Rec0 Word32)) (S1 (MetaSel (Just Symbol "hashVariant") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 Argon2Variant)))))

data Argon2Variant Source #

Which variant of Argon2 to use. You should choose the variant that is most applicable to your intention to hash inputs.

Constructors

Argon2i | Argon2i uses data-independent memory access, which is preferred for password hashing and password-based key derivation. Argon2i is slower as it makes more passes over the memory to protect from tradeoff attacks.
Argon2d | Argon2d is faster and uses data-depending memory access, which makes it suitable for cryptocurrencies and applications with no threats from side-channel timing attacks.

Instances

Bounded Argon2Variant Source # |
Methods minBound :: Argon2Variant # maxBound :: Argon2Variant #
Enum Argon2Variant Source # |

Methods

succ :: Argon2Variant -> Argon2Variant #

pred :: Argon2Variant -> Argon2Variant #

toEnum :: Int -> Argon2Variant #

fromEnum :: Argon2Variant -> Int #

enumFrom :: Argon2Variant -> [Argon2Variant] #

enumFromThen :: Argon2Variant -> Argon2Variant -> [Argon2Variant] #

enumFromTo :: Argon2Variant -> Argon2Variant -> [Argon2Variant] #

enumFromThenTo :: Argon2Variant -> Argon2Variant -> Argon2Variant -> [Argon2Variant] #

Eq Argon2Variant Source # |
Methods (==) :: Argon2Variant -> Argon2Variant -> Bool # (/=) :: Argon2Variant -> Argon2Variant -> Bool #
Ord Argon2Variant Source # |
Methods compare :: Argon2Variant -> Argon2Variant -> Ordering # (<) :: Argon2Variant -> Argon2Variant -> Bool # (<=) :: Argon2Variant -> Argon2Variant -> Bool # (>) :: Argon2Variant -> Argon2Variant -> Bool # (>=) :: Argon2Variant -> Argon2Variant -> Bool # max :: Argon2Variant -> Argon2Variant -> Argon2Variant # min :: Argon2Variant -> Argon2Variant -> Argon2Variant #
Read Argon2Variant Source # |
Methods readsPrec :: Int -> ReadS Argon2Variant # readList :: ReadS [Argon2Variant] # readPrec :: ReadPrec Argon2Variant # readListPrec :: ReadPrec [Argon2Variant] #
Show Argon2Variant Source # |
Methods showsPrec :: Int -> Argon2Variant -> ShowS # show :: Argon2Variant -> String # showList :: [Argon2Variant] -> ShowS #
Generic Argon2Variant Source # |
Associated Types type Rep Argon2Variant :: * -> * # Methods from :: Argon2Variant -> Rep Argon2Variant x # to :: Rep Argon2Variant x -> Argon2Variant #
type Rep Argon2Variant Source # |
type Rep Argon2Variant = D1 (MetaData "Argon2Variant" "Crypto.Argon2" "argon2-1.2.0-34BCT97DazHC6hmlmEfz20" False) ((:+:) (C1 (MetaCons "Argon2i" PrefixI False) U1) (C1 (MetaCons "Argon2d" PrefixI False) U1))

defaultHashOptions :: HashOptions Source #

A set of default `HashOptions`, taken from the `argon2` executable.

    defaultHashOptions :: HashOptions
    defaultHashOptions =
      HashOptions {hashIterations = 1
                  ,hashMemory = 2 ^ 17
                  ,hashParallelism = 4
                  ,hashVariant = Argon2i}

# Exceptions

data Argon2Exception Source #

Not all `HashOptions` can necessarily be used to compute hashes. If you supply invalid `HashOptions` (or hashing otherwise fails) a `Argon2Exception` will be throw.

Constructors

Argon2PasswordLengthOutOfRange !CSize | The length of the supplied password is outside the range supported by `libargon2`.
Argon2SaltLengthOutOfRange !CSize | The length of the supplied salt is outside the range supported by `libargon2`.
Argon2MemoryUseOutOfRange !Word32 | Either too much or too little memory was requested via `hashMemory`.
Argon2IterationCountOutOfRange !Word32 | Either too few or too many iterations were requested via `hashIterations`.
Argon2ParallelismOutOfRange !Word32 | Either too much or too little parallelism was requested via `hasParallelism`.
Argon2Exception !Int32 | An unexpected exception was throw. Please report this as a bug!

Instances

Show Argon2Exception Source # |
Methods showsPrec :: Int -> Argon2Exception -> ShowS # show :: Argon2Exception -> String # showList :: [Argon2Exception] -> ShowS #
Exception Argon2Exception Source # |
Methods toException :: Argon2Exception -> SomeException # fromException :: SomeException -> Maybe Argon2Exception # displayException :: Argon2Exception -> String #