]> independent

Canada ietf@andrewe.dev

otpauth hotp totp This document defines syntax and processing rules for the otpauth: URI scheme used to provision one-time-password (OTP) credentials (verification codes) for HOTP and TOTP. This document defines a common baseline for interoperability, including issuer handling rules that improve account matching while maintaining compatibility with existing deployments. It does not preclude future extensions for other OTP methods. Discussion Venues Source for this draft and an issue tracker can be found at .

Introduction The otpauth: URI scheme is used to transfer OTP configuration, including a shared secret and related parameters, into OTP clients. The scheme is currently registered with IANA as a provisional URI scheme . Current ecosystem behavior is primarily described by vendor documentation, including Google's otpauth key URI format and Apple's verification code guidance . Those documents are largely aligned, but differ on semantics for issuer information. This document defines interoperable behavior for URI producers and consumers for HOTP and TOTP, with emphasis on reliable account association in modern password managers. This document does not preclude future extensions for other OTP methods. An earlier individual Internet-Draft, , also proposes standardizing the otpauth: URI scheme. The two documents differ mainly in these ways:

• This document defines normative processing rules for producers and consumers, including conditions under which a consumer must reject a URI. The earlier draft describes the syntax without such rules.
• This document permits the legacy issuer label prefix for compatibility and makes the issuer parameter authoritative for account matching. The earlier draft instead recommends carrying the issuer only as a separate parameter.
• This document sets a minimum consumer baseline (SHA1 and 6 digits) and treats other values as SHOULD. The earlier draft calls for support of all of its optional parameters in all cases.
• This document constrains the label and secret grammar using productions.
• This document adds Security and Privacy Considerations for the shared secret.

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. This specification uses the Augmented Backus-Naur Form (ABNF) notation defined in . This specification uses the OTP concepts from and . In this document, secret, issuer, and account identify credential attributes associated with HOTP and TOTP methods. The term URI is imported from . Mentions of "query string" in this document refer to the URI query component defined in Section 3.4 of . The Base16, Base32, and Base64 data encodings referenced in this document are from . The terms "producer" and "consumer" are used throughout:

• A producer creates an otpauth: URI.
• A consumer parses and imports an otpauth: URI.

URI Format An otpauth: URI uses this general form: /? ]]> where <type> identifies the OTP algorithm family and <parameters> contains URL query parameters.

Syntax The syntax is defined using ABNF from and URI productions from . Per , quoted ABNF literals are case-insensitive. Therefore, otpauth, totp, and hotp are matched case-insensitively by this grammar. Producers SHOULD emit lowercase forms for consistency. The same case-insensitive matching applies to quoted parameter names and quoted enumerated values in this ABNF. This ABNF names commonly used parameters explicitly and allows extension parameters. Parameter requirements are defined in the following section. Parameter values MUST percent-encode literal & characters as %26. A consumer MUST parse label before decoding as follows:

• If label contains a separator, split the raw string at the first separator, where separator is either literal : or percent-encoded %3A (case-insensitive).
• If label does not contain a separator, treat the entire label as account.
• Percent-decode each parsed component using standard URI decoding rules from .
• If decoded issuer-label or decoded account contains a colon, the consumer MUST reject the URI.

otp-type otp-type identifies the OTP method and MUST be either totp or hotp. A consumer MUST reject a URI with any other otp-type.

label label identifies the account being provisioned: : ]]> In this structure:

• issuer-label is optional
• the separator is either a literal colon (:) or %3A
• optional spaces before account are encoded as %20
• issuer-label and account MUST NOT themselves contain a colon

Producers SHOULD percent-encode label components using URI encoding rules from . Valid examples include alice@example.com, Example:alice@example.com, and Example%20Issuer%3A%20alice@example.com.

Parameters Parameter order is not significant. A producer MUST include exactly one secret parameter. A consumer MUST reject the URI if secret is missing. A producer MUST include counter if otp-type is hotp. A producer MAY include algorithm, digits, and issuer, and MAY include period if otp-type is totp. Each known parameter MUST appear at most once. A consumer MUST reject the URI if any known parameter appears more than once. shows which parameters apply to each otp-type. Parameter applicability by otp-type

