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. 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.

Server → to → 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:

Client → to  → 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 → to → Client		The SERVER returns the user's account information and status: 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. The query path & data to be used for the client's subsequent query. A “nut” value used for session linking and replay attack prevention. Optional and/or command-specific data — see details below.)

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:

• The Transaction Information Flags (TIF) details whether and how the user is known to the server (by current ID, previous ID or which previous ID, if any, or neither), whether the client's query IP matches the IP of the original page request, whether the user's SQRL login privilege is enabled or disabled.
• A pending session URL link may be provided to the client in this initial exchange so that it will be returned and signed to detect any third-party tampering. The client retains the link for possible use once login is complete.
• If the client might need to provide the server with an Unlock Request Signature (URS) to reenable or delete a disabled account or to update the server from a previous user identity key to the current identity key, the server will return the Server Unlock Key (SUK). This will allow the client's next query to provide the additional signature required.
• A query path for any possible subsequent query. The query path & data is not the entire URL for the client's next query, but only the path beginning at the root ‘/’. The IP and port will remain unchanged from those obtained in the initial SQRL link URL. This allows the web server to embed whatever state it may wish to in another nut, and to also maintain state with the URL path itself. Any subsequent query(s) made by the client will be of this path and data. Once set, the client will issue all queries to this location and any server reply can update this path and data for subsequent queries.

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.

SQRL clients never expose their users' single master key. And in the normal course of events there will never be any need for a user's single master key to be changed. But life following a “normal course of events” is not something we can guarantee. So the SQRL system incorporates a built-in facility for allowing its users to securely rekey their identities.

As detailed in the description of SQRL's Secure Storage System, a user's SQRL client retains up to four previous identity keys which it carries at all times. Whenever a SQRL client negotiates its user's identity with a server which still recognizes this user by one of its previous identity keys, the server will be silently updated to recognize the user by their current identity key. Since rekeying an identity will normally be an emergency measure only, and is never expected during the normal course of SQRL's use, this “identity ratchet” automatically and transparently keeps websites synchronized to the their SQRL users' curent identities.

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:

Initiating a chain of client queries:
A SQRL identity assertion and authentication interchange requires one or more client queries. It is typically initiated when the SQRL client presents its user with the web domain requesting the user's identity and challenges its user to prove their identity to the client through a passphrase, passhint, biometric, or other verification. The details of the client and server interaction is detailed below.

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.

• If the client is issuing its initial query from the original SQRL link URL, the complete URL from the “sqrl://” to its end is base64url encoded to render it URL-safe.
• If the client is issuing a succeeding query after the initial one, it will have previously received the web server's reply in the form of a base64url-encoded list of name=value pairs, one per line. The client, therefore, does not need to base64url encode the server's previous reply. It simply returns exactly what it received to the server as the value of the “server=” parameter. The client's returning of the exact payload received, allows the web server to store a cryptographic hash of the payload it last sent and, after base64url decoding the value of the “server=” parameter, verify that the entire payload received and returned by the client was not tampered with in any way. This way the server does not need to take the returned payload apart and verify each piece individually. Any verification fault will immediately fail the entire transaction. The web server will reply with the “Command failed” and “SQRL failure” set in the “tif” value.

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:

• ver = 1
  As with the server's supported version set declaration, the client MUST declare the set of protocol versions it understands, supports, and is willing to use. Moreover, the version specification MUST be the first name=value pair appearing in the client's argument list. The protocol version specification consists of an unordered comma-separated list of one or more whole integer version numbers (1, 2, 3, ...) and/or version ranges. The server and client both declare their supported version sets and use the highest version available from the overlap of their sets.
