Crypto.OTP

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)

Documentation

type OTP = Word32

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

data OTPDigits

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

Show OTPDigits

Methods

showsPrec :: Int -> OTPDigits -> ShowS

show :: OTPDigits -> String

showList :: [OTPDigits] -> ShowS

type OTPTime = Word64

An integral time value in seconds.

hotp

Arguments

:: (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

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

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

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

data TOTPParams h

Instances

Show h => Show (TOTPParams h)

Methods

showsPrec :: Int -> TOTPParams h -> ShowS

show :: TOTPParams h -> String

showList :: [TOTPParams h] -> ShowS

data ClockSkew

Constructors

NoSkew

OneStep

TwoSteps

ThreeSteps

FourSteps

Instances

Enum ClockSkew

Methods

succ :: ClockSkew -> ClockSkew

pred :: ClockSkew -> ClockSkew

toEnum :: Int -> ClockSkew

fromEnum :: ClockSkew -> Int

enumFrom :: ClockSkew -> [ClockSkew]

enumFromThen :: ClockSkew -> ClockSkew -> [ClockSkew]

enumFromTo :: ClockSkew -> ClockSkew -> [ClockSkew]

enumFromThenTo :: ClockSkew -> ClockSkew -> ClockSkew -> [ClockSkew]

Show ClockSkew

Methods

showsPrec :: Int -> ClockSkew -> ShowS

show :: ClockSkew -> String

showList :: [ClockSkew] -> ShowS

defaultTOTPParams :: TOTPParams SHA1

The default TOTP configuration.

mkTOTPParams

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.