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.
SQRL Link & Query Protocol
This page specifies the parameters, and their meaning, used to facilitate SQRL client and web server interactions. The “Protocol Syntax” page specifies the detailed transmission format of this interchange.
SQRL Client/Server Interaction Notes
The client always provides any signatures required to authenticate any private key knowledge assertions it is making. Since it is always, at a minimum, asserting the user's identity, all of the information contained within the client's query will always carry at least one verifiable signature. If any of the client's key signatures fail to validate, the server returns “client failure” and “command failed” errors and does nothing else. (See below for details.)

Also, since the SQRL system is based upon an asymmetric authenticated-client model employing one-way signatures, where only the client signs its queries, the server's data is protected by having the client always return and sign everything received from the server and having the server verify that what it received back from the client is identical to what it sent. One consequence of this, as we'll see, is that the server often provides some material to the client before it is required so that it may be retained by the client for possible later use, and meanwhile returned to the server for verification (of no tampering) under the client's signature.

SQRL Authentication Initiation


Server →
→ Client
SQRL authentication is initiated when a SQRL client receives a SQRL URL that was previously (and usually recently) generated by a SQRL-aware web server. This URL might be received by the client optically as a QR code, or provided to the SQRL client by the operating system. Through this mechanism:

The SERVER provides a unique, opaque session-identifying
token and the server's “friendly name”:

The Server provides the Client with a unique URL containing a cryptographically strong opaque token and a short “friendly name” (such as “Amazon” or “GRC”) by which the user knows the authenticating website.

One way or another, the subsequent return of the token must allow the server to determine the IP address (or a hash of the IP address in the case of IPv6 IPs) which originally requested the login page (to which a pending login session would be associated). It should also include a timestamp to detect the URL's age, and randomizing information to guarantee the nut's uniqueness and unpredictability. For further discussion of the composition of the server's “nut” see the Web Server Behavior page.

The “friendly name” allows the client to immediately present the name of the authenticating site to the user as a mitigation against server/site spoofing attacks. The user should only proceed if they are authenticating to the site they expect.

The SQRL client, having received a unique token from the server through the SQRL link URL, initiates its first interaction with the web server. This identifies its user and allows it to obtain the user's stored data and web server features:

Initial Client/Server Interchange

Client →
 → Server
The CLIENT returns the token & asserts its user's identity:
Upon receiving the SQRL link URL—either through a same-device operating system hand off or a cross-device optical QR code scan—The client initiates an HTTPS connection to the indicated IP and port, and issues a POST query of the provided URL. The POST body issues the query command (cmd=query) and provides the user's current IDentity Key (cIDK) and current IDentity Signature (cIDS). Also, if the user's SQRL identity is also carrying one or more previous identities, the most recent previous IDentity Key (pIDK) and previous IDentity Signature (pIDS) will also be included.
Server →
→ Client
The SERVER returns the user's account information and status:
  1. The Transaction Information Flags (TIF), which is binary encoded to indicate whether or not the user is known by their current ID, previous ID, or neither, whether or not the client's query IP matches the IP of the original login session-requesting page, whether or not SQRL authentication is enabled, and whether or not the identified user is logged into the server.
  2. The query path & data to be used for the client's subsequent query.
  3. A “nut” value used for session linking and replay attack prevention.
  4. Optional and/or command-specific data — see details below.)

Repeated Client/Server Interchanges

The initial query command might be followed by additional query or non-query commands, as needed. Since each server reply provides a query path for a subsequent query, and a unique nut value to guarantee uniqueness for the client's signing of its query, this supports a chain of client queries and server replies, as needed and driven by the SQRL client.

For example, if a user's SQRL identity is carrying more than one previous identity key (identities may carry up to four previous identity keys) and the server indicates that it does not recognize the user by either their current or their most recent identity keys, the SQRL client should re-issue a query using the current and next most recent identity key to see whether the server may recognize the user by that older previous identity key. And this re-querying should continue until all available previous identities have been tried.

The initial client/server query command interaction(s) can be viewed as the client identifying itself (perhaps more than once) for the purpose of querying the website's SQRL database to obtain its user's relevant status, plus information required for the SQRL client to navigate additional interactions:

Login NEVER occurs without affirmative confirmation from the user. So this first data gathering interaction always results in a display explaining what has been learned, and requires some action by the user.

The top of every action-requiring dialog will display the website's “friendly display name” such as “Amazon”, “Yahoo”, “Google”, etc. If an attacker were to somehow intercept and change the website's simple display name in the web server's reply, this change would be detected with the user's next query, so no damage could be done.

Client & User Interaction

The SQRL system design methodology locates most of the heavy lifting complexity in the SQRL client. This fits the inherent many-to-one relationship with “many” website implementations being used by relatively fewer SQRL clients. We minimize website complexity where possible.

The SQRL client “knows” whether it's performing a same- or cross-device login. It knows whether it is has been loaded with a new master identity key and/or a new identity unlock key and may thus be in the process of retiring the previous identity or unlock key(s), enabling or entirely deleting a disabled identity. From the server it knows whether the server has identified the user by either the current or a previous key (if any), or neither, and it's able to determine whether the current or a previous identity unlock key is required. In other words, it's able to determine whether any key changes are possible (if previous keys are loaded) and whether the server is already using the current key(s) or still aware of a previous key.

The client gathers everything it knows, coupled with the results of the server's reply, which provides everything the server knows, then prompts its user for any additional required information or options to proceed based upon the specific circumstances:

