sqrl

README

SQRL

An implementation of the SQRL protocol, designed to be easy to integrate into a http server or SQRL client.

This is not production ready, please proceed with caution.

Simple Quick Reliable Login (SQRL) is a protocol designed and formalised by Steve Gibson of the Gibson Research Corporation. Visit his site for more information about the SQRL.

SSP Example

The SQRL Service Provider (SSP) example is based on Steve's own example at sqrl.grc.com. To run the sample use the following;

$ cd ssp/example
$ go run *.go

Documentation

Index

• Constants
• Variables
• type ClientMsg
  • func ParseClient(raw string) (*ClientMsg, error)
  • func Verify(req *Request, first *Transaction, response *ServerMsg) (*ClientMsg, error)
  • func (m *ClientMsg) Encode() (string, error)
  • func (m ClientMsg) HasOpt(query Opt) bool
• type Cmd
• type Identity
• type Nut
• type Nutter
  • func NewNutter() Nutter
• type Opt
• type Request
• type ServerMsg
  • func ParseServer(raw string) (*ServerMsg, error)
  • func (m *ServerMsg) Encode() (string, error)
  • func (m *ServerMsg) Is(flag TIF) bool
  • func (m *ServerMsg) Set(flag TIF) *ServerMsg
  • func (m *ServerMsg) Unset(flag TIF) *ServerMsg
• type Signature
  • func (s Signature) Verify(id Identity, payload string) bool
• type TIF
• type Transaction

Constants

const (
	// V1 is the version 1 string for the SQRL protocol.
	V1 = "1"

	// Scheme is sqrl: used in SQRL URI's
	Scheme = "sqrl"
)

const (
	// CmdUnknown is used when a client's query was not understood.
	CmdUnknown = Cmd("")

	// CmdQuery allow the SQRL client to determine whether its user
	// is known to the SQRL server and to optionally obtain server-stored
	// data which the client may need.
	//
	// With each query command, the client assert its user's current identity
	// key and optionally a previous identity key.
	CmdQuery = Cmd("query")

	// CmdIdent requests will usually follow one or more query CmdQuery.
	//
	// 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.
	CmdIdent = Cmd("ident")

	// CmdDisable 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.
	CmdDisable = Cmd("disable")

	// CmdEnable 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).
	CmdEnable = Cmd("enable")

	// CmdRemove 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.
	CmdRemove = Cmd("remove")
)

const (
	// OptNoIPTest instructs the server to ignore any IP mismatch and to proceed
	// to process the client's query even if the IPs do not match. By default,
	// SQRL servers fail any incoming SQRL query whose IP does not match the IP
	// encoded into the query's nut.
	OptNoIPTest = Opt("noiptest")

	// OptSQRLOnly disables any alternative non-SQRL authentication capability.
	OptSQRLOnly = Opt("sqrlonly")

	// OptHardlock disables 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.
	OptHardlock = Opt("hardlock")

	// OptCPS 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.
	// https://www.grc.com/sqrl/semantics.htm
	OptCPS = Opt("cps")

	// OptSUK instructs the SQRL server to return the stored server unlock key
	// (SUK) associated with whichever identity matches the identity supplied
	// by the SQRL client.
	OptSUK = Opt("suk")
)

const (
	// TIFCurrentIDMatch 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).
	TIFCurrentIDMatch = TIF(0x01)

	// TIFPreviousIDMatch 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).
	TIFPreviousIDMatch = TIF(0x02)

	// TIFIPMatch 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.
	TIFIPMatch = TIF(0x04)

	// TIFSQRLDisabled indicates that SQRL authentication for this
	// identity has previously been disabled. 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.
	TIFSQRLDisabled = TIF(0x08)

	// TIFFunctionNotSupported indicates that the client requested one or
	// more SQRL functions (through command verbs) that the server does
	// not currently support.
	TIFFunctionNotSupported = TIF(0x10)

	// TIFTransientError indicates 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.
	TIFTransientError = TIF(0x20)

	// TIFCommandFailed 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.
	TIFCommandFailed = TIF(0x40)

	// TIFClientFailure 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
	TIFClientFailure = TIF(0x80)

	// TIFBadIDAssociation 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
	TIFBadIDAssociation = TIF(0x100)
)

Variables