• cmd = { one of the tokens below }
  The value of the “cmd” parameter specifies the action the client is requesting from the web server. It consists of one of the following tokens:

  query		All SQRL transactions must begin with one or more 'query' queries. 'Query' queries allow the SQRL client to determine whether and how its user is known to the SQRL server, whether SQRL's use is currently enabled for the site, and whether the user's query IP matches the IP which was associated with the original SQRL URL.(See the TIF flag bits below for more detail.) SQRL queries can only provide, at most, identity assertions for the user's current and one previous identity. If more than one previous identity key is known to the client (GRC's reference client retains up to four and this should be a minimum) then successive query queries are used iteratively, most recent previous identity to oldest, to determine which, if any, of the identity keys carried by the client are known to the server.
  ident		An ident query will usually follow one or more query queries. Whereas the query queries allow the client to obtain information from the server, the ident query requests the web server to accept the user's identity assertion as it is provided by this signed query. When a SQRL client is being used to authenticate to a website there is usually no user-interface action from the client after a successful ident transaction. The client's dialogs will close and the website will update to show that the user has been authenticated.
  disable		A disable query instructs the web server to immediately disable the SQRL system's authentication privilege for this domain. This might be requested if the user had reason to believe that their current SQRL identity key had been compromised. It is primarily intended to be used as a short-term emergency stop-gap measure to protect important accounts until a new identity key can be created and set into the server. The disable and enable operations are not symmetrical: An identified user may request to have their authentication disabled, but subsequently re-enabling authentication requires the identity's privileged unlock (RescueCode) credentials, which no attacker could obtain from the client because identity unlock credentials are never stored in the client.
  enable		An enable query is the reverse of the ‘disable’ query. It re-enables SQRL system identity authentication for the user's account. Unlike ‘disable’, however, ‘enable’ requires the additional authorization provided by the account's current unlock request signature (urs). The server will always return the user's stored server unlock key (suk) whenever it is replying to a disabled account (TIF bit 0x08) so that the client will be able to generate the unlock request signature (urs) to authorize this privileged operation.
  remove		This remove query instructs the web server to immediately remove all trace of this SQRL identity from the server. For example, this process would allow an account to be disassociated from one SQRL identity and subsequently reassociated with another. This differs from the user's identity being rekeyed, since “remove” allows a change to an unassociated identity. As with the enable command above, it must be authorized by the inclusion of the user's SQRL identity's unlock request signature (urs). In order to induce the server to provide the suk, the client must first disable the account in a separate operation, then use the provided suk to generate the urs signature. Since the associated account might not have an alternative (non-SQRL) method of subsequently authenticating a user (e.g. no other login means) the web server should leave the current account logged-in so that a replacement SQRL identity can be associated, and it should also advise the user of the need to immediately add a new SQRL identity if they wish to retain access to their account.

