SQRLSQRL
100x100 SQRL Logo   Secure Quick Reliable Login
A highly secure, comprehensive, easy-to-use replacement
for usernames, passwords, reminders, one-time-code
authenticators . . . and everything else.
divider
SQRL Link & Query Protocol
SYNTAX
This page details the format of the information exchange between the SQRL client and the remote web server. The “Protocol Semantics” page specifies and describes the meaning and behavior of individual options.
THIS PRELIMINARY SPECIFICATION IS IN FLUX
AND IS SUBJECT TO CHANGE AT ANY TIME
At this time it is being published for comment only. Please DO NOT RELY
upon it until this notice has been removed. (Which should be soon!)
SQRL: What we use, what we ignore
The full definition of an Internet URL (uniform resource locator) includes several less commonly used parameters:

scheme://username:password@hostname:port/path?query

Since the SQRL system is designed to always generate the same user identity when the user visits the same site, we need to be careful and explicit about which pieces of any possible URL we use for that generation. Consequently, any superfluous, variable, optional, and possibly confusing components are deliberately excluded from use:

scheme://username:password@hostname:port/path?query

The end result of pruning the SQRL link URL is the retention of the URL's scheme, which will be either ‘sqrl’ or ‘qrl’, the DNS domain name without any optional port specifier, and the balance of the URL's path and query terms:

scheme://hostname/path?query

Lowercase: Since the scheme and DNS domain name portions of a URL are not case-sensitive, those two components of any SQRL link URL are converted to lowercase before any processing is performed. The path and query parameters are left untouched.

No port? The deliberate exclusion of the “port” parameter from the domain-based key generation allows sites to freely move SQRL authentication services and/or web services to non-standard ports without breaking any existing SQRL identification. This eliminates the ability to have separate port-based identities for the same domain name, which seems like the preferred thing to do.
SQRL QR code/hyperlink URL format

SQRL URLs may be encoded into graphical QR codes to enable multifactor cross-device authentication, or embedded into standard HTML links to enable local, same-device SQRL authentication. To afford maximum server-side design freedom, the SQRL URL format has minimal requirements:

sqrl-url-scheme

sqrl-url-sample

sqrl-url-sample

sqrl-domain-extension
SQRL Authentication Query Format

In the odd and somewhat contrived “sending data from a web client back to a web server” operation of the web, a web client may use a “GET” query to send a web server data by asking the server for a standard web resource, where the data it wishes to send is appended to the end of the resource's name. This is the so-called “query tail”.

http-query-format

As shown in the diagram above, this simple “GET” query link format is used in the web server's SQRL link URL to append data to the URL: the server's “nut”, which is used to make every SQRL URL unique and unpredictable, and any other information the server may wish to include for the client or to have returned to itself.

POST Queries
A web client can also use a “POST” query to send additional data which might be too lengthy to fit into a URL, might be binary data, or otherwise unsuitable for a URL's environment. Since the SQRL client often returns a substantial amount of information to the web server (multiple keys and signatures, etc., see below), it uses the POST verb's natural division of data. The server's supplied SQRL link URL, as provided, is used for the POST verb's query, and the entire collection of SQRL arguments and signatures are provided in the body of the POST submission.

The URL's parameters are standard HTTP form-urlencoded parameters where name=value pairs are separated by ‘&’ characters:

The use of standardized HTTP POST query syntax allows existing web query parsing, interpretation tools and libraries to be used without modification.

How the SQRL query string is formed
A SQRL client will only interpret a URL link beginning with “sqrl://” or “qrl://” as a valid SQRL link. Anything else submitted through any channel (sent to the client by an operating system when then user clicks on a link, or optically scanned from a QR code) will present its user with a note that the link scanned or submitted was not recognized as a valid SQRL login link and no other link processing will be performed.

If the SQRL client receives a link that does begin with either of the two SQRL schemes:
How to form the POST verb's body
client={ base64url encoded name=value list }&
server={ base64url encoded name=value list }&
ids={ signature corresponding to idk }&
pids={ signature corresponding to pidk }&
urs={ signature to permit SQRL association updates }
In this example, the line-breaks are ONLY PRESENT for display clarity. The
actual SQRL POST body is a single long unbroken string. The “SQRL Web
Server Reply Format” section below has an example of the step-by-step
encoding and construction of SQRL's compound name=value format.
The content of the “client” parameter.

The client name=value pair conveys the bulk of the client's data to the web server. It contains everything the client wishes to provide to the server with the exception of the server's original URL or previous reply data (which are conveyed in the server value) and the variable number of signatures required to validate various parameters and requests being issued by the client.
The content of the “server” parameter.

The server parameter value is either the unmodified SQRL link URL, exactly as it was originally obtained by the SQRL client, then base64url encoded, -OR- the base64url encoded name=value pair list that was most recently received from the server. Either way, the resulting base64url ASCII string becomes the value of the server= parameter.

Forming signatures

The SQRL protocol uses signatures to prove its ownership of various secrets (typically private keys) without revealing what those secrets are. It does this by providing a signature's public key in the client parameter list and using the signature's matching private key to sign the concatenation of the client and the server values. The 512-bit binary signature is then converted into ASCII using base64url (and trailing equals signs removed) for transmission, and appended to the client's POST body in the series of ampersand separated name=value pairs.

