cryptonite-0.30: Cryptography Primitives sink

Safe Haskell | Safe-Inferred
Language | Haskell2010

Crypto.OTP

Description

One-time password implementation as defined by the HOTP and TOTP specifications.

Both implementations use a shared key between the client and the server. HOTP passwords are based on a synchronized counter. TOTP passwords use the same approach but calculate the counter as a number of time steps from the Unix epoch to the current time, thus requiring that both client and server have synchronized clocks.

Probably the best-known use of TOTP is in Google's 2-factor authentication.

The TOTP API doesn't depend on any particular time package, so the user needs to supply the current `OTPTime` value, based on the system time. For example, using the `hourglass` package, you could create a `getOTPTime` function:

    >>> import Time.System
    >>> import Time.Types
    >>>
    >>> let getOTPTime = timeCurrent >>= \(Elapsed t) -> return (fromIntegral t :: OTPTime)

Or if you prefer, the `time` package could be used:

    >>> import Data.Time.Clock.POSIX
    >>>
    >>> let getOTPTime = getPOSIXTime >>= \t -> return (floor t :: OTPTime)

Synopsis

- type OTP = Word32
- data OTPDigits
  - = OTP4
  - | OTP5
  - | OTP6
  - | OTP7
  - | OTP8
  - | OTP9
- type OTPTime = Word64
- hotp :: forall hash key. (HashAlgorithm hash, ByteArrayAccess key) => hash -> OTPDigits -> key -> Word64 -> OTP
- resynchronize :: (HashAlgorithm hash, ByteArrayAccess key) => hash -> OTPDigits -> Word16 -> key -> Word64 -> (OTP, [OTP]) -> Maybe Word64
- totp :: (HashAlgorithm hash, ByteArrayAccess key) => TOTPParams hash -> key -> OTPTime -> OTP
- totpVerify :: (HashAlgorithm hash, ByteArrayAccess key) => TOTPParams hash -> key -> OTPTime -> OTP -> Bool
- data TOTPParams h
- data ClockSkew
  - = NoSkew
  - | OneStep
  - | TwoSteps
  - | ThreeSteps
  - | FourSteps
- defaultTOTPParams :: TOTPParams SHA1
- mkTOTPParams :: HashAlgorithm hash => hash -> OTPTime -> Word16 -> OTPDigits -> ClockSkew -> Either String (TOTPParams hash)

# Documentation

type OTP = Word32 Source #

A one-time password which is a sequence of 4 to 9 digits.

data OTPDigits Source #

The strength of the calculated HOTP value, namely the number of digits (between 4 and 9) in the extracted value.

Constructors

OTP4 |
OTP5 |
OTP6 |
OTP7 |
OTP8 |
OTP9 |

#### Instances

Instances details

Show OTPDigits Source # |
Instance details Defined in Crypto.OTP Methods showsPrec :: Int -> OTPDigits -> ShowS Source # show :: OTPDigits -> String Source # showList :: [OTPDigits] -> ShowS Source #

type OTPTime = Word64 Source #

An integral time value in seconds.

hotp Source #

Arguments

:: forall hash key. (HashAlgorithm hash, ByteArrayAccess key) |
=> hash |
-> OTPDigits | Number of digits in the HOTP value extracted from the calculated HMAC
-> key | Shared secret between the client and server
-> Word64 | Counter value synchronized between the client and server
-> OTP | The HOTP value

resynchronize Source #

Arguments

:: (HashAlgorithm hash, ByteArrayAccess key) |
=> hash |
-> OTPDigits |
-> Word16 | The look-ahead window parameter. Up to this many values will be calculated and checked against the value(s) submitted by the client
-> key | The shared secret
-> Word64 | The current server counter value
-> (OTP, [OTP]) | The first OTP submitted by the client and a list of additional sequential OTPs (which may be empty)
-> Maybe Word64 | The new counter value, synchronized with the client's current counter or Nothing if the submitted OTP values didn't match anywhere within the window

Attempt to resynchronize the server's counter value with the client, given a sequence of HOTP values.

totp Source #

Arguments

:: (HashAlgorithm hash, ByteArrayAccess key) |
=> TOTPParams hash |
-> key | The shared secret
-> OTPTime | The time for which the OTP should be calculated. This is usually the current time as returned by `Data.Time.Clock.POSIX.getPOSIXTime`
-> OTP |

Calculate a totp value for the given time.

totpVerify :: (HashAlgorithm hash, ByteArrayAccess key) => TOTPParams hash -> key -> OTPTime -> OTP -> Bool Source #

Check a supplied TOTP value is valid for the given time, within the window defined by the skew parameter.

data TOTPParams h Source #

#### Instances

Instances details

Show h => Show (TOTPParams h) Source # |
Instance details Defined in Crypto.OTP Methods showsPrec :: Int -> TOTPParams h -> ShowS Source # show :: TOTPParams h -> String Source # showList :: [TOTPParams h] -> ShowS Source #

data ClockSkew Source #

Constructors

NoSkew |
OneStep |
TwoSteps |
ThreeSteps |
FourSteps |

#### Instances

Instances details

Enum ClockSkew Source # |

Instance details

Defined in Crypto.OTP

Methods

succ :: ClockSkew -> ClockSkew Source #

pred :: ClockSkew -> ClockSkew Source #

toEnum :: Int -> ClockSkew Source #

fromEnum :: ClockSkew -> Int Source #

enumFrom :: ClockSkew -> [ClockSkew] Source #

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

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

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

Show ClockSkew Source # |
Instance details Defined in Crypto.OTP Methods showsPrec :: Int -> ClockSkew -> ShowS Source # show :: ClockSkew -> String Source # showList :: [ClockSkew] -> ShowS Source #

defaultTOTPParams :: TOTPParams SHA1 Source #

The default TOTP configuration.

mkTOTPParams Source #

Arguments

:: HashAlgorithm hash |
=> hash |
-> OTPTime | The T0 parameter in seconds. This is the Unix time from which to start counting steps (default 0). Must be before the current time.
-> Word16 | The time step parameter X in seconds (default 30, maximum allowed 300)
-> OTPDigits | Number of required digits in the OTP (default 6)
-> ClockSkew | The number of time steps to check either side of the current value to allow for clock skew between client and server and or delay in submitting the value. The default is two time steps.
-> Either String (TOTPParams hash) |

Create a TOTP configuration with customized parameters.