argon2-1.3.0.1: Memory-hard password hash and proof-of-work function

License | BSD3
Maintainer | hvr@gnu.org
Safe Haskell | Trustworthy
Language | Haskell2010

Crypto.Argon2

Contents

- Hash computation & verification
  - Binary hash representation
  - ASCII-encoded representation
- Configuring hashing
- Status codes

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 (unsafe) access directly to the C interface, see Crypto.Argon2.FFI.

Since: 1.3.0.0

Synopsis

- hash :: HashOptions -> ByteString -> ByteString -> Either Argon2Status ByteString
- hashEncoded :: HashOptions -> ByteString -> ByteString -> Either Argon2Status ShortText
- verifyEncoded :: ShortText -> ByteString -> Argon2Status
- data HashOptions = HashOptions {
  - hashIterations :: !Word32
  - hashMemory :: !Word32
  - hashParallelism :: !Word32
  - hashVariant :: !Argon2Variant
  - hashVersion :: !Argon2Version
  - hashLength :: !Word32
  }
- data Argon2Variant
  - = Argon2i
  - | Argon2d
  - | Argon2id
- data Argon2Version
  - = Argon2Version10
  - | Argon2Version13
- defaultHashOptions :: HashOptions
- data Argon2Status
  - = Argon2Ok
  - | Argon2OutputPtrNull
  - | Argon2OutputTooShort
  - | Argon2OutputTooLong
  - | Argon2PwdTooShort
  - | Argon2PwdTooLong
  - | Argon2SaltTooShort
  - | Argon2SaltTooLong
  - | Argon2AdTooShort
  - | Argon2AdTooLong
  - | Argon2SecretTooShort
  - | Argon2SecretTooLong
  - | Argon2TimeTooSmall
  - | Argon2TimeTooLarge
  - | Argon2MemoryTooLittle
  - | Argon2MemoryTooMuch
  - | Argon2LanesTooFew
  - | Argon2LanesTooMany
  - | Argon2PwdPtrMismatch
  - | Argon2SaltPtrMismatch
  - | Argon2SecretPtrMismatch
  - | Argon2AdPtrMismatch
  - | Argon2MemoryAllocationError
  - | Argon2FreeMemoryCbkNull
  - | Argon2AllocateMemoryCbkNull
  - | Argon2IncorrectParameter
  - | Argon2IncorrectType
  - | Argon2OutPtrMismatch
  - | Argon2ThreadsTooFew
  - | Argon2ThreadsTooMany
  - | Argon2MissingArgs
  - | Argon2EncodingFail
  - | Argon2DecodingFail
  - | Argon2ThreadFail
  - | Argon2DecodingLengthFail
  - | Argon2VerifyMismatch
  - | Argon2InternalError

# Hash computation & verification

## Binary hash representation

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.
-> Either Argon2Status ByteString | The un-encoded password hash (or error code in case of failure).

Encode a password with a given salt and `HashOptions` and produce a binary stream of bytes (of size `hashLength`).

## ASCII-encoded representation

These operations use the PHC string format, a crypt(3)-like serialization format for password 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.
-> Either Argon2Status ShortText | The encoded password hash (or error code in case of failure).

Encode a password with a given salt and `HashOptions` and produce a textual encoding according to the PHC string format of the result.

Use `verifyEncoded` to verify.

verifyEncoded :: ShortText -> ByteString -> Argon2Status Source #

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

Returns `Argon2Ok` on successful verification. If decoding is successful but the password mismatches, `Argon2VerifyMismatch` is returned; if decoding fails, the respective `Argon2Status` code is returned.

# Configuring hashing

data HashOptions Source #

Parameters that can be adjusted to change the runtime performance of the hashing. See also `defaultHashOptions`.

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 variant of Argon2 to use.

- hashVersion :: !Argon2Version

  Which version of Argon2 to use for generating hashes.

- hashLength :: !Word32

  Desired length of hash expressed in octets.

Instances

Bounded HashOptions Source # |
Instance details Defined in Crypto.Argon2 Methods minBound :: HashOptions Source # maxBound :: HashOptions Source #
Eq HashOptions Source # |
Instance details Defined in Crypto.Argon2 Methods (==) :: HashOptions -> HashOptions -> Bool Source # (/=) :: HashOptions -> HashOptions -> Bool Source #
Ord HashOptions Source # |

Instance details

Defined in Crypto.Argon2

Methods

compare :: HashOptions -> HashOptions -> Ordering Source #

(<) :: HashOptions -> HashOptions -> Bool Source #

(<=) :: HashOptions -> HashOptions -> Bool Source #

(>) :: HashOptions -> HashOptions -> Bool Source #