Parameter	totp	hotp
secret	REQUIRED	REQUIRED
issuer	RECOMMENDED	RECOMMENDED
algorithm	OPTIONAL	OPTIONAL
digits	OPTIONAL	OPTIONAL
period	OPTIONAL	NOT USED
counter	NOT USED	REQUIRED

NOT USED means that a producer SHOULD NOT include the parameter and a consumer MUST ignore it.

secret The secret parameter carries the shared OTP secret and is mandatory. The value MUST use unpadded Base32 with alphabet A-Z2-7, as specified by . Producers SHOULD emit uppercase Base32 text. Consumers MAY accept lowercase Base32 text for interoperability. requires a shared secret of at least 128 bits and recommends 160 bits (Section 4). Producers MUST use a secret that decodes to at least 128 bits and SHOULD use at least 160 bits. A consumer MAY reject a URI whose decoded secret is shorter than 128 bits.

issuer The issuer parameter identifies the relying party that issued the OTP credential. A producer SHOULD include issuer. A producer SHOULD set issuer to a stable service identifier that is useful for account matching and credential suggestion. A domain name controlled by the relying party (for example, example.com) is RECOMMENDED where available, but non-domain identifiers are allowed. A consumer SHOULD use issuer as the primary identifier for account matching and credential suggestion.

algorithm algorithm is OPTIONAL. If absent, the default is SHA1. Valid algorithm values are SHA1, SHA256, and SHA512. Producers SHOULD use one of these values.

• Consumers MUST support SHA1.
• Consumers SHOULD support SHA256 and SHA512.

defines HOTP with HMAC-SHA-1 only, and adds HMAC-SHA-256 and HMAC-SHA-512 for TOTP. This document also permits SHA256 and SHA512 with hotp, applying the same HMAC substitution, because some consumers support it. Some consumers ignore this parameter and always use SHA1; such a consumer generates codes that do not match the producer's. A producer SHOULD use SHA1 with hotp unless it knows the consumer supports other values. If a consumer receives an unsupported algorithm value, it SHOULD reject the URI.

digits digits is OPTIONAL. If absent, the default is 6. Valid digits values are 6, 7, and 8.

• Producers SHOULD use 6 or 8.
• Consumers MUST support 6.
• Consumers SHOULD support 8.
• Consumers MAY support 7.

permits 7-digit codes, but lists only 6 and 8, so producers are advised to avoid 7. If a consumer receives an unsupported digits value, it SHOULD reject the URI.

period period is OPTIONAL for totp. It is the time step, in seconds, defined in . The value MUST be a decimal integer greater than zero. If absent, the default is 30. A consumer MUST reject the URI if period is not a decimal integer greater than zero. The start of time counting (T0 in ) is the Unix epoch, and time is measured in UTC. This document defines no parameter to change it. period is NOT USED for hotp.

counter counter is REQUIRED for hotp. It is the initial counter value, the value the consumer uses to generate the first code. The value MUST be a decimal integer from 0 to 18446744073709551615 (2^64 - 1) inclusive. A consumer MUST reject an hotp URI if counter is missing or is not a decimal integer in this range. After provisioning, the consumer maintains and increments the counter. A URI carries only the initial value and does not track later state. counter is NOT USED for totp. These parameters map to HOTP and TOTP behavior defined in and , while allowing extension values where explicitly noted.

Additional Parameters Producers MAY include additional parameters that are not defined by this document. Consumers SHOULD ignore unrecognized parameters unless local policy requires rejecting them.

Issuer Label Prefix and Issuer Parameter In this document:

• The issuer label prefix (issuer-label) is presentation-oriented text for display.
• The issuer parameter (issuer) is the canonical identifier for account matching.

A producer MAY include an issuer label prefix for backward compatibility. A producer that includes both values SHOULD use a human-readable service name for the issuer label prefix and a stable matching identifier for the issuer parameter. If both issuer label prefix and issuer parameter are present:

