SQRL's Service Provider (SSP) API defines a proven application programming interface to support the externalization of SQRL services from the relying website. Although it is foreseeable that server-specific add-ons will also be created to allow web servers to provide native support for SQRL, there will be instances where SQRL authentication services are more naturally provided by an external API server.

As shown in the diagram above, each of the four components communicates with the others. The SQRL SSP API server may reside on the same domain as the website server, fielding all queries for objects with the .sqrl extension, it may reside on a subdomain as shown in the example above, or it may reside on an entirely separate domain.

The SSP API minimizes the work required to add SQRL support to an existing web server. The API replies to web browser queries for SQRL assets on sign-in pages, performs all SQRL protocol transactions with SQRL clients, and uniquely identifies authenticated SQRL users to web servers.

The API also maintains a database that can be used to associate SQRL users to the web server's accounts. When this is done, a SQRL authentication of any previously associated user will return the web server's account directly, eliminating the need for a web server's database to be altered to accommodate SQRL authentication.

The SSP API fully supports SQRL's Managed Shared Access (MSA) feature set with invitations and many-to-one SQRL-to-account mapping with permissions and user management. These features can be explored at the MSA demonstration site: https://sqrl.grc.com/msa which was entirely built using this SSP API.

Using the SSP API, authentication proceeds as follows:

	A login webpage is delivered to the user's browser by the website's server. This will usually include a unique session cookie to identity the user's browser to the web server.
	The logon webpage contains SQRL support javascript (a sample is here) which issues an SSP query for /nut.sqrl to initiate an authentication session and obtain a nonce (the SQRL “nut”) to use in referencing the forthcoming authentication.    The javascript adds the “nut” parameter to the /png.sqrl query to display a corresponding SQRL QR code image. It also dynamically sets the URL of the page's “Click to sign in with SQRL” button.    Once this is done, the page's javascript begins polling the SSP server with periodic /pag.sqrl queries for any post-authentication page to display.
	At this point, authentication begins when the user either clicks the sign in button or scans the displayed QR code with a smartphone: Clicking the sign in button invokes the user's locally-installed SQRL client using the sqrl:// scheme, which the client registers with its operating system. This causes the web browser page to jump to the SQRL client's localhost web server which listens on port 25519. This allows the web browser to eventually receive an HTTP 302 Redirect to the web server containing the 24-character client provided session (CPS) token received at successful authentication.    This CPS token passing—from the SSP server to the user's local SQRL client to the user's local web browser and finally to the web server—eliminates any possible man-in-the-middle to prevent logon spoofing and interception attacks. Scanning the QR code with a SQRL smartphone client picks up the URL of the SSP server and causes the authentication to proceed between smartphone and SSP server. Once successful, the logon page's periodic probes for /pag.sqrl will finally return a 24-character token causing the user's browser to jump to the web server to display a logged-on page to the user.
	Stepping back a bit to point #3 above... Once authentication is initiated, a locally installed or smartphone SQRL client interacts with the SSP server using SQRL's authentication protocol to establish the logging-on user's identity.    Upon successful authentication with a local SQRL client, the SSP API returns a 24-character CPS (Client Provided Session) authentication token to the SQRL client. The client then responds to the user's waiting browser with a 302 Redirect to a previously configured web server URL, supplying the 24-character token to the web server. This provides a secure assertion of the user of this web browser since the only way the browser could have received the CPS token was from the local SQRL client.    Upon successful authentication with a mobile client, the browser's periodic /pag.sqrl query returns the same previously configured URL, with the 24-character authentication token, to which the browser should jump.
	Upon receiving the incoming authentication query from a web browser, the web server forwards the 24-character authentication token it received in the browser query to the SSP server by issuing an /cps.sqrl query containing the token. The SSP server replies with the authenticated identity information it has for the user, including any web server account which might be associated with the user. This ends the authentication session and the transient transaction is deleted from the SSP server. The web server can then sign this user in and jump their browser to any signed-in landing page.

The diagram below depicts the sequential interaction among the four network components described above. You may click this link to view a full-size much more legible diagram. The diagram is split horizontally into four bands, with the top and bottom sections always executed, and either the second or third section used depending upon whether the authentication is with a locally installed or a mobile SQRL client, respectively.

The SSP API uses a standard HTTP query/reply interface with URL-safe parameters, when required, appended to the query as standard application/x-www-form-urlencoded name=value pairs. Each of the queries is defined and described below:

