| License | BSD3 |
|---|---|
| Maintainer | hvr@gnu.org |
| Safe Haskell | Trustworthy |
| Language | Haskell2010 |
Crypto.Argon2
Contents
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
- hash :: HashOptions -> ByteString -> ByteString -> Either Argon2Status ByteString
- hashEncoded :: HashOptions -> ByteString -> ByteString -> Either Argon2Status ShortText
- verifyEncoded :: ShortText -> ByteString -> Argon2Status
- data HashOptions = HashOptions {}
- data Argon2Variant
- data Argon2Version
- 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
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.
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
| |
Instances
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. |
data Argon2Version Source #
Version of the Argon2 algorithm.
Constructors
| Argon2Version10 | Version 1.0 (deprecated) |
| Argon2Version13 | Version 1.3 (See this announcment for more details) |
defaultHashOptions :: HashOptions Source #
A set of default HashOptions, taken from the argon2 executable.
defaultHashOptions::HashOptionsdefaultHashOptions=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 |
| 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 |
| Argon2SaltPtrMismatch | Salt pointer is |
| Argon2SecretPtrMismatch | Secret pointer is |
| Argon2AdPtrMismatch | Associated data pointer is |
| Argon2MemoryAllocationError | Memory allocation error |
| Argon2FreeMemoryCbkNull | The free memory callback is |
| Argon2AllocateMemoryCbkNull | The allocate memory callback is |
| Argon2IncorrectParameter |
|
| 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 |