(>=) :: HashOptions -> HashOptions -> Bool Source #

max :: HashOptions -> HashOptions -> HashOptions Source #

min :: HashOptions -> HashOptions -> HashOptions Source #

Read HashOptions Source # |
Instance details Defined in Crypto.Argon2 Methods readsPrec :: Int -> ReadS HashOptions Source # readList :: ReadS [HashOptions] Source # readPrec :: ReadPrec HashOptions Source # readListPrec :: ReadPrec [HashOptions] Source #
Show HashOptions Source # |
Instance details Defined in Crypto.Argon2 Methods showsPrec :: Int -> HashOptions -> ShowS Source # show :: HashOptions -> String Source # showList :: [HashOptions] -> ShowS Source #
Generic HashOptions Source # |
Instance details Defined in Crypto.Argon2 Associated Types type Rep HashOptions :: Type -> Type Source # Methods from :: HashOptions -> Rep HashOptions x Source # to :: Rep HashOptions x -> HashOptions Source #
NFData HashOptions Source # |
Instance details Defined in Crypto.Argon2 Methods rnf :: HashOptions -> () Source #
type Rep HashOptions Source # |

Instance details

Defined in Crypto.Argon2

type Rep HashOptions = D1 (MetaData "HashOptions" "Crypto.Argon2" "argon2-1.3.0.1-8LyL1TejXG3Kn097RSFT1b" False) (C1 (MetaCons "HashOptions" PrefixI True) ((S1 (MetaSel (Just "hashIterations") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 Word32) :*: (S1 (MetaSel (Just "hashMemory") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 Word32) :*: S1 (MetaSel (Just "hashParallelism") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 Word32))) :*: (S1 (MetaSel (Just "hashVariant") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 Argon2Variant) :*: (S1 (MetaSel (Just "hashVersion") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 Argon2Version) :*: S1 (MetaSel (Just "hashLength") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 Word32)))))

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.
Argon2id | Argon2id works as Argon2i for the first half of the first iteration over the memory, and as Argon2d for the rest, thus providing both side-channel attack protection and brute-force cost savings due to time-memory tradeoffs.

Instances

Bounded Argon2Variant Source # |
Instance details Defined in Crypto.Argon2 Methods minBound :: Argon2Variant Source # maxBound :: Argon2Variant Source #
Enum Argon2Variant Source # |

Instance details

Defined in Crypto.Argon2

Methods

succ :: Argon2Variant -> Argon2Variant Source #

pred :: Argon2Variant -> Argon2Variant Source #

toEnum :: Int -> Argon2Variant Source #

fromEnum :: Argon2Variant -> Int Source #

enumFrom :: Argon2Variant -> [Argon2Variant] Source #

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

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

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

Eq Argon2Variant Source # |
Instance details Defined in Crypto.Argon2 Methods (==) :: Argon2Variant -> Argon2Variant -> Bool Source # (/=) :: Argon2Variant -> Argon2Variant -> Bool Source #
Ord Argon2Variant Source # |

Instance details

Defined in Crypto.Argon2

Methods

compare :: Argon2Variant -> Argon2Variant -> Ordering Source #

(<) :: Argon2Variant -> Argon2Variant -> Bool Source #

(<=) :: Argon2Variant -> Argon2Variant -> Bool Source #

(>) :: Argon2Variant -> Argon2Variant -> Bool Source #

(>=) :: Argon2Variant -> Argon2Variant -> Bool Source #

max :: Argon2Variant -> Argon2Variant -> Argon2Variant Source #

min :: Argon2Variant -> Argon2Variant -> Argon2Variant Source #

Read Argon2Variant Source # |
Instance details Defined in Crypto.Argon2 Methods readsPrec :: Int -> ReadS Argon2Variant Source # readList :: ReadS [Argon2Variant] Source # readPrec :: ReadPrec Argon2Variant Source # readListPrec :: ReadPrec [Argon2Variant] Source #
Show Argon2Variant Source # |
Instance details Defined in Crypto.Argon2 Methods showsPrec :: Int -> Argon2Variant -> ShowS Source # show :: Argon2Variant -> String Source # showList :: [Argon2Variant] -> ShowS Source #
Generic Argon2Variant Source # |
Instance details Defined in Crypto.Argon2 Associated Types type Rep Argon2Variant :: Type -> Type Source # Methods from :: Argon2Variant -> Rep Argon2Variant x Source # to :: Rep Argon2Variant x -> Argon2Variant Source #
NFData Argon2Variant Source # |
Instance details Defined in Crypto.Argon2 Methods rnf :: Argon2Variant -> () Source #
type Rep Argon2Variant Source # |
Instance details Defined in Crypto.Argon2 type Rep Argon2Variant = D1 (MetaData "Argon2Variant" "Crypto.Argon2" "argon2-1.3.0.1-8LyL1TejXG3Kn097RSFT1b" False) (C1 (MetaCons "Argon2i" PrefixI False) (U1 :: Type -> Type) :+: (C1 (MetaCons "Argon2d" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "Argon2id" PrefixI False) (U1 :: Type -> Type)))

