One-time passwords

8.12

One-time passwords🔗ℹ

package: otp-lib

This module is an implementation of the one-time passwords defined in RFC 4226 and RFC 6238. It reuses the cryptographic primitives exposed in the crypto module.

1 HOTP🔗ℹ

Detailed in RFC 4226, HOTP (HMAC-based One-Time Password) uses a hashing algorithm and secret key to sign a moving factor to generate a one-time password.

The moving factor is a parameter provided by the user; it can be any value which is guaranteed to change each time a password is generated.

procedure
(generate-hotp secret
moving-factor
[ #:mode mode
#:digits digits
#:checksum? checksum?
#:truncation-offset truncation-offset]) → string?
  secret : bytes?
  moving-factor : exact-integer?
  mode : (or/c digest-spec? digest-impl?) = 'sha1
  digits : (between/c 4 10) = 6
  checksum? : boolean? = #f
  truncation-offset : (or/c #f (</c 16)) = #f

Generates a HOTP (HMAC-based One-Time Password) using the mode as the hashing algorithm and secret as the key.

The password is guaranteed to be a string? with a string-length of digits and characters between 0 and 9.

When checksum? is set, the password will have an extra checksum digit calculated using the Luhn algorithm.

The truncation-offset controls which part of the generated hash will be used for the password — in the case that it’s not set, it defaults to an automatic selection algorithm.

procedure
(hotp-valid? secret
moving-factor
code
[ #:mode mode
#:truncation-offset truncation-offset
#:checksum? checksum?]) → boolean?
  secret : bytes?
  moving-factor : exact-integer?
  code : string?
  mode : (or/c digest-spec? digest-impl?) = 'sha1
  truncation-offset : (or/c #f (</c 16)) = #f
  checksum? : boolean? = #f

Checks whether a code corresponds to the moving-factor.

The number of digits is inferred from the string-length of code and checksum?.

See the corresponding generate method for information on the rest of the parameters.

Detailed in RFC 6238, TOTP (Time-based One-Time Password), is an extension to HOTP using a Unix-based timestamp as a moving factor. This means there is no need for a second trusted channel to share a moving factor — the system clock and NTP servers fulfill that role.

procedure
(generate-totp secret
[ #:mode mode
#:time t
#:time-start t₀
#:time-step Δt
#:digits digits
#:checksum? checksum?]) → string?
  secret : bytes?
  mode : (or/c digest-spec? digest-impl?) = 'sha1
  t : exact-integer? = (current-seconds)
  t₀ : exact-nonnegative-integer? = 0
  Δt : exact-nonnegative-integer? = 30
  digits : (between/c 4 10) = 8
  checksum? : boolean? = #f

Generates a TOTP (Time-based One-Time Password) using the mode as the hashing algorithm, secret as the key and t as the moving factor.

The parameter Δt controls the resolution of the underling timer for the moving factor. t₀ is the time offset from the standard Unix epoch time. Both parameters are measured in seconds.

See generate-hotp for information on the rest of the parameters.

procedure
(totp-valid? secret
[ #:mode mode
#:time t
#:time-start t₀
#:time-step Δt
#:digits digits
#:checksum? checksum
#:max-drift max-drift]) → boolean?
  secret : bytes?
  mode : (or/c digest-spec? digest-impl?) = 'sha1
   t :
(or/c exact-integer?
      (-> exact-integer?))
= current-seconds
  t₀ : exact-nonnegative-integer? = 0
  Δt : exact-nonnegative-integer? = 30
  digits : (between/c 4 10) = 8
  checksum : boolean? = #f
  max-drift : exact-nonnegative-integer? = 0

Checks whether a code corresponds to the moving factor t.

The max-drift is the tolerance of method in either direction. This is to compensate for the fact that system clocks can drift and be different. This is measured in units of Δt and centred around t. With the default parameters, a max-drift of 1 corresponds to a window of (* 2 30) seconds around current-time.

See the corresponding generate method for information on the rest of the parameters.

One-time passwords🔗ℹ

1 HOTP🔗ℹ

2 TOTP🔗ℹ