independent

Ankara Turkey ietf@linuxgemini.space

Internet internet internet security otpauth totp hotp This document describes a foundational schema for the otpauth URI, utilized by TOTP (and/or HOTP) based authenticators.

Discussion This note is to be removed before publishing as an RFC. Source for this draft and an issue tracker can be found at https://github.com/linuxgemini/otpauth-spec-draft.

Introduction The otpauth URI is used for easy addition of accounts to TOTP (and/or HOTP) authenticators with various options . Although available as a provisional scheme at IANA , there are many divisions of the usage specification per authenticator hardware and software . This document aims to provide foundational boundaries for the URI format and standardize the secret sharing of OTP tokens.

Conventions and Terminology 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 of . This specification uses the terms "TOTP" defined by and "HOTP" defined by . Both RFCs also mention "secret", "issuer" and "account". The term "URI" is imported from . Mentions of "query string" in this document references the "Query" parameter (in section 3.4) of this RFC. The Base16, Base32, and Base64 Data Encodings mentioned here are imported from with the same name.

Syntax The URI MUST be formatted like below: otpauth://TYPE/LABEL?PARAMETERS An approximate ABNF representation of this is like below: otpauth-uri = "otpauth://" uri-type "/" uri-label "?" uri-parameters uri-type = "totp" / "hotp" uri-label = *VCHAR uri-parameters = "secret=" *base-32 [ *uri-opt-parameters ] uri-opt-parameters = ("&algorithm=" otp-algorithm) uri-opt-parameters =/ ("&digits=" otp-digits) uri-opt-parameters =/ ("&counter=" *DIGIT) / ("&period=" *DIGIT) uri-opt-parameters =/ ("&issuer=" *VCHAR) / ("&" *VCHAR "=" *VCHAR) ; Please refer to RFC3986 for handling ; complex names otp-algorithm = "SHA1" / "SHA256" / "SHA512" otp-digits = %x36-38 ; 6-8 base-32 = %x41-5A / %x32-37 ; A-Z2-7 DIGIT = %x30-39 ; 0-9 VCHAR = %x21-7E ; visible (printing) characters

TYPE entry (REQUIRED) The type entry MUST be one of totp or hotp, depending on the OTP type.

LABEL entry (REQUIRED) The label entry MUST be an identifier representing the user. For example, can be an username, nickname or a person's name. Although the Authenticator Team at Google recommends including the secret issuer to be prepended to the label with the colon character (: or %3A) as a seperator in , the authors of this document believe that the issuer should only be appended as a seperate parameter(see next division).

PARAMETERS entry (REQUIRED) This entry is an URI query string. Each parameter MUST be seperated by the & character and SHOULD BE "URI Safe" (see section 2.2. Reserved Characters in ). The following parameters SHOULD BE included:

secret parameter (REQUIRED) The secret of the OTP MUST be provided within this parameter. The secret MUST be encoded in Base32. The padding specified in section 2.2 is not required and SHOULD BE omitted. For example: otpauth://totp/ietfuser?secret=NBSWY3DPFQQHO33SNRSAU

algorithm parameter (OPTIONAL) The algorithm used for TOTP or HOTP tokens SHOULD BE provided in this parameter. When not provided, SHA1 is assumed by default. The ABNF representation is defined below: otp-algorithm = "SHA1" / "SHA256" / "SHA512" Some authenticators at the time writing of this document ignore this parameter, the authors of this document believes that this parameter MUST be supported in all cases.

digits parameter (OPTIONAL) The amount of digits to be outputted for TOTP or HOTP tokens SHOULD BE provided in this parameter. This value MUST be between 6 and 8. When not provided, 6 digits is assumed by default. Some authenticators at the time writing of this document ignore this parameter, the authors of this document believes that this parameter MUST be supported in all cases.

counter parameter (OPTIONAL, REQUIRED if HOTP) The provisioning counter for TOTP or HOTP tokens SHOULD BE provided in this parameter. This parameter is required if the token type is HOTP.

period parameter (OPTIONAL) The refresh period (in seconds) for TOTP or HOTP tokens SHOULD BE provided in this parameter. When not provided, 30 seconds is assumed by default. Some authenticators at the time writing of this document ignore this parameter, the authors of this document believes that this parameter MUST be supported in all cases.

issuer parameter (OPTIONAL) The issuer name of TOTP or HOTP tokens SHOULD BE provided in this parameter.

Other parameters (OPTIONAL) Vendors MAY include other parameters in their issued otpauth URIs. These parameters are OPTIONAL for the function of TOTP or HOTP tokens and not necessary to be included in this document.

Examples otpauth://totp/ietfuser?secret=NBSWY3DP otpauth://hotp/13tfus3r?secret=NBSWY3DP&counter=192 otpauth://totp/big?issuer=why&secret=NBSWY3DP&period=5&algorithm=SHA256

Security Considerations This URI format does not in itself pose a security threat. However, the Security Considerations of SHOULD BE followed.

IANA Considerations This format is already available as a provisional entry . IANA is asked to change the provisional URI scheme to reference [[this RFC]].

Normative References Informative References Google IANA

Acknowledgements We would like to thank Q Misell, Terrence Eden, The Google Authenticator Team at Google, and others (please let us know, if you've been mistakenly omitted) for their valuable input, feedback and general support of this work. This document originated from discussions at the Fediverse initially written by Terrence Eden .

Document History [[ To be removed from the final specification ]] -00

• first draft