The receiving web server, to verify the validity of various aspects of the SQRL client's request, verifies each attached signature in turn. It extracts each signature's matching pubic key from the client parameter list and uses it with the signature to verify that the SQRL client is authorized to perform the operations it is requesting. Since every attached signature should always verify correctly, any failed signature verification causes the entire SQRL query transaction to fail even if other signatures are valid for their operations. Unless every signature is valid no action is taken.

Concatenation:
As mentioned above, the client and server string values are signed as a single whole after they have been concatenated into a single string. They are concatenated in the same order as they appear in the client's POST body: client first and server second. So the server value is appended to the end of the client value. The resulting single string is then signed by every private key required to validate the requested server actions.

Base64url encoding:
Many base64url encoders append one or two “padding” equals signs to the end of the encoded string because they encode in blocks of 24-bits — converting each set of three input bytes into four output characters. But neither 256-bit keys nor 512-bit signatures are an even multiple of three bytes. So encoding these values will always cause one or two padding equals signs to be appended to the end of the encoded string. Since the signature's name=value expression contains an equals sign, we need to remove the trailing equals signs from the base64url encoding so that the receiving web server does not become confused. Note that the receiver will need to add one or two equals signs back to the end of the key or sig before decoding them back into their original binary values.

SQRL Web Server Reply Format

The web server's HTTP reply status (200 OK, 404 Not Found, etc.) does not encode the success or failure of the underlying SQRL authentication transaction. That information is carried within the body of the reply. Instead, the standard HTTP status is only used to indicate whether the query payload was properly received from the SQRL client and whether the HTTP object referred to in the SQRL query was found, valid, known, etc. in the standard HTTP sense.

An HTTP “200 OK” reply would indicate that the communication from the SQRL client appeared to succeed and that the web server's object referred to by the query was valid. An HTTP “404 Not Found” would indicated that, irrespective of the query's trailing URL parameters, the object referred to by the query was not found, invalid, illegal, etc.

Since SQRL link URLs are invoking a real-time service rather than a static web page, and since they are expected to be generated upon demand, the entire class of 3xx Redirection responses will be illegal for SQRL queries and will result in the SQRL client returning an error message to the user. It will not follow any redirection links provided by any such replies.

Returning information to the SQRL client

Assuming that the overall HTTP reply status was “200 OK”; In order to return SQRL protocol status, public keys, and other required information, the web server will return a base64url encoded list of name=value pairs, one per line, with each one, including the final one, terminated with a CRLF character pair.

Since this single base64url encoded string is the only data being returned by the server, there is no need to explicitly label it. Upon receipt, the client base64url decodes the string into the server's list of CRLF-separated name=value pairs.

SQRL's ASCII Encoding of Binary Data

SQRL's various key and signature values are generated as binary character arrays of 256 and 512 bits respectively. Although POST query and HTTP reply bodies can contain and carry binary data, the conversion of this binary information into a reduced ASCII character set for transmission allows SQRL to be used with other transports that may not be binary compatible, eases development verification, and encourages the use of standard data parsing libraries.

To perform this conversion, we employ a widely available variation of the standard base64 encoding known as “base64url” as defined in the Base Data Encodings RFC #4648. The “base64url” encoding replaces the URL-hostile ‘+’ and ‘/’ characters, which are typically used as the last two non-alphanumeric symbols in the encoding alphabet, with the URL-friendly characters ‘-’ and ‘_’ respectively. However . . .

Trailing “=” characters must be trimmed from
the end before the encoded strings are used.

Base64 encoding converts 8-bit bytes into a 6-bit character set. The least common multiple (LCM) of 8 and 6 is 24. Therefore, some base64 converters perform their conversions by taking multiples of three 8-bit binary source bytes (24-bits) to produce four 6-bit characters (24-bits). The trouble with this is that the source data length may not be an even multiple of 3 bytes (and none of ours are). Encoders resolve this (annoyingly) by appending one or two null (all zero) bytes to fill out the final “group of three” source bytes. Such converters also insist upon always emitting full sets of four encoded characters . . . even if doing so means that they must pad the output with “=” equals sign characters (since they have no real source data to go with those padding characters).

The “=” equals sign is NOT a URL-safe character because it is reserved to join URL parameter names and values. Therefore, the SQRL standard requires that any trailing “=” characters be trimmed and removed from the end of all base64url converted strings.

Our 256-bit, 32-byte SQRL keys will always end in one (“=”)
equals sign, and our 512-bit, 64-byte SQRL signatures will
end with two (“==”) equals signs. They must be removed.
The same care should be taken by the server with the encoding and subsequent decoding of its “nut” value included in the SQRL link URL.

Note that when the encoding process is reversed to decode and return the ASCII back to binary, some base64url decoders will expect to encounter the original equals sign(s). So, to be safe, the web server that decodes these strings should append one (“=”) equals sign to SQRL's key values and two (“==”) equals signs to SQRL's signature values.



Secure QR Login (SQRL) Documentation:

Jump to top of page
Gibson Research Corporation is owned and operated by Steve Gibson.  The contents
of this page are Copyright (c) 2016 Gibson Research Corporation. SpinRite, ShieldsUP,
NanoProbe, and any other indicated trademarks are registered trademarks of Gibson
Research Corporation, Laguna Hills, CA, USA. GRC's web and customer privacy policy.
Jump to top of page

Last Edit: Jun 30, 2017 at 15:38 (114.24 days ago)Viewed 5 times per day