• opt = option1[~option2[~option3]...]
  The value of the “opt” parameter provides an unordered list of transaction options which the client asserts to the web server with each query. Individual options, as detailed below, may have an advisory or an explicit behavior-modifying role, which may also depend upon the command being issued by the client.
  
  The value of the “opt” parameter consists of one or more tilde-separated assertions:

  noiptest		By default, SQRL servers fail any incoming SQRL query whose IP does not match the IP encoded into the query's nut. This detects and prevents one of the easiest to exploit attacks on SQRL. However, some cross-device uses of SQRL, where the SQRL client is expected to have a different IP than the nut, such as with a mobile client using cellular bandwidth, will need to override and disable this default server same-IP verification. The presence of this 'noiptest' option instructs the server to ignore any IP mismatch and to proceed to process the client's query even if the IPs do not match. If the 'noiptest' option is not present and the IPs do not match, the server will reply with a TIF value of exactly 0x40 to indicate that the command failed. The 0x04 "IPs matched" bit will also be off, as is appropriate, but no other TIF bits have meaning in this case. If the 'noiptest' option is present, the server will be instructed to proceed with the client's query, and the 0x04 "IPs matched" TIF bit will reflect whether the IPs did or did not match.
  sqrlonly		When present, this option requests the web server to set a flag on this user's account to disable any alternative non-SQRL authentication capability, such as weaker traditional username and password authentication. Server support for this feature is optional but strongly encouraged. A server which supports this option must retain a memory of the most recent presence (or non-presence) of this option as presented during the most recent successful non-“query” command query. Users who have become confident of their use of SQRL may ask their client to include this optional request. The web server should only assume this intention if the option is present in any successful non-query transaction. Its absence from any successful non-query transaction should immediately reset the flag and the prohibition in the web server. The web server may, at its option, notice when any change has occurred and explicitly ask the user to affirm their changed intention. Additionally, since the 'sqrlonly' and 'hardlock' protections only make sense when a SQRL identity is present, SQRL clients should never send options these with the 'remove' [identity] command. SQRL servers should also ignore any residual effects of those options after a user's account has had SQRL removed.
  hardlock		When present, this option requests the web server to set a flag on this user's account to disable any alternative “out of band” change to this user's SQRL identity, such as traditional and weak “what as your favorite pet's name” non-SQRL identity authentication. Server support for this feature is optional but strongly encouraged. A server which supports this option must retain a memory of the most recent presence (or non-presence) of this option as presented during the most recent successful non-“query” command query. Users who have become confident of their use of SQRL may ask their client to include this optional request. The web server should only assume this intention if the option is present in any successful non-query transaction. Its absence from any successful non-query transaction should immediately reset the flag and the prohibition in the web server. The web server may, at its option, notice when any change has occurred and explicitly ask the user to affirm their changed intention. Additionally, since the 'sqrlonly' and 'hardlock' protections only make sense when a SQRL identity is present, SQRL clients should never send options these with the 'remove' [identity] command. SQRL servers should also ignore any residual effects of those options after a user's account has had SQRL removed.
  cps		“cps” is the abbreviation for Client Provided Session. The presence of this flag informs the server that the client has established a secure and private means of returning a server-supplied logged-in session URL to the web browser after successful authentication. When the 'cps' option is provided by the client to a successful “ident” query, and the server supports cps-mode login, the server will return a 'url=' parameter which the SQRL client then forwards to the web browser. When the server returns the 'url=' parameter to the client, thus confirming its support for 'cps', it must also completely abandon the pending login of the browser session associated with the SQRL query. The use and enforcement of this 'cps' process is strongly encouraged for all SQRL servers because it robustly thwarts website spoofing, man-in-the-middle attacks, and abuse of SQRL authentication by returning the authenticated URL directly to the user's browser via the SQRL client. In the non-cps case, where this flag is NOT present or (even if present) the server does not support cps-mode login, the web server will instead arrange to refresh the web browser's page or redirect the web browser to an authenticated (typically, logged-on) page. As noted above, when the client indicates that cps-mode is available, the server is strongly encouraged to abandon the pending web session and instead provide the authenticated page URL in a “url={url}” response parameter for the “ident” command query.
  suk		“suk” is the abbreviation for Server Unlock Key. The presence of this flag instructs the SQRL server to return the stored server unlock key (SUK) associated with whichever identity matches the identity supplied by the SQRL client. The SQRL specification requires the SQRL server to automatically return the account's matching SUK whenever it is able to anticipate that the client is likely to require it, such as when the server contains a previous identity key, or when the account is disabled. However, there are instances where the client may know that it is going to need the stored SUK from the server, such as when it wishes to remove a non-disabled account. The client could first disable the account to induce the server to return the SUK, but it's simpler for the client to request the SUK from the server whenever it wants it. It's also conceivable that future extensions of this specification will incorporate other instances where the server's stored SUK is required for RescueCode based authentication.

• btn = ‘0’, ‘1’ or ‘2’ ‑ submit trigger from an “ask” prompt
  The client must include a “btn=” parameter in any server query generated by a reply to the server's ask prompting (“ask” is described below). The text value of the “btn=” parameter will be the character ‘0’, ‘1’ or ‘2’ if the dialog's “OK” or the first or second optional buttons, respectively, were used to submit the ask query.
