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.

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:

• Scheme: The SQRL URL scheme is either “sqrl” or “qrl”. The strongly preferred use of “sqrl” as the SQRL URL's scheme signals to the SQRL client that the web server supports standard encrypted and authenticated SSL/TLS connections and has a certificate for the indicated domain. Unless a standard colon-delimited port override is provided, the SQRL client will connect to the IP for the indicated domain at standard HTTPS port 443 and issue a standard HTTP GET query.

  If a host web server does not support SSL/TLS connections, it may signal this to the SQRL client by using the “qrl” scheme. This drops the leading “s” to signal that the SQRL client should issue its user authentication query over an unsecured HTTP connection. In this case, unless a standard colon-delimited port override is provided, the SQRL client will connect to the IP for the indicated domain at standard HTTP port 80 and issue a standard HTTP GET query.

• Domain: As usual, the domain portion of the URL specifies the DNS domain to be looked up to determine the host web server's connection IP address. Unless modified by the optional “d” domain-extension parameter, this is the same string that is HMAC hashed to create the user's site-specific private key.
• Query Separator & Query: The query data begins after the query separator (?) question mark character. To protect against various sorts of replay and prediction attacks, the query data must include a cryptographically strong unpredictable and non-repeating opaque token. This has been previously referred to with the generic term “nonce.” However, due to its specific unpredictability and possible reversibility requirements (more than simply a number used once) this more complete formal specification will use the term “nut.”

  Its precise role will vary based upon the server's implementation needs. It might be the result of a strong one-way hash function or a strong reversible symmetric cipher. But since it is publicly exposed in the SQRL link URL, it must at least have the property of cryptographically strong unpredictability:

• The “Web Server Behavior” page further discusses the recommended ways this “nut” value can be developed and used by the hosting web server.
• Any OTHER server data: This is discussed on the “Web Server Behavior” page, but it's important enough to be mentioned here. Due to the fact that login session-state information is being placed onto a web page where it is then taken up by an SQRL authenticator, the value of any other token the web server might use for session identification must also be completely unpredictable or encrypted. If, for example, a simple session number counter were used, an attacker might examine the SQRL link, predict a future session ID, then trick the user into signing a modified SQRL link for the attacker to use in impersonating the user. Any session tokens should therefore be generated by a cryptographically strong cipher under a secret key or a strong secretly salted hash function.
  
  SQRL clients return and sign the entire unmodified SQRL link URL, exactly as it was received. So websites are free to include any additional information they choose so long as they remain mindful of possible attack implications.
• Server Friendly Name: All SQRL links must also provide the commonly known name of the website for quick and easy recognition by SQRL users. SQRL refers to this as the “SFN” or server friendly name. For example, whereas Amazon's full domain name is www.amazon.com, they are known as Amazon, so their SFN would doubtless be “Amazon”. Similarly, www.wordpress.com would use “Wordpress” and www.ebay.com would use “eBay”. The entire SQRL URL is returned to the server for verification and if the returned “sfn” does not match what is expected, the transaction will be immediately failed.
  
  To support an international character set, individual characters employ UTF-8 encoding and to make the entire name url-safe it is then base64url encoded. The resulting “sfn={base64url-encoded name}” name=value string is included anywhere within the SQRL URL:

• Portion of URL to be hashed: Except as modified by the presence of the optional “d=n” domain extension specifier (see the following item) the SQRL authenticator hashes (with a keyed HMAC function) the entire DNS domain name contained in the SQRL link URL (excluding, as described above, any username, password, or port designation).
  
  The entire UNMODIFIED URL, exactly as it was obtained from the website, is transcribed into the “url” parameter which is returned and signed in the SQRL client's authentication query.
• The optional “x=n” domain eXtension specification:

• As shown in the diagram above, a SQRL URL may optionally contain a domain extension specifier in the query parameter list using the reserved single character name “x”. If present, the “x=n” domain extension specifier will cause the SQRL client to include “n” characters of the path starting immediately after the domain name in the computation of the domain-specific private key. See the diagram above.
  
  Note that if a “:port” specification is present after the domain it will be ignored and skipped during the formation of the “Site Key String” (SKS).
  
  This optional domain extension allows websites which support separate user accounts defined at the start of the resource's path (such as GitHub) to inform the SQRL client of this by indicating how much of the path they would like included in the SQRL's HMAC key hashing.