data Argon2Version Source #

Version of the Argon2 algorithm.

Constructors

Argon2Version10 | Version 1.0 (deprecated)
Argon2Version13 | Version 1.3 (See this announcment for more details)

Instances

Bounded Argon2Version Source # |
Instance details Defined in Crypto.Argon2 Methods minBound :: Argon2Version Source # maxBound :: Argon2Version Source #
Enum Argon2Version Source # |

Instance details

Defined in Crypto.Argon2

Methods

succ :: Argon2Version -> Argon2Version Source #

pred :: Argon2Version -> Argon2Version Source #

toEnum :: Int -> Argon2Version Source #

fromEnum :: Argon2Version -> Int Source #

enumFrom :: Argon2Version -> [Argon2Version] Source #

enumFromThen :: Argon2Version -> Argon2Version -> [Argon2Version] Source #

enumFromTo :: Argon2Version -> Argon2Version -> [Argon2Version] Source #

enumFromThenTo :: Argon2Version -> Argon2Version -> Argon2Version -> [Argon2Version] Source #

Eq Argon2Version Source # |
Instance details Defined in Crypto.Argon2 Methods (==) :: Argon2Version -> Argon2Version -> Bool Source # (/=) :: Argon2Version -> Argon2Version -> Bool Source #
Ord Argon2Version Source # |

Instance details

Defined in Crypto.Argon2

Methods

compare :: Argon2Version -> Argon2Version -> Ordering Source #

(<) :: Argon2Version -> Argon2Version -> Bool Source #

(<=) :: Argon2Version -> Argon2Version -> Bool Source #

(>) :: Argon2Version -> Argon2Version -> Bool Source #

(>=) :: Argon2Version -> Argon2Version -> Bool Source #

max :: Argon2Version -> Argon2Version -> Argon2Version Source #

min :: Argon2Version -> Argon2Version -> Argon2Version Source #

Read Argon2Version Source # |
Instance details Defined in Crypto.Argon2 Methods readsPrec :: Int -> ReadS Argon2Version Source # readList :: ReadS [Argon2Version] Source # readPrec :: ReadPrec Argon2Version Source # readListPrec :: ReadPrec [Argon2Version] Source #
Show Argon2Version Source # |
Instance details Defined in Crypto.Argon2 Methods showsPrec :: Int -> Argon2Version -> ShowS Source # show :: Argon2Version -> String Source # showList :: [Argon2Version] -> ShowS Source #
Generic Argon2Version Source # |
Instance details Defined in Crypto.Argon2 Associated Types type Rep Argon2Version :: Type -> Type Source # Methods from :: Argon2Version -> Rep Argon2Version x Source # to :: Rep Argon2Version x -> Argon2Version Source #
NFData Argon2Version Source # |
Instance details Defined in Crypto.Argon2 Methods rnf :: Argon2Version -> () Source #
type Rep Argon2Version Source # |
Instance details Defined in Crypto.Argon2 type Rep Argon2Version = D1 (MetaData "Argon2Version" "Crypto.Argon2" "argon2-1.3.0.1-8LyL1TejXG3Kn097RSFT1b" False) (C1 (MetaCons "Argon2Version10" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "Argon2Version13" PrefixI False) (U1 :: Type -> Type))

defaultHashOptions :: HashOptions Source #

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

    defaultHashOptions :: HashOptions
    defaultHashOptions =
      HashOptions { hashIterations  = 3
                  , hashMemory      = 2 ^ 12 -- 4 MiB
                  , hashParallelism = 1
                  , hashVariant     = Argon2i
                  , hashVersion     = Argon2Version13
                  , hashLength      = 2 ^ 5 -- 32 bytes
                  }

For more information on how to select these parameters for your application, see section 6.4 of the Argon2 specification.

# Status codes

data Argon2Status Source #

Returned status code for Argon2 functions.

Not all `HashOptions` can necessarily be used to compute hashes. If you supply unsupported or invalid `HashOptions` (or hashing otherwise fails) an `Argon2Status` value will be returned to describe the failure.

Note that this enumeration contains some status codes which are not expected to be returned by the operation provided by the Haskell API.

Constructors