Keys
• idk = IDentity Key
  This is the user's SQRL ID which uniquely identifies them to the site. It is the elliptic curve public key derived from the user's master key (mk) after it has been processed with the site's “site key string” sks, which is the extended domain name used for keying the site's ID. The binary key is base64url encoded with trailing equals sign padding removed.
• pidk = Previous IDentity Key
  When a user has rekeyed their identity, thus changed their master key, but wishes to update a website's SQRL association with the new key, their SQRL client will be using the new key as its idk, but websites which have not yet been updated will only recognize the user by their previous idk. So SQRL identities retain up to four previous identity unlock keys (piuk) so that the server may synthesize both this pidk along with the unlock request signature (urs) to allow websites to replace their obsolete SQRL identity key data with the new data. During one or more query queries, the client will present the server with the user's current idk and each previous identity key (pidk)and its matching previous identity signature (pids), in turn, from most recent to least recent. In this way the SQRL client searches for any previous identity the server may have.
• suk = Server Unlock Key
  This suk key is included in every client 'ident' query when the immediately previous server reply did not have the 0x01 bit of its tif flags set. The lack of tif bit 0x01 indicates that the server does not recognize the client by its current identity key and signature. The server might not recognize the client's identity at all (neither tif 0x01 or 0x02 bits are set) or it might recognize the client by its previous identity (tif bit 0x02 set). In either case the client must assert its current identity by providing the server with both this suk and a corresponding vuk (see below). As described on the Identity Lock Protocol page, the server unlock key is a DHKA (Diffie-Hellman Key Agreement) public key generated by the client and then stored by the server and returned to the client with every reply.
• vuk = Verify Unlock Key
  This vuk key is generated with and always accompanies the suk key described above. As described on the Identity Lock Protocol page, the verify unlock key is a DHKA (Diffie-Hellman Key Agreement) public key generated by the client, stored by the server, and used by the web server to verify the unlock request signature (urs) provided by the client whenever it wishes to authorize any operation requiring the identity's RescueCode.
Client Secrets
• ins = INdex Secret
  When the immediately previous server reply contained a Secret Index (sin=value) name & value parameter, the output of the user's identity key forming HMAC256 is passed through the EnHash function and used to key to a secondary HMAC256 which is used to hash the server's provided sin literal value without modification. The secondary HMAC's 256-bit output is base64url encoded and returned to the server as the value for this ins parameter.
• pins = Previous INdex Secret
  Whenever the ins parameter, above, is being returned to the server, and if the user's identity also contains at least one previous identity key (pidk) that previous identity key is used, as above, to also produce and include the matching pins parameter and value. When more than one previous identity key exists, and while the server continues indicating that it does not identity the user by either of the two presented identity keys, the client will successively iterate through each of the previous identity keys, producing synchronized pidk and pins name=value parameters.
Client Signatures

All client queries sent to the web server are signed using private keys matching one or more of the public keys included in the “client=” name=value list. The data to be signed are the two base64url encoded values of the “client=” and “server=” parameters with the “server=” value concatenated to the end of the “client=” value. Each of the signatures below, generated as a binary token, must also be base64url encoded before being appended to their respective “name=” parameter.

• ids = IDentity Signature
  This is the signature used to authenticate the contents of the query block sent to the web server. The SQRL client synthesizes the site-specific private key, uses that to sign the concatenated values of the previously mentioned client and server parameters, sends the resulting signature to the web server as the value of this ids parameter. The web server verifies the signature using the accompanying idk, which must also match the value stored in the user's SQRL account association.
• pids = Previous IDentity Signature
  As with the pidk (previous identity key), one or more of these are sent (in successive queries if more than one) to the web server when a SQRL client has rekeyed its identity and thus changed its Identity Unlock Key (iuk). The client retains up to four Previous Identity unlock keys (piuk) to enable it to generate the pidk and pids values. These will both be necessary for the web server to identify and authenticate a user by one of their previous, not-yet-updated, identities.
