ns_totp(n)

Name

ns_totp - Returns a decimal-coded time-based one-time password (TOTP)

Table Of Contents

• Table Of Contents
• Synopsis
• Description
• COMMANDS
• OPTIONS
• EXAMPLES
• CONFIGURATION
• See Also
• Keywords

Synopsis

Description

The function returns a time-based one time password (TOTP) as described in RFC-6238. The function uses the HOTP function of RFC-4226 but adds the possibility to restrict the validity of the password to a time window.

RFC-6238 defines TOTP as:

 TOTP = HOTP(K, T), where T is an integer
 
 K: key
 T: time slice (moving factor for one time passwd)

The implemented function ns_totp is a generalization by allowing to specify the message digest algorithm, the number of characters of the returned truncated value, a used_id and a time.

The listed command is available in installations when NaviServer is compiled with OpenSSL support and where the nsf package is installed.

COMMANDS

ns_totp ?-digest value? ?-digits integer? ?-interval integer? ?-user_id integer? ?-key value? ?-time time?

OPTIONS

-digest digest

Specifies the message digest algorithm used for checksum computation. The available algorithms are provided by OpenSSL. Typical choices include sha1, sha256, and sha512. The default is sha256.

-digits digits

Specifies the number of digits in the generated one-time password (OTP). The default value, as recommended in the RFC, is 8.

-interval interval

Specifies the validity period of the OTP in seconds (time step size). The default value is 30.

-user_id user_id

Specifies the user identifier used to derive a per-user secret. The secret can be provided explicitly with -key, or derived from user_id and the per-server serversecret configuration value. For testing, use -key. For production use, prefer -user_id together with a configured serversecret.

-key key

Specifies the secret key used for generating the OTP. If -key is not provided, -user_id must be used together with a configured per-server serversecret.

-time time

Specifies the time value (epoch seconds) used as the base for the OTP computation. If omitted, the current system time is used.

EXAMPLES

Minimal example:

 % ns_totp -key "tweedie123"
 33888450

A common application for TOTP is integration with authenticator apps such as Google Authenticator, which expect a specially formatted URL:

otpauth://TYPE/LABEL?PARAMETERS

where TYPE is either hotp or totp. This URL is typically encoded in a QR code. Most authenticator apps can scan such codes directly, or provide means to enter the parameters manually.

The URL encodes several parameters relevant for TOTP generation:

• secret: the Base32-encoded shared secret (mandatory)

• period: validity interval in seconds, default 30

• digits: number of digits in the OTP, default 6

• algorithm: hash algorithm, default SHA1

Among these, the only mandatory parameter is the secret. When using ns_totp, it is usually necessary to extract at least secret and digits from the URL, and to provide -digest explicitly, since the defaults of ns_totp (sha256 and 8 digits) differ from those used by many authenticator apps.

 # Decoded authenticator URL
 % set url otpauth://totp/IDENT?secret=XSECRETSECRETSECRETSECRETSECRETX&period=30&digits=6&issuer=WU%20Wien
 
 # Extract parameters from URL
 % set p [ns_set array [ns_parsequery [dict get [ns_parseurl $url] query]]]
 secret XSECRETSECRETSECRETSECRETSECRETX period 30 digits 6 issuer {WU Wien}
 
 # Generate TOTP
 % package require base32
 % ns_totp -digest sha1 -digits [dict get $p digits] -key [base32::decode [dict get $p secret]]
 259664

CONFIGURATION

When ns_totp is called with -user_id instead of an explicit -key, NaviServer derives a per-user secret from the configured server secret and the provided user identifier.

The server secret is configured per virtual server with the serversecret parameter in the ns/server/$server section.

ns_section ns/server/$server {
    ns_param serversecret "change-this-secret"
}

The value should be a site-specific secret and should not be shared between unrelated installations. Changing it invalidates TOTP values derived from -user_id.

For testing or one-off use, provide the secret directly with -key. For production use, prefer -user_id together with a configured serversecret, so that each user receives a personalized derived secret.

See Also

ns_crypt, ns_hmac, ns_hotp, ns_md, ns_rand, ns_sha1, nsd

Keywords

TOTP, crypto, encoding, nsf