TOTP.hs

{-|
Module      : Botan.Bindings.TOTP
Description : Time-based one time passwords
Copyright   : (c) 2023-2024, Apotheca Labs
              (c) 2024-2025, Haskell Foundation
License     : BSD-3-Clause
Maintainer  : joris@well-typed.com, leo@apotheca.io
Stability   : experimental
Portability : POSIX

One time password schemes are a user authentication method that
relies on a fixed secret key which is used to derive a sequence
of short passwords, each of which is accepted only once. Commonly
this is used to implement two-factor authentication (2FA), where
the user authenticates using both a conventional password (or a
public key signature) and an OTP generated by a small device such
as a mobile phone.

Botan implements the HOTP and TOTP schemes from RFC 4226 and 6238.

Since the range of possible OTPs is quite small, applications must
rate limit OTP authentication attempts to some small number per
second. Otherwise an attacker could quickly try all 1000000 6-digit
OTPs in a brief amount of time.

HOTP generates OTPs that are a short numeric sequence, between 6
and 8 digits (most applications use 6 digits), created using the
HMAC of a 64-bit counter value. If the counter ever repeats the
OTP will also repeat, thus both parties must assure the counter
only increments and is never repeated or decremented. Thus both
client and server must keep track of the next counter expected.

Anyone with access to the client-specific secret key can authenticate
as that client, so it should be treated with the same security
consideration as would be given to any other symmetric key or
plaintext password.

TOTP is based on the same algorithm as HOTP, but instead of a
counter a timestamp is used.
-}

{-# LANGUAGE CApiFFI #-}

module Botan.Bindings.TOTP (
    BotanTOTPStruct
  , BotanTOTP (..)
  , botan_totp_destroy
  , botan_totp_init
  , botan_totp_generate
  , botan_totp_check
  ) where

import           Botan.Bindings.ConstPtr
import           Data.Word
import           Foreign.C.Types
import           Foreign.ForeignPtr
import           Foreign.Ptr
import           Foreign.Storable

-- NOTE: RFC 6238

-- | Opaque TOTP struct
data {-# CTYPE "botan/ffi.h" "struct botan_totp_struct" #-} BotanTOTPStruct

-- | Botan TOTP object
newtype {-# CTYPE "botan/ffi.h" "botan_totp_t" #-} BotanTOTP
    = MkBotanTOTP { runBotanTOTP :: Ptr BotanTOTPStruct }
        deriving newtype (Eq, Ord, Storable)

-- | Destroy a TOTP instance
foreign import capi safe "botan/ffi.h &botan_totp_destroy"
    botan_totp_destroy
        :: FinalizerPtr BotanTOTPStruct

-- | Initialize a TOTP instance
foreign import capi safe "botan/ffi.h botan_totp_init"
    botan_totp_init
    :: Ptr BotanTOTP    -- ^ __totp__
    -> ConstPtr Word8   -- ^ __key[]__
    -> CSize            -- ^ __key_len__
    -> ConstPtr CChar   -- ^ __hash_algo__
    -> CSize            -- ^ __digits__
    -> CSize            -- ^ __time_step__
    -> IO CInt

-- | Generate a TOTP code for the provided timestamp
foreign import capi safe "botan/ffi.h botan_totp_generate"
    botan_totp_generate
    :: BotanTOTP    -- ^ __totp__: the TOTP object
    -> Ptr Word32   -- ^ __totp_code__: the OTP code will be written here
    -> Word64       -- ^ __timestamp__: the current local timestamp
    -> IO CInt

-- | Verify a TOTP code
foreign import capi safe "botan/ffi.h botan_totp_check"
    botan_totp_check
    :: BotanTOTP    -- ^ __totp__: the TOTP object
    -> Word32       -- ^ __totp_code__: the presented OTP
    -> Word64       -- ^ __timestamp__: the current local timestamp
    -> CSize        -- ^ __acceptable_clock_drift__: specifies the acceptable amount
                    --   of clock drift (in terms of time steps) between the two hosts.
    -> IO CInt