sqrlserver.request module

class sqrlserver.request.Request(key, params, **kwargs)

Bases: object

Class encompassing SQRL client requests

The class acts as a simple state machine. The request can have one of five states:

  • NEW (initial state, no processing has been done)
  • WELLFORMED (initial well-formedness checks have been done and passed)
  • VALID (initial validity tests have been done and passed; while in this state, the request will process client- submitted commands)
  • ACTION (the user needs to provide additional information)
  • COMPLETE (end state; finalize and return the response)

After the class is initialized, call handle to start the transition loop. It will never exit without the state being either ACTION or COMPLETE.

  • ACTION means the user needs to gather information. It is accompanied by a payload that explains what it needs.
  • COMPLETE means that all processing that can be done has been done. You can finalize and return the response, which will include the necessary status codes for the client.

Note

Errors in the **kwargs will result in a thrown ValueError. Any other errors that arise not from client input also result in thrown errors. All client-related errors are communicated through the Response object.

Parameters:
  • key (bytes) – 32-byte encryption key. Must be the same as what you used to encrypt the nut.
  • params (dict) –

    All the query parameters from the query string and POST body.

    The following parameters must exist:

    • nut
    • server
    • client
    • ids

    Depending on the content of these, additional parameters may also be needed. Missing or malformed parameters will result in an error response.
Keyword Arguments:
 
  • ipaddr (string) – String representation of the valid IPv4 or IPv6 address the request came from. Defaults to ‘0.0.0.0’.
  • ttl (uint) – Required. The maximum acceptable age in seconds of the submitted nut. Defaults to 600 (10 minutes).
  • maxcounter (uint) – The maximum acceptable counter value in the submitted nut. Defaults to None, which disables upper-limit checking of the counter.
  • mincounter (uint) – The minimum acceptable counter value in the submitted nut. Defaults to None, which disables lower-limit checking of the counter.
  • secure (bool) – Whether the request was received via SSL. Defaults to True.
  • hmac (string) – The response object emits a keyed MAC. Because this library is stateless, the server has to be responsible for storing this MAC if desired (recommended). It would need to be stored and returned with each repeated query in the same client session. If present, the validity check will verify that the MAC is valid. It is keyed by the master key passed at object instantiation. Unless that key is relatively stable, this check may not be useful.
finalize(**kwargs)

Finalizes and returns the internal Response object.

This function has no side effects. It can be called multiple times without issue. SFN is injected automatically.

Keyword Arguments:
 
  • counter (uint) – 32-byte integer to encode as the counter value in the new nut. Must be provided if you want the object to generate the nut for you.
  • ipaddr (string) – The IPv4 or IPv6 address you want encoded into the new nut. If not provided, it will use the ipaddress saved in the Request object.
  • nut (Nut) – A pre-generated nut. If provided, this nut will be injected into the response. Otherwise a new nut will be generated and injected for you.
  • params (dict) – A dictionary of name-value pairs that will be sent to the client, and that the client is supposed to return untouched. You can also encode these values into the qry.
  • qry (string) – The URL the client should respond to. If not provided,the last value sent will be used. This is a good place to also encode any state information you want the client to return to you (though see params below). The scheme and netloc parts will be stripped, if given. The nut (whether autogenerated or provided) will be inserted into qry for you.
  • timestamp (uint) – Unix timestamp (seconds only) to be encoded into the new nut. If omitted, it will use the current system time.
Returns:

the finalized response object.
Return type:

Response
handle(args={})

The core request handler.

After each call, it will set the state property to either ACTION or COMPLETE. The user is expected to keep calling handle (with appropriate args) until COMPLETE, at which point the response object can be finalized and returned.

Parameters:args (dict) – Different action settings require different information to resolve (documented below). Pass that data here.

Notes

The goal of this library is to generalize as much as is reasonable. That means this code has no idea how your server runs or stores data. So to fulfil the request, it may require additional information. That is gathered by setting the state to ACTION and by setting the action property.

The action property, if set, will be an array of tuples. The actions should be resolved in the order provided.

The first element of each tuple will be a keyword. Depending on that keyword, additional elements may be provided. You are expected to call handle again with any requested information passed in a single dictionary.

For more details, please read the standalone docs.