• Anything else in the SQRL link: The web server may freely include any additional arguments it chooses to within the SQRL link URL.

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

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.

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.

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:

• Before any modifications are made, the link, exactly as received, is preserved to become the value of the client's “url” parameter returned to the server.
• The hostname portion of the link (except for any username:password@) will be used as the value for the query's “Host:” header.
• If any username[:password]@ appeared in the SQRL link URL it will be returned in the query's “Authentication:” header.
• The “User-Agent:” header is set to “SQRL/1” to specify the client and its version.
• The “Content-type:” header is set to “application/x-www-form-urlencoded”

• SQRL POST queries follow the HTTP standard for “form-urlencoded” data: The POST's body is a single string consisting of “name=value” pairs separated with ampersands (‘&’).
• The protocol is deliberately tolerant of arbitrary reordering of individual name=value parameters. This affords compatibility with web server development environments which might parse received form data into a language-specific abstraction of the original submission. We only require that the value of a given named parameter can be retrieved.
• All binary values (public keys and signatures) are base64url encoded with any trailing equals signs (‘=’) removed to prevent confusion with the equals sign in the name=value pair. If needed by the receiving decoder, the appropriate number of equals signs should be appended before decoding the base64url value back to its original binary.
• The “ASCII Encoding of Binary Data” box at the bottom of this page contains additional discussions of SQRL's base64url binary-to-ASCII-to-binary encoding and decoding.
• The query data consists of three or more name=value pairs:
  • client= The base64url encoded collection of the client's arguments as a series of ampersand-separated name=value pairs. The client parameter MUST always be present and SHOULD always be the first parameter in the parameter list.
  • server= Either:
    • The base64url encoded SQRL link URL as it was received by the client before any modifications were made, or...
    • The data received from the server's immediately previous reply (which will be a base64url encoded list of &-separated name=values
    The server parameter MUST always be present and SHOULD always be the second parameter in the parameter list.
  • ids= One or more signatures of the concatenation of the values of the first two parameters. The ids= parameter (at least) MUST always be present since it uses the user's site-specific private key to sign the concatenated values of the first two required parameters, thus validating the user's identity to the web site.
  • ???= Additional signatures will be appended, as needed, to similarly sign the concatenated values of the first two required parameters.
• The value of the second server= parameter is concatenated to the end of the value of the first client= to create the data to be signed and later verified.
• Signatures are NOT “cumulative”. Each signature signs exactly the same string of data, consisting of the concatenated values of those two parameters.
• The client= value contains one or more public keys that are included to allow the receiving web server to validate their respective requested functions. Therefore, there will be a ???= signature for every corresponding public key appearing in the client= value list.

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 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 client value will contain one or more public keys, and possibly other binary data. In all cases, keys and other binary data will be converted into a safe 64-character ASCII character set using standard base64url encoding. After encoding any trailing equals signs, which the encoding may have added as padding, will be removed from the encoded string to prevent confusion with the equals signs separating name=value pairs.
• The client's data being sent to the web server takes the form of a list of name=value pairs with one name=value pair per line and every name=value pair, including the last one, being terminated by a carriage return and line feed (CRLF) pair:

  ver=1<CR,LF>
  cmd=ident<CR,LF>
  idk={base64url encoded identity key}<CR,LF>
  pidk={base64url encoded previous identity key}<CR,LF>
  suk={base64url encoded server unlock key}<CR,LF>
  vuk={base64url encoded verify unlock key}<CR,LF>

• To aid any future version parsing, the first argument of the client value MUST be the version (ver=1) which the SQRL client adheres to. This is the only operator ordering convention. All other name=value parameters may appear in any order within the client value string.
• Once the list of the client's name=value pairs has been assembled, it is base64url converted into a final ASCII encoded string to become the final value of the “client=” 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.


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.

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.

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

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.

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.