The following cases are not intended to be a complete reference sample. They are meant to give a sense for the system's operation and user experience. Please reference the behavior of GRC's client and server for an operational example.

Unexpected IP address mismatch and the client has not been overridden to prevent alerting its user in this situation.
Some SQRL clients, such as GRC's Windows' client, would never expect to see the SQRL server report an IP mismatch between the IP embedded in the SQRL QR code and the client's connection IP. So such a mismatch should, and would, prevent any further authentication. But a mobile device's client would expect to encounter an IP mismatch if it was performing an optical QR code cross-device authentication and connecting with the SQRL server over its cellular connection. For this reason, SQRL servers simply report the IP match or mismatch and individual clients determine whether it should be a showstopper based upon the details of the authentication.
The client will explain the specific situation with its user. The user will be advised to carefully reexamine their web browser's URL and to possibly restart their login by manually reentering the site's domain name in the web browser they're logging in to.

The user is unknown to the server.
(Neither the user's provided identity key, nor any of the up-to-four previous identity keys, if present, are known to the web server.)
As GRC's SQRL demo demonstrates, the server will reply that the user is unknown to the user and will offer to create a new account. If the user already has an account they would decline the creation of a new account and instead login without SQRL then associate their existing account with SQRL. The lesson here is that SQRL is simply the identity authenticating agency. All account creation, association, and whatever other housekeeping should be performed on the server side.

The user was identified by their previous ID key (pIDK).
The user is migrating between identities, and this site still has one of the old (previous) identities. Since the SQRL client carries up to four previous identity unlock keys (pIUK) it is able to successively “query” the server with the user's current identity and one of its previous identities, in turn, until the proper pervious identity matches the one the server has. At that point, since both the correct previous and the new current identity will be available, the server will automatically and silently update the user's identity records.

The user was identified by their current ID key (IDK)
This is the most common operating circumstance. The website's provided “Server Friendly Name” (SFN) will be shown to the user for verification when the user authenticates themselves to their SQRL client. Then the web page will be updated to display their logged-in status.

The user wishes to disable their SQRL authentication rights for a site.
A user who fears that their SQRL identity may have become compromised, can unilaterally rescind their own SQRL authentication rights as long as they are known to the site. The dialog that acknowledges that the user has been identified will contain an “Other Actions” button to take the user to a dialog allowing them to unilaterally rescind their SQRL identity's own authentication rights.

The user is identified, but their SQRL authentication is currently disabled.
In this instance the SQRL client notifies its user that SQRL authentication for this website was previously disabled. Since SQRL clients are permitted to carry the user's identity unlock key (IUK) in RAM while exercising extreme precautions and continually reprompting the user about whether they are finished with it so that it can be removed from memory, if the IUK is current available in RAM the client will simply verify that the user does wish to reenable their SQRL access to this website. If the user's decrypted IUK is not currently being held in RAM, the client will prompt them to supply their identity's RescueCode (in order to decrypt their IUK for use) if they wish to reenable SQRL authentication for this website and proceed.

The user has rekeyed their identity and wishes to update websites with knowledge of their new keying.
SQRL website server identity key updating is autonomous and transparent to the user. It occurs automatically as a result of one or more the client's initial 'query' commands. Therefore, users merely need to encounter the site and cause the local password authentication dialog to be presented in order to have the site updates with their current identity keying.

A user wishes to permanently delete all SQRL identity association from a site.
A user may permanently remove their SQRL identity association from a site when their identity unlock key (IUK) is loaded into the client and accepted by the site. If their IUK is not currently loaded the user will be prompted for their identity's RescueCode.

No examples were provided showing the power created by the website's ability to present any acknowledgement, informative, or questioning dialog to its user through the SQRL interface. The site can label buttons and request user verification of important actions in order to obtain additional verification of the user's intentions.

Client -to- Server Semantics

Sending back what the server sent to the client:
All client queries to the web server echo back to the server, under the client's signature(s), either the original SQRL link URL, or the previous reply data that was most recently received by the client. This allows the web server to verify that the client “saw” the same data that the server sent, thus detecting any possible in-flight round-trip tampering.

The value of the client's “server=” name=value pair, contains this data, exactly as received from the server.

The “client=” value:
The query's “client=” parameter contains a base64url encoded list of name=value pairs, one per line, with each line terminated by a CRLF character pair. The client assembles a list of the following name=value pairs to return data to the web server, to specify one or more command actions it is requesting from the server, and to provide any cryptographic keying material required to authorize the requested actions and/or authenticate its user's identity:

Server -to- Client Semantics

A remote web server provides data to a SQRL client through two different channels: Initially encoded in the SQRL URL which provides the required “nut=” and “sfn=”, and an optional “x=” domain extension specifier.

The second channel for web server data is in the HTTP response bodies of SQRL client queries. Any of the parameters shown may be used, as required, in the server's replies to client queries.

Parameters are named with a simple name=value syntax. When appearing in a URL query tale, the name=value pairs must be URL-safe and ampersand-separated following standard HTTP GET query syntax. When returned by a web server in response to a client's query, the name=value pairs occupy the body of the reply, appearing one per line with each pair (including the last one) terminated by a CRLF character pair. To enhance the clarity of the descriptions below, the equals signs have been set off with spaces, but spaces are never used in the SQRL protocol:

Changes & Updates

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 28, 2017 at 13:54 (0.08 days ago)Viewed 10 times per day