#totp API reference

Time-based one-time passwords (RFC 6238 TOTP over RFC 4226 HOTP) - the six-digit two-factor codes authenticator apps show. A shared secret (a base32 string, the same one an app stores) plus the current time yields a short numeric code that both sides compute independently. Built on hash.hmac (HMAC-SHA1 by default; SHA-256 / SHA-512 optional), encoding (base32 secrets), and time (the 30-second step); the dynamic-truncation step uses bytes + bitwise operators. Pure .j, runs on both binaries.

generate / verify read the clock; generateAt / verifyAt take an explicit Unix time (deterministic - use them in tests). verify accepts a +/-1-step clock-skew window. uri builds the otpauth:// provisioning string an authenticator app scans as a QR code.

Import with import "totp.j" as totp;. See the totp guide for prose and examples.

#Functions

#totp.generate(secret as string, opts as Options)

Compute the TOTP code for the current time.

Parameters

• secret {string} - the base32 shared secret
• opts {Options} - digits / period / algorithm (zero-value = defaults)

Returns {string} - the zero-padded numeric code

#totp.generateAt(secret as string, unixSeconds as int, opts as Options)

Compute the TOTP code for an explicit Unix time (seconds). Deterministic.

Parameters

• secret {string} - the base32 shared secret
• unixSeconds {int} - the Unix time in seconds
• opts {Options} - digits / period / algorithm (zero-value = defaults)

Returns {string} - the zero-padded numeric code

#totp.generateSecret()

Generate a fresh random shared secret with the RFC 6238-recommended length for SHA-1 TOTP (20 bytes / 160 bits), as an unpadded base32 string.

Returns {string} - the base32-encoded secret

#totp.generateSecretN(nbytes as int)

Generate a fresh random shared secret of an explicit byte length, as a base32 string (unpadded, the authenticator format decodeSecret accepts). Randomness is crypto-grade (crypto.randBytes), so the secret is unguessable. Round-trips: the result works with generate / verify.

Parameters

• nbytes {int} - the number of random bytes (RFC 6238 recommends >= 20 for SHA-1)

Returns {string} - the base32-encoded secret

#totp.hotp(secret as string, counter as int)

The raw RFC 4226 HOTP: the six-digit HMAC-SHA1 code for an explicit counter, the counter-based building block TOTP layers a clock over. Use it directly for HOTP (event-based OTP) or to pin against the RFC 4226 test vectors; TOTP itself is just this over unixSeconds // period.

Parameters

• secret {string} - the base32 shared secret
• counter {int} - the RFC 4226 moving-factor counter

Returns {string} - the six-digit zero-padded numeric code

#totp.uri(issuer as string, account as string, secret as string, opts as Options)

Build the otpauth://totp/... provisioning URI an authenticator app scans (as a QR code) to enrol an account. The label is issuer:account.

Parameters

• issuer {string} - the service name (e.g. "ACME")
• account {string} - the account name (e.g. "jane@acme.example")
• secret {string} - the base32 shared secret
• opts {Options} - digits / period / algorithm (zero-value = defaults)

Returns {string} - the otpauth provisioning URI

#totp.verify(secret as string, code as string, opts as Options)

Verify a code against the current time, allowing a +/-1-step skew.

Parameters

• secret {string} - the base32 shared secret
• code {string} - the code to check
• opts {Options} - digits / period / algorithm (zero-value = defaults)

Returns {bool} - true if the code matches

#totp.verifyAt(secret as string, code as string, unixSeconds as int, opts as Options)

Verify a code against an explicit Unix time, allowing a +/-1-step skew (so a code from the previous or next window still passes). Deterministic.

Parameters

• secret {string} - the base32 shared secret
• code {string} - the code to check
• unixSeconds {int} - the Unix time in seconds
• opts {Options} - digits / period / algorithm (zero-value = defaults)

Returns {bool} - true if the code matches this step or an adjacent one

#totp.verifyWindow(secret as string, code as string, window as int, opts as Options)

Verify a code against the current time, allowing a window-step skew on each side of now.

Parameters

• secret {string} - the base32 shared secret
• code {string} - the code to check
• window {int} - the number of period-steps to accept on each side of now
• opts {Options} - digits / period / algorithm (zero-value = defaults)

Returns {bool} - true if the code matches any step within the window

#totp.verifyWindowAt(secret as string, code as string, unixSeconds as int, window as int, opts as Options)

Verify a code against an explicit Unix time, allowing a window-step skew on each side of now (so window steps of clock drift in either direction still pass). window 0 checks only the current step; window 1 is the +/-1-step default verifyAt uses. Deterministic.

Parameters

• secret {string} - the base32 shared secret
• code {string} - the code to check
• unixSeconds {int} - the Unix time in seconds
• window {int} - the number of period-steps to accept on each side of now
• opts {Options} - digits / period / algorithm (zero-value = defaults)

Returns {bool} - true if the code matches any step within the window

#Structs

#totp.Options

TOTP parameters. A zero-value struct (def o as totp.Options;) means the common defaults: 6 digits, a 30-second step, and HMAC-SHA1.

#Enums

#totp.Algorithm

The HMAC digest algorithm behind a TOTP code: Sha1 (the default), Sha256, or Sha512. Selected through Options.algorithm; the zero value is Sha1.