06. Message brakedown

This page contains a breakdown of messages from and to clients.

From client

A client will send a sever a message with the following values in the body:

• client
• server
• ids
• pids [optional]
• urs [optional]

Client

This is a base64 encoded set of key values separated by a "/r/n" newline.

The values that are required to be in this part of the message are:

• VER
• CMD
• IDK

VER

This is the versions of SQRL that the client supports. It is a comma separated list of integers acceptable values can be "#" or "#-#" where # is an integer number. When these is a "#-#" this is a range of versions.

CMD

This is the SQRL command that the client wants the server to run.

This can be one of the following values: QUERY, IDENT, ENABLE, DISABLE, REMOVE.

Quiery

This command allows a client to determine the existence of a user. No data should be altered when a query command is issues.

IDENT

This command allows the client to request the server to authenticate the user if the request is verified by its signature.

ENABLE

This command is the client requesting a disabled user to be enabled when the request is signed with a valid URS.

DISABLE

This command is the client requesting a user to not be allowed to login with there SQRL identity.

REMOVED

This command is the client requesting the user to not be related to this SQRL identity when the request is signed with a valid URS.

IDK

This is the public key that identifies the user uniquely to a domain name.

The optional values that can be in the client section are:

• OPT
• BTN
• PIDK
• INS
• PINS
• SUK
• VUK

OPT

It's ~ separated list of values that let a client specify the sever to carry out extra operations or return extra data.

The values that can be sent back are:

• noiptest: instructs the server not to check the IP of the request generally sent in a cross-device authentication.
• sqrlonly: instructs the server to mark a user as only allowed to login with SQRL. This is optional on the server.
• hardlock: instructs the server to not allow any form of account recovery such as forgot my password emails.
• cps: Client provided session is sent when the SQRL can redirect the browser to a URL returned by the sever. This helps with same device authentication.
• suk: instructs the server to return the server unlock key stored against the IDK on the sever.

BTN

A digit that indicates the button that was clicked by a user when they reply’s to a request that included an ask.

PIDK

This is a previous version of the public key that could have identified the user uniquely to a domain name.

INS

A result of an index secret

PINS

A result of a previous index secret

SUK

The server unlock key the client has for the user.

VUK

The verify unlock key the client has for the user.

Server

This is a base64 encoded SQRL that the user scanned or clicked or if this not the first request it is the last response the SQRL client revived.

IDS

This is the signature of the client and server sections concatenated in that order signed by the client. This can be verified with the IDK.

PIDK

This is the signature of the client and server sections concatenated in that order signed by the client. This can be verified with the PIDK.

URS

This is the signature that is used to validate enabling and removing a user.

From server

A server will send a client a message with the following values in the body:

• ver
• nut
• tif
• qry
• url [optional]
• can [optional]
• sin [optional]
• suk [optional]
• ask [optional]

VER

This is the versions of SQRL that the server supports. It is a comma separated list of integers acceptable values can be "#" or "#-#" where # is an integer number. When these is a "#-#" this is a range of versions.

NUT

This is the latest valid nut that the client should use with the next request.

TIF

This is the transition information flag this is a set of bits that are used to reply to a client with success or error states. The flags that exists are:

• IdMatch (0x1)
• PreviousIdMatch (0x2)
• IpMatch (0x4)
• SqrlDisabled (0x8)
• FunctionNotSupported (0x10)
• TransientError (0x20)
• CommandFailed (0x40)
• ClientFailed (0x80)
• BadId (0x100)
• IdentitySuspended (0x200)

QRY

This is the path the client should use for the next request.

URL

This is the URL that a SQRL client should forward a browser to when the user is authenticated. This should only be sent when the client has the opt of cps.

CAN

This is the URL that the client will forward a browser to if the user cancels the authentication. This should only be sent when the client has the opt of cps.

SIN

A request for the client to return the INS value requested here.

SUK

The server unlock key for a user this is returned when the client sent a opt of suk or the server thinks the client may need it for the next request.

ASK

This is a set of values that allows the server to get the SQRL client to prompt the user.