• A consumer MUST NOT reject the URI only because the two values differ.
• A consumer SHOULD treat the issuer parameter as authoritative for account matching.
• A consumer MAY use issuer label prefix for display.

A consumer MUST continue to accept URIs where issuer label prefix and issuer parameter are equal, as this remains common in deployed systems .

Examples The following are valid otpauth: URIs (where PB4XU is the unpadded Base32 encoding of xyz):

Security Considerations This URI format does not in itself pose a security threat. However, the secret parameter carries a bearer credential. Disclosure of secret enables OTP generation and can lead to account compromise. Producers and consumers:

• SHOULD treat otpauth: URIs as sensitive secrets.
• SHOULD avoid writing full URIs to logs, analytics, and crash reports.
• SHOULD transport provisioning data only over authenticated and encrypted channels.

Consumers SHOULD display issuer and account information clearly before import so users can detect phishing or provisioning mistakes. For hotp, the counter in a URI is only the initial value. A consumer that imports a previously issued URI again after generating codes would reset its counter, which can repeat codes already used or put it out of step with the verifier. A consumer SHOULD NOT silently replace the counter of an existing credential with the value from a newly imported URI. For totp, a code is valid only if the consumer's clock and the verifier's clock agree closely enough. Clock synchronization is outside the scope of this document. Verifier behavior, such as HOTP counter resynchronization and TOTP acceptance windows, is also outside the scope of this document; see and .

Privacy Considerations otpauth: URIs may reveal account identifiers and service associations through label and issuer fields. Applications handling these URIs SHOULD minimize retention and SHOULD avoid sharing raw URI values across process boundaries unless necessary for explicit user action.

IANA Considerations The otpauth: URI scheme is registered as provisional in the IANA URI Schemes registry . Upon publication of this document as an RFC, IANA is requested to update the reference for the existing otpauth provisional registration to point to this RFC.

References Normative References A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] This document describes an algorithm to generate one-time password values, based on Hashed Message Authentication Code (HMAC). A security analysis of the algorithm is presented, and important parameters related to the secure deployment of the algorithm are discussed. The proposed algorithm can be used across a wide range of network applications ranging from remote Virtual Private Network (VPN) access, Wi-Fi network logon to transaction-oriented Web applications. This work is a joint effort by the OATH (Open AuTHentication) membership to specify an algorithm that can be freely distributed to the technical community. The authors believe that a common and shared algorithm will facilitate adoption of two-factor authentication on the Internet by enabling interoperability across commercial and open-source implementations. This memo provides information for the Internet community. This document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [STANDARDS-TRACK] Internet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK] This document describes an extension of the One-Time Password (OTP) algorithm, namely the HMAC-based One-Time Password (HOTP) algorithm, as defined in RFC 4226, to support the time-based moving factor. The HOTP algorithm specifies an event-based OTP algorithm, where the moving factor is an event counter. The present work bases the moving factor on a time value. A time-based variant of the OTP algorithm provides short-lived OTP values, which are desirable for enhanced security. The proposed algorithm can be used across a wide range of network applications, from remote Virtual Private Network (VPN) access and Wi-Fi network logon to transaction-oriented Web applications. The authors believe that a common and shared algorithm will facilitate adoption of two-factor authentication on the Internet by enabling interoperability across commercial and open-source implementations. This document is not an Internet Standards Track specification; it is published for informational purposes. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References Internet Assigned Numbers Authority Google independent This document specify the One-Time Password (OTP) Credential Provisioning otpauth URI format, utilized by TOTP (Time-Based One- Time Password Algorithm) and HOTP (An HMAC-Based One-Time Password Algorithm) based authenticators. Apple

Acknowledgments The author thanks the maintainers and implementers of authenticator applications and password managers, including the teams at Apple and Google whose documentation helped shape existing interoperable behavior. The author also thanks İlteriş Eroğlu, author of , for earlier work bringing the otpauth: URI scheme to the IETF.