• urs = Unlock Request Signature
  The unlock request signature provides proof to the web server that the SQRL client is in possession of the identity unlock key (iuk) for which the server provided its stored server unlock key (suk). This urs signature must be provided in three instances: When the client's identity has been rekeyed so that the server's stored identity can be updated, and when the client is requesting to either enable a currently disabled account or remove the SQRL authentication information entirely.
  
  If the SQRL client does not currently have the decrypted Identity Unlock Key available it will not, and cannot, supply the matching urs value and it may prompt the user to provide the identity's secret RescueCode if needed. As noted above, SQRL's more security-critical (and uncommon) operations are protected by this additional signing requirement. The web server supplies its stored server unlock key (suk) with any replies that might require the SQRL client to provide a urs signature. This enables the client to generate an unlock request signature (urs) of the client and server data being sent to the web server with its next query. The web server uses its stored verify unlock key (vuk) to verify the client's signature. The use of the enable or remove command verbs to re-enable or remove a disabled identity, or the replacement of a previous identity key with the current identity key, must be accompanied by a valid unlock request signature.

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:

Web server's parameters sent to the SQRL client
• ver = 1[,n],[n-m]
  The server MUST indicate the set of protocol versions it understands, supports, and is willing to use. Moreover, the version specification MUST be the first name=value pair appearing in the server's argument list. The protocol version specification consists of an unordered comma-separated list of one or more version numbers and/or version ranges. The server and client both declare their supported version sets and use the highest version available from the overlap of their sets.
• nut = base64url encoded opaque token
  The server's “nut” value is discussed extensively elsewhere. It is a never-repeating opaque cryptographically strong nonce which may, at the server's discretion, contain reversibly encrypted data used to associate and maintain state. It MUST be included with every response to guarantee uniqueness and prevent reuse/replay. As with all of SQRL's use of base64 encoding, any trailing equals signs used for padding must be removed.