Argon2Ok | OK (operation succeeded)
Argon2OutputPtrNull | Output pointer is `NULL`
Argon2OutputTooShort | Output is too short
Argon2OutputTooLong | Output is too long
Argon2PwdTooShort | Password is too short
Argon2PwdTooLong | Password is too long
Argon2SaltTooShort | Salt is too short
Argon2SaltTooLong | Salt is too long
Argon2AdTooShort | Associated data is too short
Argon2AdTooLong | Associated data is too long
Argon2SecretTooShort | Secret is too short
Argon2SecretTooLong | Secret is too long
Argon2TimeTooSmall | Time cost is too small
Argon2TimeTooLarge | Time cost is too large
Argon2MemoryTooLittle | Memory cost is too small
Argon2MemoryTooMuch | Memory cost is too large
Argon2LanesTooFew | Too few lanes
Argon2LanesTooMany | Too many lanes
Argon2PwdPtrMismatch | Password pointer is `NULL`, but password length is not 0
Argon2SaltPtrMismatch | Salt pointer is `NULL`, but salt length is not 0
Argon2SecretPtrMismatch | Secret pointer is `NULL`, but secret length is not 0
Argon2AdPtrMismatch | Associated data pointer is `NULL`, but ad length is not 0
Argon2MemoryAllocationError | Memory allocation error
Argon2FreeMemoryCbkNull | The free memory callback is `NULL`
Argon2AllocateMemoryCbkNull | The allocate memory callback is `NULL`
Argon2IncorrectParameter | `Argon2_Context` context is `NULL`
Argon2IncorrectType | There is no such version of Argon2
Argon2OutPtrMismatch | Output pointer mismatch
Argon2ThreadsTooFew | Not enough threads
Argon2ThreadsTooMany | Too many threads
Argon2MissingArgs | Missing arguments
Argon2EncodingFail | Encoding failed
Argon2DecodingFail | Decoding failed
Argon2ThreadFail | Threading failure
Argon2DecodingLengthFail | Some of encoded parameters are too long or too short
Argon2VerifyMismatch | The password does not match the supplied hash
Argon2InternalError | Internal error or unrecognized status code

Instances

Bounded Argon2Status Source # |
Instance details Defined in Crypto.Argon2 Methods minBound :: Argon2Status Source # maxBound :: Argon2Status Source #
Enum Argon2Status Source # |

Instance details

Defined in Crypto.Argon2

Methods

succ :: Argon2Status -> Argon2Status Source #

pred :: Argon2Status -> Argon2Status Source #

toEnum :: Int -> Argon2Status Source #

fromEnum :: Argon2Status -> Int Source #

enumFrom :: Argon2Status -> [Argon2Status] Source #

enumFromThen :: Argon2Status -> Argon2Status -> [Argon2Status] Source #

enumFromTo :: Argon2Status -> Argon2Status -> [Argon2Status] Source #

enumFromThenTo :: Argon2Status -> Argon2Status -> Argon2Status -> [Argon2Status] Source #

Eq Argon2Status Source # |
Instance details Defined in Crypto.Argon2 Methods (==) :: Argon2Status -> Argon2Status -> Bool Source # (/=) :: Argon2Status -> Argon2Status -> Bool Source #
Ord Argon2Status Source # |

Instance details

Defined in Crypto.Argon2

Methods

compare :: Argon2Status -> Argon2Status -> Ordering Source #

(<) :: Argon2Status -> Argon2Status -> Bool Source #

(<=) :: Argon2Status -> Argon2Status -> Bool Source #

(>) :: Argon2Status -> Argon2Status -> Bool Source #

(>=) :: Argon2Status -> Argon2Status -> Bool Source #

max :: Argon2Status -> Argon2Status -> Argon2Status Source #

min :: Argon2Status -> Argon2Status -> Argon2Status Source #

Read Argon2Status Source # |
Instance details Defined in Crypto.Argon2 Methods readsPrec :: Int -> ReadS Argon2Status Source # readList :: ReadS [Argon2Status] Source # readPrec :: ReadPrec Argon2Status Source # readListPrec :: ReadPrec [Argon2Status] Source #
Show Argon2Status Source # |
Instance details Defined in Crypto.Argon2 Methods showsPrec :: Int -> Argon2Status -> ShowS Source # show :: Argon2Status -> String Source # showList :: [Argon2Status] -> ShowS Source #
Exception Argon2Status Source # |
Instance details Defined in Crypto.Argon2 Methods toException :: Argon2Status -> SomeException Source # fromException :: SomeException -> Maybe Argon2Status Source # displayException :: Argon2Status -> String Source #
NFData Argon2Status Source # |
Instance details Defined in Crypto.Argon2 Methods rnf :: Argon2Status -> () Source #