-
Notifications
You must be signed in to change notification settings - Fork 5
05. Terminology
This page will attempt to explain the key terms relating to a SQRL authentication process.
We will start by talking about the terms a consumer of the middleware will see, then go on to the terms that relate to the underlying code and the protocol.
This section will cover the terms a consumer of the middleware will need to understand. It will highlight each term; it's uses and purpose in the SQRL authentication process.
This may be clear, but the user is the identifier for the user that your application will be given by the middleware to link to the user’s data.
The UserId directly maps to the "idk" or "pidk" (see the protocol terms section for details of this) that the middleware is sent by a SQRL client.
The purpose of the UserId is to provide a way to lookup users in the storage you have chosen for them. This Id can be changed by a user at any time but the attempts to find old Ids is handled by the middleware. With this in mind it is not advisable to use this UserId as a Id to relate data to it's advised that you have an immutable Id that you store this Used it against that can then be used to link users to data.
The UserId is unique per user and per site so the same user will not have the same UserId on different domains.
This abbreviation stands for "Server Unlock Key" which is one of two public keys that a server is required to store for the user.
The SUK is returned to the SQRL client when it is asked for by the client to produce the URS (Unlock Request Signature see the protocol terms section for details of this).
This abbreviation stands for "Verify Unlock Key" which is one of two public keys that a server is required to store for the user.
The VUK is never sent out from the application but it is used by the middleware to verify the URS (Unlock Request Signature see the protocol terms section for details of this) which ensures only a valid user can unlock or remove a user.
This section will detail the terms a contributor to this project would need to understand.
It will highlight each term; it's uses and purpose in the SQRL authentication process and code.
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 IMK by the HMAC hash of the site's domain name. The binary key is base64url encoded with trailing equals sign padding removed.
This key is passed to the middleware consumers as UserId this makes it a friendlier name for them to consume.
We use the IDK when checking if a user exists or when changing/retrieving any user data.
When a user is authenticated, we set the NameIdentifier claim to the value this can be helpful for consumers to look up information for the authenticated user in the OnTicketReceived events.
Previous IDentity Key as the name suggests it is the users last IDK and is optionally sent by a SQRL client when the user has changed their master key for their identity at any point in time, we might know the user by this Id so when checking for a user we should look for this Is as well if the IDK wasn't matched.
If a user exists with this Id, we must respond with a specific code to the client so it can perform an update on the user to correct the Id the system has stored.
Identity Master Key this is the key which is used to key the HMAC256 which hashes DNS domain names to produce the per-site public/private elliptic curve key pairs which represent and authenticate the user’s identity.
This value is never sent to the middleware and is only used by the SQRL client.
This is a never-repeating opaque cryptographically strong single-use nonce that should only be sent to the client once.
The middleware uses the first NUT which is in the QR code and link shown on the webpage that starts the login process to authenticate users who are performing cross-device authentication.
A NUT should be removed from a store of active NUTs once it has been sent back to the middleware or after it's expired.
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 variety of user identity, command and connection status information for the client query it is in response to.
The middleware has a helpful ENUM to assist with the setting of this three-bit value.
A base64url-encoded list of client parameters. This is a set of values such as the version of SQRL the client is using, the command been asked to be carried out and IDK are required to be included.
There are other values that can be returned these are OPT, BTN, PIDK, INS, PINS, SUK, VUK these are optional and are explained in the "Message brake down" page.
The base64url-encoded data returned by the server in response to the previous client query, if any, or the QR code/links URL if this is the client’s initial query.
This is a set of values such as VER, NUT, TIF, QRY.
Depending on the last response the following might be included: URL, CAN, SIN, SUK, ASK.
The "Message brake down" page explains these in more detail.
The base64url-encoded signature of the message from the client (specifically the client and sever parts), in that order. In this instance, the signature’s key is the per-site private key corresponding to the per-site public key provided by the client within its parameter list contained in the “client” data.
Unlock request signature is used to verify a command that results in the user details been updated.
More documentation can be found on GRC website here https://www.grc.com/sqrl/sqrl.htm