var (
	// ErrInvalidClient the 'client' parameter is invalid.
	ErrInvalidClient = errors.New("invalid client param")
	// ErrInvalidClient the 'server' parameter is invalid.
	ErrInvalidServer = errors.New("invalid server param")
	// ErrInvalidIDSig the identity signature parameter is not correct
	// for the given identity key and payload.
	ErrInvalidIDSig = errors.New("invalid identity signature")
	// ErrIPMismatch the client IP address does not match the original
	// transaction in the negotiation.
	ErrIPMismatch = errors.New("ip does not match")
)

var Base64 = base64.URLEncoding.WithPadding(base64.NoPadding)

Base64 is the encoder that should be used when encoding keys, signatures and other payloads for transmission.

It is the standard URL encoding with no padding to avoid confusion around the meaning of the = when form encoding SQRL requests.

Types

type ClientMsg

type ClientMsg struct {
	Ver []string
	Cmd Cmd
	Idk Identity

	Opt []Opt
}

ClientMsg is used to represent the values sent by the client to the server.

Ver are the versions of SQRL the client supports. Cmd is the command type for this request.

func ParseClient

func ParseClient(raw string) (*ClientMsg, error)

ParseClient decodes a client message from the given string

func Verify

func Verify(req *Request, first *Transaction, response *ServerMsg) (*ClientMsg, error)

Verify checks that a request from a SQRL client is valid.

The transaction that started this session should be provided if one exists. If no previous transaction is provided, the request is presumed to be the first request for this session.

Note: No attempt is made to verify the previous transaction (other than to compare it's properties to those of the new transaction). It is assumed that the previous transaction has already had it's signatures checked and payload validated.

If a validation error is encoutered, the precise error will be returned and the correct transaction information flags will be set on the response.

func (*ClientMsg) Encode

func (m *ClientMsg) Encode() (string, error)

Encode writes the client message to a string ready for transmission to a SQRL server.

func (ClientMsg) HasOpt

func (m ClientMsg) HasOpt(query Opt) bool

HasOpt returns true/false whether the given option was provided.

type Cmd

type Cmd string

Cmd are the different commands a SQRL client can issue to the server.

type Identity

type Identity string

Identity represents a users site specific public key, base64 encoded for transmission.

type Nut

type Nut string

Nut is a base64, encrypted nonce that contains metadata about the request that it was derived from.

type Nutter

type Nutter interface {
	Next() Nut
}

Nutter generates new nuts used to issue unique challenges to a SQRL client. It is also used to validate nuts that were previously issued.

func NewNutter

func NewNutter() Nutter

NewNutter creates a Nut generator

type Opt

type Opt string

Opt are used to indicate client preferences for a SQRL request.

type Request

type Request struct {
	Nut    Nut
	Client string
	Server string
	Ids    Signature

	ClientIP string
}

Request represents a (usually HTTP) request sent from a SQRL client to a SQRL server.

type ServerMsg

type ServerMsg struct {
	// TODO: should we remove Ver? Do package
	// consumers actually need to be able to
	// set this?
	Ver []string
	Nut Nut
	Tif TIF
	Qry string
	URL string
}

ServerMsg is used to represent the values sent from the server to the client.

func ParseServer

func ParseServer(raw string) (*ServerMsg, error)

ParseServer decodes the base64 encoded server parameter into the component parts.

func (*ServerMsg) Encode

func (m *ServerMsg) Encode() (string, error)

Encode writes the server message to a string ready for transmission to the client.

func (*ServerMsg) Is

func (m *ServerMsg) Is(flag TIF) bool

Is returns whether or not the server message includes the given transaction information flag.

func (*ServerMsg) Set

func (m *ServerMsg) Set(flag TIF) *ServerMsg

Set adds the given transaction information flag to the server message.

func (*ServerMsg) Unset

func (m *ServerMsg) Unset(flag TIF) *ServerMsg

Unset removes the given transaction information flag from the server message.

type Signature

type Signature string

Signature is a base64 signature sent by the client. The signature can be verified using the corresponding identity.

func (Signature) Verify

func (s Signature) Verify(id Identity, payload string) bool

Verify determines if the given signature is valid.

type TIF

type TIF int

TIF represent Transaction Interaction Flags sent from the server to provide information about a client request.

type Transaction

type Transaction struct {
	Next Nut
	*Request
}

Transaction represents a SQRL request and response, a single exchange in a SQRL negotiation. There are likely to be multiple transactions for a single SQRL sign-in.

Next is the Nut that was issued to the client as part of this transaction and should be resubmitted with the next request to continue where the client and server left off.