To aid understanding, the four SSP API sections below are presented in the approximate order of their use during a SQRL authentication process:

Web Browser  to  SSP Server
/nut.sqrl  -or-  /nut.sqrl?{1-9}		PUBLIC
Purpose:	Obtain an authentication nonce, known through SQRL's documentation as a “nut”, and cancellation URL for this browser session and logon page.
Opt Params:	1-9= May optionally provide a single digit 1-9 ('0' is equivalent to none) which invokes SQRL's path extension feature for the authentication. This creates separate authentication domains within a single host domain. This is useful if a single domain hosts separate services where visitors have separate identities. sin= { a string naming a “secret index” for the server (see semantics spec.) } ask= { a string specification for a SQRL client ask prompt (see semantics spec.) }
Returns:	nut={ 12-character nonce }&can={ base64url-encoded version of the query's Referer header }
May Return:	x=n&nut={ 12-char nonce }&can={ encoded Referer header } when path extension is present and 'n' will be the parameter digit provided to query.
Usage:	The logon page's javascript issues this query once upon loading to obtain the parameter string which is added to the “Click to sign in with SQRL” URL and the page's CPS-trigger query. (See the SQRL protocol specification for more background and sample javascript here.)    The “nut={ 12-character nonce }” portion, which uniquely identifies this new authentication session, is also extracted from the returned string and used as the session “nut” parameter for the following two browser queries:
/png.sqrl?{ 12-char nut }		PUBLIC
Purpose:	Obtain an optical QR code image encoded with the authentication nut for this browser session.
Param:	nut={ 12-character nut }
Returns:	A binary object with a mime type of image/png.
Usage:	SQRL logon pages typically offer a QR code for use with smartphone-based SQRL clients. This image reference should be embedded into a page to display the QR code.
/pag.sqrl?{ 12-char nut }		PUBLIC
Purpose:	Periodically query the SSP server for a new page to display.
Param:	nut={ 12-character nut }
Returns:	Either an HTML “404 Not Found” when no page change is needed, Or a “200 OK” with the URL for the page's javascript to jump the browser to.
Usage:	The logon page's javascript periodically issues this query while waiting for a SQRL authentication to succeed. A return of 404 Not Found causes a reissue of the same query after a delay. (See the sample javascript here.)
SQRL Client  to  SSP Server
/cli.sqrl?{ 12-character nut }		PUBLIC
Purpose:	This is the SQRL client query URL used with HTTP POSTs for the SQRL protocol. SQRL clients send their authentication queries to this URL.
Param:	nut={ 12-character nut }
Returns:	A multiline block of HTML form-encoded data following the SQRL protocol.
Usage:	SQRL clients use this query for their transactions with the SSP server. The initial nut used is the value returned by the /nut.sqrl query and embedded within the /png.sqrl image. The logon page's javascript uses the nut returned by the /nut.sqrl query to form the sqrl:// URL assigned to the page's “Click to sign in with SQRL” button. (See the SQRL protocol specification for more background and sample javascript here.)
Web Browser  to  Web Server
{ configured URL }?{ 24-character authentication token }		PUBLIC
Purpose:	The web browser jumps to the pre-configured URL on the web server to inform the web server of a successful SQRL authentication.
Param:	nut={ 24-character authentication nonce }
Returns:	An HTTP 302 Redirect reply to the web browser.
Usage:	When the web server receives this query, the user has successfully authenticated with SQRL and the user's web browser is waiting to receive the URL of a logged-on landing page. The web server uses the SSP API /cps.sqrl query (see next item below), passing it the 24-character nonce it received from the browser's query, to obtain the SQRL user's account information. This allows the web server to sign the user into an account, and the web server then replies with an HTTP 302 Redirect to the logged-on page.
Web Server  to  SSP Server
/cps.sqrl?{ 24-character CPS nonce }		PRIVATE
Purpose:	The web server obtains SQRL user and account information with this query.
Param:	The 24-character authentication nonce obtained from the web browser.
Returns:	user={ 12-character unique user identifier } stat= { comma-delimited list of zero or more tokens } name= { base64url-encoded URL of the authentication logon page }
May Return:	acct={ up to 64-character web server account ID }
Usage:	When SQRL authentication is successful, the web browser jumps to the web server carrying a 24-character authentication nonce. The web server then issues this /cps.sqrl?... query to the SSP server with the 24-character nonce as its sole parameter. The SSP server replies with either the three or four parameters to identify the authenticated user. This allows the web server to log the user on and then reply to it with an HTTP 302 Redirect to a logged on page.
	The stat= parameter's tokens are defined below under “API parameter notes.”
/add.sqrl?{ parameter list described below }		PRIVATE
Purpose:	Add or update associations between SQRL user and web server account.
Req Params:	acct= { up to 64-character web server account ID }
Opt Params:	user= { 12-character unique user identifier } stat= { comma-delimited list of zero or more tokens } name= { up to 64-character username handle }
Returns:	The updated list of SQRL users associated with the account.
Usage:	If the SQRL user is not already known to the system, SQRL authentication creates a unique but temporary SQRL ID for a user. If the webserver wishes to make this SQRL ID permanent or to create a permanent association with its own account, it must issue this /add.sqrl? query with a non-null acct= parameter which does not need to be unique.    In normal use, this query will almost always be used to add SQRL user and web server account associations. So both the acct= and user= parameters will be present. However, to support managed shared access, it can also be used before a SQRL user has been associated to the web server account. In that case, the user= parameter will be omitted and the name= parameter will be used in its place.    If an existing entry is being updated when the stat= or name= parameters are not present, their values will not be changed. But if they are present with a null value, their values will be set to null. An association's SQRL user cannot be changed once set. In the unlikely event that a SQRL user would be changing their account association, they would first be removed (see the /rem.sqrl query) then re-associated.
/rem.sqrl?{ parameter list described below }		PRIVATE
Purpose:	Remove one or more SQRL / web server account associations.
Req Params:	user= { 12-character unique user identifier } -or- acct= { up to 64-character web server account ID }
Opt Param:	name= { up to 64-character username handle }
Returns:	The updated list of SQRL users associated with the account.
Usage:	This query can be called in any one of three ways: If the user= parameter is present its specification is guaranteed to be unique so that SQRL user's account association will be deleted. If no user= parameter is present, the acct= and optional name= parameters will be used. If name= is not present, all SQRL associations for that account will be removed. This is useful when a web server's account is being deleted so that all of its possible SQRL associations will also be deleted. If a name= is present along with acct= then only the matching named SQRL association will be removed. This is useful for operations supporting SQRL's managed shared access. Note that SQRL associations should be removed with this /rem.sqrl? query when the associated website account is deleted. This releases resources for this user in the SSP API database.
/lst.sqrl?{ one of the three parameters below }		PRIVATE
Purpose:	List all SQRL users associated with the indicated web server account, the SQRL user or a pending invitation.
Req Params:	acct= { up to 64-character web server account ID } -or- user= { 12-character unique user identifier } -or- invt= { 20-digit outstanding invitation code }
Opt Params:	None
Returns:	If acct= is provided, returns the current list of SQRL users associated with the account. Otherwise, if user= is provided, return the user's association record, if any. It invt= is provided, return any record with a matching outstanding invitation.
Usage:	This query may be of interest to the web server for various purposes. However, it is primarily intended to support SQRL's managed shared access features where a list of all SQRL users with associations to a given account need to be known and displayed. The return for this, as for the /add.sqrl and /rem.sqrl queries, is a textual list containing one entry per line having this format:      user={...}&acct={...}&name={...}&stat={...}&invt={...}
/inv.sqrl?{ parameter list described below }		PRIVATE
Purpose:	Create and register a new pending invitation for a SQRL user to join the indicated web server account.
Req Params:	acct= { up to 64-character web server account ID } name= { up to 64-character username handle } stat= { comma-delimited list of zero or more tokens }
Opt Params:	None
Returns:	The 20-digit invitation assigned to the pending account.
Usage:	This query is used strictly for SQRL's managed shared access. An account manager issues an invitation to a SQRL user, receiving a 20-digit invitation code which is sent to the invitee out-of-band. The invitee authenticates with SQRL and rather than creating an account, provides the 20-digit invitation which authenticates their elligibility for addition to the existing account. This facility can be seen and explored at: https://sqrl.grc.com/msa

PUBLIC

versus

PRIVATE

As noted above, the five web server to SSP server queries must be private and accessible only to the web server. This can be easily accomplished in any number of ways. The SSP private service might be bound to a network interface on a private, internal, non-public network. Or the SSP service could be bound to a non-standard firewalled port (55219 is the recommended default) with the assurance that this port is not publicly available. Alternatively or additionally this could be arranged by having the SSP API server check the IP address of the requesting machine ensure that it is the related web server, or that the query is coming from a machine on a non-routable (private) IP network.

The stat= parameter's value consists of a comma-delimiter list of zero or more string tokens each of whose presence or absence conveys user SQRL client or user account status to and from the hosting website. The list of standard tokens, and their meaning is:

• sqrlonly:	The user's SQRL client has been configured to ask websites to disable all other non-SQRL means of visitor identification and logon.
• hardlock:	The user's SQRL client has been configured to ask websites and website staff refuse any and all requests to help the user recover ANY means of identity authentication (both SQRL and non-SQRL).
• disabled:	The user has disabled SQRL logon access to this website. This status will be received from the /cps.sqrl? query. The website should display an acknowledgement to the user and the user's logged-on state is not changed by this: If the user is currently logged-on they remain logged on.
• remove:	The user has requested a removal of their SQRL identity from this website. This status will be received from the /cps.sqrl? query. The website should display an acknowledgement to the user. The website should usually comply with the user's request, but if the user has no backup means of authenticating and signing into the website the site may allow the user to choose to abort the removal at this time. If the web server removes the user's SQRL association it must also issue a /rem.sqrl? query to the SSP API to delete the user from the SSP database.
• rekeyed:	The user's SQRL identity has been rekeyed since its previous authentication. This may be significant to high-security websites which might ask the user if they wish to invalidate other web browser sessions.
• acctownr:	This user is the “owner” of the account. This is used to support SQRL's managed shared access (MSA) features.
• acctmngr:	This user is a “manager” of the account. This is used to support SQRL's managed shared access (MSA) features.

Additionally:

• All public queries must be performed over HTTPS connections for endpoint authentication and protection from observation and tampering.
• The web server's private queries to the SSP API do not need to be secured by TLS since they are already private. This frees the SSP server from needing to have any sort of trusted certificate for local queries.
• The web server's SQRL's logon pages should follow standard best practices for web logon: The pages must be secure to prevent tampering with browser session cookies and those cookies should be marked “Secure” and “HttpOnly” to hide them from non-https queries and to prevent access by the page's javascript.
• Query parameters are URL-safe (% escaped where needed) application/x-www-form-urlencoded name=value pairs provided as URL parameters of HTTP GET queries using standard HTTP syntax.
• Query and reply parameter values have the following sizes:
  • 12 ASCII chars: SQRL nuts and user identities are 12 characters.
  • 20 ASCII digits: Managed shared access (MSA) invitations are 20 digits.
  • 24 ASCII chars: The client provided session (CPS) auth token is 20 digits.
  • 64 ASCII chars: The web server account ID, Username handle and Status string may each be up to 64 characters.
• IMPORTANT NOTE: The SQRL authentication domain is the public domain of the SSP server. All SQRL identities for a website are derived from and tied to this domain. To prevent many forms of spoofing, there is deliberately zero flexibility here. Therefore, the initial choice of authentication domain must be made with some care since it cannot be casually changed. (There is a protocol for migrating between domains, but it is usually only practical when domain properties are being moved. It cannot not be done casually.) For this reason, the use of a subdomain such as sqrl.example.com is recommended, though any domain prefix can be used.

The SSP API server requires the following configuration:

• Web Server Authentication Query URL
  Upon successful authentication, the SSP server provides this URL to the web browser for it to use calling the web server. This configuration parameter takes the form of a standard 'C' language style formatted print (printf) string where the 24-character authentication nonce will be substituted for the '%s' in the format template.
  (Example: https://www.example.com/auth.php?%s)
• SSP Database Files
  The SSP API maintains three database files: sqrl-assoc.db, sqrl-ident.db and sqrl-index.db which will be created in the directory from which the sspapi.dll is loaded. This keeps everything together, but it also means that this directory will need to be writeable by the server's W3SVC process.
• Private Query Port and IP
  Public access to the SSP server's private API must be blocked. This is easily achieved by assigning it a non-standard publicly firewalled port and also by specifying the IP of the machines which are allowed to query it.

The Web Server requires the following configuration:

• SSP API Query URL
  The web server calls to the SSP API to obtain information about the SQRL user, and also if it wishes to have the SSP API manage the association of web server accounts to SQRL user identities. The URL it will use (hostname:port) to privately query the SSP API needs to be configured for the web server's use.
  (Example: http://{internal-IP}:55219)

Website developers who wish to add SQRL support to their existing servers need to:

1. Establish an instance of the SQRL SSP API server so that it is privately web query-accessible to the web server, and so that the SSP API server is publicly accessible.
2. Add to the web server's logon page: A SQRL QR code image asset (/png.sqrl) and javascript which sets the /png.sqrl's URL and “Click to sign in with SQRL” button, support local SQRL client usage and page auto-update polling (sample javascript is here).
3. Add web server support for a browser URL which forwards the 24-character authentication nonce to the SSP server then redirects the web browser to a logged-on page.
4. For account management, either add web server support for SQRL identity association or add support for those functions provided by the SSP API.

And that's it.

• The SSP API server has two network interfaces:
  • A public HTTPS web server which presents a trusted TLS certificate replying to web browser and SQRL client queries over HTTPS standard port 443. This will be SQRL's “authentication domain.”
  • A private non-publicly accessible HTTP web server, which may be on a private network, replying to private web server queries at any mutually agreed-upon (non-publicly accessible) port.
• The web server needs the following:
  • A URL browsers will jump to providing a 24-character nonce. The web server's reply will be an HTTP 302 Redirect to a logged-on landing page.
  • Code to call the SSP server with the 24-character nonce provided by a browser. The SSP reply will be information about the user, including the web server's own account ID if it had been previously associated with the user.
  • Optional: If the web server wishes, it may use the SSP's built-in database to associate SQRL users to web server accounts so that no modification of the web server's account database is required to support SQRL.
• The logon page needs JavaScript (sample here) to perform the following tasks:
  • Query the /nut.sqrl API to initiate a session and obtain a “nut” nonce.
  • Place the nut into the query for a /png.sqrl image to display a SQRL QR code.
  • Place the nut into the URL of the “Click to sign in” button.
  • Periodically poll the /pag.sqrl API to obtain a new page to display.

• Gibson Research's SSP API Reference Library:
  Gibson Research has written a reference implementation of this SSP API as a standard 32-bit ISAPI module compatible with Microsoft's 32- and 64-bit IIS family of web servers and 32-bit Apache. This ISAPI module can either be hosted on the website server, when feasible, or hosted on an external server.

  The 26KB binary of the SSP ISAPI module is available to any interested developers and will be widely available shortly. Its full public release will include its 32-bit MASM source code as soon as GRC's proprietary include file references, custom macros, and additional internal documentation have been incorporated into it for publication.

  Additionally, for non-Windows developers, we have an unlicensed copy of Windows 10 Pro fully setup and pre-configured in a VMware VM hosting the SSP API and test server, identical to what can be found at https://sqrl.grc.com/demo and https://sqrl.grc.com/msa. (Windows 10 functions without registration with some minor user-interface customization features disabled. It is the developer's responsibility to register it if it will be used for any length of time. Corporate developers may simply apply one of their available license keys.) Developers who wish to duplicate SQRL's SSP API for other platforms, or integrate it with other web servers, are invited to inquire.

  GRC's implementation is dependent upon three external library DLLs: the Berkeley database, the Libsodium crypto library, and a QRcode encoding library.

Secure QR Login (SQRL) Documentation:

1 Introduction & overview     2 The user's view of the application     3 Detailed crypto architecture     4 The identity lock protocol     5 Client-Side key management     6 User-interface & operation     7 Anti-phishing countermeasures     8 Attacks, weaknesses, vulnerabilities     9 Link & query protocol syntax   10 Link & query protocol semantics   11 SQRL's Secure Storage System   12 Our use of the SCrypt PBKDF   13 Client implementation details   14 Web server behavior   15 SQRL Service Provider API   16 Implementation resources   17 Projects and finished applications   18 SQRL commentary from the industry   19 Frequently Asked SQRL Questions   20 Feedback about SQRL & these pages

Gibson Research Corporation is owned and operated by Steve Gibson.  The contents of this page are Copyright (c) 2024 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.

Last Edit: Mar 07, 2019 at 14:20 (2,204.35 days ago)

Viewed 2 times per day