• tif = hexadecimal integer
  The Transaction Information Flags (TIF) is a single hexadecimal encoded integer which MUST be included in every server response. It is generated by the web server to convey a wide variety of user identity and connection status information in an easily generated and interpreted form. The individual bits are shown using the familiar “0x” hex prefix, but the TIF's value does not need or use the “0x” prefix. The individual bits have the following values and meanings:

  0x01		(Current) ID match: When set, this bit indicates that the web server has found an identity association for the user based upon the default (current) identity credentials supplied by the client: the IDentity Key (idk) and the IDentity Signature (ids).
  0x02		Previous ID match: When set, this bit indicates that the web server has found an identity association for the user based upon the previous identity credentials supplied by the client in the previous IDentity Key (pidk) and the previous IDentity Signature (pids). Note: When neither of the ID match bits are set, none of the identity credentials supplied by the client are known to the web server.
  0x04		IPs matched: When set, this bit indicates that the IP address of the entity which requested the initial logon web page containing the SQRL link URL (and probably encoded into the SQRL link URL's “nut”) is the same IP address from which the SQRL client's query was received for this reply. Note that the server must retain the IP embedded in, or associated with, the original SQRL URL, not any subsequent query, and compare the current query IP against that original IP.
  0x08		SQRL disabled: When set, this bit indicates that SQRL authentication for this identity has previously been disabled. While this bit is set, the “ident” command and any attempt at authentication will fail. This bit can only be reset, and the identity re-enabled for authentication, by the client issuing an “enable” command signed by the unlock request signature (urs) for the identity known to the server. Since this signature requires the presence of the identity's RescueCode, only SQRL's strongest identity authentication is permitted to re-enable a disabled identity.
  0x10		Function(s) not supported: This bit indicates that the client requested one or more SQRL functions (through command verbs) that the server does not currently support. The client will likely need to advise its user that whatever they were trying to do is not possible at the target website. The SQRL server will fail this query, thus also setting the “40h” Command Failed bit.
  0x20		Transient error: The server replies with this bit set to indicate that the client's signature(s) are correct, but something about the client's query prevented the command from completing. This is the server's way of instructing the client to retry and reissue the immediately previous command using the fresh ‘nut=’ crypto material and ‘qry=’ url the server will have also just returned in its reply. Although we don't want to overly restrict the specification of this error, the trouble is almost certainly static, expired, or previously used nut= or qry= data. Thus, reissuing the previous command under the newly supplied server parameters would be expected to succeed. The “0x40” “Command failed” bit (shown next) will also be set since the client's command will not have been processed.
  0x40		Command failed: When set, this bit indicates that the web server has encountered a problem fully processing the client's query. In any such case, no change will be made to the user's account status. All SQRL server-side actions are atomic. This means that either everything succeeds or nothing is changed. This is important since clients can request multiple updates and changes at once. If this bit is set without the 80h bit set (see below) the trouble was not with the client's provided data, protocol, etc. but with some other aspect of completing the client's request. With the exception of the following “Client failure” status bit, the SQRL semantics do not attempt to enumerate every conceivable web server failure reason. The web server is free to use its “ask” feature to explain the problem to the client's user. If this bit is set with both of the ID match bits (0x01 & 0x02) reset, the trouble may be that none of the identities provided to the server are known to it. So the SQRL client should first retry the command, successively offering every previous identity that it might have before giving up. Furthermore, to prevent probing of a user's account status, other than the ID match bits, none of the other TIF bits other than the 0x80 Client failure bit should be considered valid when the 0x40 Command failed bit is returned.
  0x80		Client failure: This bit is set by the server when some aspect of the client's submitted query ‑ other than expired but otherwise valid transaction state information ‑ was incorrect and prevented the server from understanding and/or completing the requested action. This could be the result of a communications error, a mistake in the client's SQRL protocol, a signature that doesn't verify, or required signatures for the requested actions which are not present. And more specifically, this is NOT an error that the server knows would likely be fixed by having the client silently reissue it previous command using updated entropy . . . although that might still be the first recourse for the client. Since any such client failure will also result in a failure of the command, the 40h bit will also be set.
  0x100		Bad ID Association: This bit is set by the server when a SQRL identity which may be associated with the query nut does not match the SQRL ID used to submit the query. If the server is maintaining session state, such as a logged on session, it may generate SQRL query nuts associated with that logged-on session's SQRL identity. If it then receives a SQRL query using that nut, but issued with a different SQRL identity, it should fail the command (setting both the 0x40 and 0x80 bits) and also return this 0x100 error bit so that the client may inform its user that the wrong SQRL identity was used with a nut that was already associated with a different identity.

  Note that the number of characters in the “tif=” value may change depending upon the number of characters required to represent the most significant “set” bit flag within the value. Also, additional bit flags defined in future versions of the protocol could be expected to expand the value beyond the nine bits defined for this first version 1 release. Therefore, neither the client nor the server should make any restrictive assumptions about the length of the “tif's” value.
  
  Also note that all SQRL clients MUST immediately terminate any connection and abort any authentication operation with any SQRL server which includes TIF bits not defined above. Protocol extensions within SQRL v1.0 are fully supported with additional name=value pairs in the query and response payload. But TIF bits must not be used for such purpose.
• qry = /query-path
  The SQRL client initially makes contact with the remote web server by issuing the query contained in the SQRL link URL. But subsequent interactions will almost certainly be made to different web server objects. The “qry” parameter is required in every reply. It instructs the client what server object to query in its next (if any) query. To mitigate the potential for tampering, this qry parameter only supplies the full path from the root ( / ) and the object, not the scheme, domain name, or port. The scheme, domain and optional port override may only be specified once, in the initial URL, and they cannot subsequently be changed.
• url = successful authentication browser redirection URL
  This value must be provided by the server in its response to any command other than “query” when the SQRL client's query includes the “opt=cps” (client provided session) parameter. The presence of “cps” indicates that the server must not authenticate the current web browser session but must, instead, use the value of this parameter to provide the client with a web page showing the result of the authentication. This URL will be the value provided by the Location: header returned in an HTTP 302 Found reply to the waiting web browser.
• sin = secret index
  The server may include this optional parameter to request a named (“indexed”) identity-based, high-entropy, 256-bit “indexed secret” from the client. When this sin name & value are sent to the client, the immediately following client query, regardless of type (query, ident, etc.) will include the indexed secret (ins) named & value and possibly also a previous-identity indexed secret (pins) This sin parameter is called the secret index because this value is hashed as a literal through the client's identity-keyed secondary HMAC256. In this way, servers may obtain any number of “named” (indexed) unique high-entropy secret values from the client each which is uniquely based upon the user's current (and possible previous) SQRL identity.
• suk = server unlock key
  As described on the Identity Lock Protocol page, the suk value is originally generated and provided to the server by the SQRL client whenever the client is creating a new identity association or modifying an existing association. The server retains this value as part of the client's identity and returns it to the client whenever it might be required by the client. Specifically, when the server identifies the user's previous identity ‑ so that the client may update the server to the user's current identity ‑ and also whenever the user's account is disabled ‑ so that the client may have the option of either re-enabling the user's account or completely removing the user's identity. In these cases, the server's provision of the stored suk value allows the client to then provide the identity unlock signature to either update the server's stored identity, re-enable a previously disabled account, or entirely remove the account from the server.
• ask = message text[~button1[;url][~button2[;url]]]
  The ask parameter may be included in the reply to a client's ‘query’ query as a means of implementing a simple but flexible means for a remote server to prompt the user with a free-form question or action confirmation message. This flexible ask facility allows the server to obtain client-signed confirmations of the user's intent through the SQRL client-server channel in situations where the web browser-to-server channel cannot offer sufficient security.
  
  In typical use, a website onto which the SQRL user is already logged-on would confirm a high-value action by saying “Please click or scan the SQRL code to confirm this transaction.” The user would click the provided SQRL button or can the SQRL QR code to initiate another authentication operation. However, in its first response to the client's query query, the server would include this ‘ask=’ parameter to display a custom, server-provided confirmation dialog to which the user would respond.
  
  Since the ask is contained within the server's response to a previous query, the user and client are not compelled to reply and may choose to cancel the dialog and end their interaction with the server. This would presumably prevent the server from proceeding with whatever action it was seeking confirmation.
  
  Note that ‘ask=’ is only valid in response to a client's ‘query’ query and should be ignored by SQRL clients if any SQRL server attempts to add an ‘ask=’ to any other non-query command.
  
  If the user wishes to submit a reply they may use the dialog's standard “OK” acknowledgement which will be present only if no ask reply buttons are explicitly specified. Otherwise they may select one of up to two optionally present buttons (or cancel).
  
  To support international characters, UTF-8 encoding is used for all textual content. The message text and optional button texts are individually base64url encoded to that they may contain characters that have semantic meaning to the transport protocol (CR, LF, and ‘~’). The semicolon (;) is reserved within button text to delimit optional URLs and may not appear on buttons.
  
  The optional ask parameters are specified by a sequential list of tilde-separated (~) arguments as shown by the semantics above. If no parameters are supplied, the message text will be displayed and the dialog's standard Cancel/Ok buttons will be used to cancel the transaction or to acknowledge the receipt of the message, respectively. The message text should be worded accordingly.
  
  The message text may be followed by either zero, one, or two button text and optional URL specifications. In clients where display space and device orientation permits, the buttons should be placed side-by-side with the “first” button on the left.
  
  The client must always include a “btn=” parameter in its reply so the server will recognize the query as a reply to its ask. If the dialog is acknowledged by pressing either of the buttons, the “btn=” parameter's value will be ‘1’ or ‘2’ depending upon which button was chosen, the first or second, respectively. If the dialog is acknowledged by clicking the dialog's “OK” button “btn=0” will be returned.
  
  A button's label text specification may be terminated by a separating tilde (~), a semicolon (;) or the end of the string. If the button text is terminated by a semicolon, the following character begins the specification of a root-anchored URL path which is bound to the button's selection. If the provided path does not begin with a '/' it will be provided by the SQRL client. If the user selects the associated button, in addition to immediately generating a query containing the appropriate “btn=” parameter, the SQRL client will submit the specified URL, using the same scheme, domain and port as the SQRL link, to its host operating system for handling. An example button text string would be: “Click to Launch;/sqrl/extra-confirmation.html”.
  
  Since this is test supplied by a potentially untrusted server, all SQRL implementations must protect against exploitation of unnecessarily powerful display surfaces. A simple text window should be used rather than a full HTML parser. If a limited display surface cannot be provided, implementations must filter/escape any dangerous characters so that they are displayed only and not treated with any exploitable capability.
• can = optional cancellation browser redirection URL
  This optional value may be provided by the server in its response to any query to provide or replace any previously provided authentication cancel URL. If the user aborts the authentication in a “same-device” authentication, the SQRL client will redirect the user's pending browser page to the URL most recently specified by this URL parameter. This URL will be the value provided by the Location: header returned in an HTTP 302 Found reply to the waiting web browser.
Client & Server Parameters Summary
• Client-to-server query parameters:
  EVERY client query MUST include the "server", "client", "idk" and "ids" parameters. Additional parameters MAY or MUST be included as described by the specification above:

  • server=	the base64url encoding of the server's initial SQRL URL or its subsequent response.
  • client=	the base64url encoding of a name=value list consisting of the following required and optional parameters:
  Required:
  • ver=	the highest SQRL protocol version supported by the client.
  • cmd=	one command token specifying this query's command.
  Optional:
  • opt=	a tilde-separated list of command-modifier options.
  • btn=	a single decimal digit indicating the user's reply to a server's "ask" parameter.

  The client provides one or more of the following keys:

  • idk=	the (required) ECC public key corresponding to the user's current identity.
  • pidk=	the (optional) ECC public key corresponding to (one of) the user's previous identity(s).
  • ins=	the (conditional) indexed secret produced upon request of the server.
  • pins=	the (conditional) previous indexed secret produced upon request of the server.
  • suk=	the server unlock key corresponding to the user's current identity.
  • vuk=	the verify unlock key corresponding to the user's current identity.

  The client provides one or more of the following signatures:

  • ids=	the current identity signature of all preceding non-signature data.
  • pids=	the previous identity signature of all preceding non-signature data.
  • urs=	the signature used to validate a RescueCode authentication.

• Server-to-client response parameters:
  EVERY server response to a SQRL client's query MUST include all of the following name-value parameters:

  • ver=	must appear first to establish the format of all that follows.
  • nut=	a nonce to guarantee the uniqueness of every server reply.
  • tif=	the status condition code results of the client's query.
  • qry=	the URL /path to be used for the client's next query, if any.

  The server MAY, as required or desired, also return one or more of the following:

  • url=	the URL /path to be used only upon successful (CPS) authentication.
  • can=	the URL /path used to redirect the browser upon user cancellation.
  • sin=	sent by the server to request the client's matching indexed secrets.
  • suk=	returned whenever the client may have a need to generate an Unlock Request Signature (URS) for highest-privilege operations.
  • ask=	optionally returned in ‘query’ replies when the server wishes to prompt the user.

• (?) anything else
  The web server may include any additional name=value pair data it wishes to, beyond those values enumerated above. (For example, a ‘mac=’ name and value might provide a message authentication code to detect any changes in the returned parameters.) If present, any additional parameters will have no protocol meaning whatsoever to the SQRL client and they will be silently ignored. They will, however, be returned by the client in its subsequent query, and signed. A web server may use any additional parameters to validation or to help it maintain state between its replies and the client next query.

• 2017/06/08 : Added “can=” parameter. Allows server to specify user-cancellation redirection URL.
• 2018/08/21 : Clarified the use of the server's optional ‘ask=’ parameter