Welcome to YubiStorm’s documentation!

Apart from providing the module itself, this project comes with a test web server that you can try. The test web server is a well documented single file, and you can get the know-how from there. Please note that the test server is not included in the pypi package (e.g. it cannot be installed using pip or easy_install), but you can download the whole project repository from here: https://bitbucket.org/nagylzs/yubistorm/downloads or you can clone the project. For details, see https://bitbucket.org/nagylzs/yubistorm

Asynchronous client for YubiCloud and Tornado.

class yubistorm.YubiStorm(client_id, client_secret, logger=None)

Asynchronous YubiCloud authentication client that works with tornado.

api_path = '/wsapi/2.0/'
api_servers = ['api.yubico.com', 'api2.yubico.com', 'api3.yubico.com', 'api4.yubico.com', 'api5.yubico.com']
create_signature(params)

Create HMAC_SHA1 signature for a query.

Parameters:params – A dict of GET parameter/name pairs.
Returns:The base64 encoded HMAC signature, as required by the YubiKey validation protocol. Please note that the returned value is not a binary string. It is a normal str instance.
Return type:str
get(rel_url, params, add_signature=True)

Get from YubiCloud.

Parameters:
  • rel_url – URL relative path to api_path
  • params – a dict of GET parameter values to be added to the GET url
  • add_signature – Set flag to add hmac signature as parameter “h”
Returns:

a response object

This method sends a https GET request to one of the yubicloud servers and returns the response object. The server is selected randomly from api_servers.

This is an async method. You need to await for it. Do not call synchronously.

get_and_parse(rel_url, params, add_signature=True)

Get from YubiCloud server and parse text response.

Parameters:
  • rel_url – URL relative to api_url
  • params – a dict of GET parameter values to be added to the GET url
  • add_signature – Set flag to add hmac signature as parameter “h”. Increases security (the server can verify the authenticity of the client).
Returns:

a data structure, parsed from the response body text.

This is an async method. You need to await for it. Do not call synchronously.

IMPORTANT: before you use the response, you must also call verify_signature on it!

classmethod get_yubikey_id(otp)

Get the unique identifier of a YubiKey from an otp.

Parameters:otp – A string containing the one time password, obtained from the YubiKey.

Each YubiKey has a fixed unique identifier that is contained within the generated OTP. The YubiCloud service uses this identifier to identify the key, and store otp usage, detect replay attacks etc.

This method extracts the unique identifier of the YubiKey from an otp generated with it. This identifier can be used assign the YubiKey to a user. Then it will be possible to find the user by giving just a single otp string (e.g. username input is not needed).

classmethod is_valid_otp(otp)

Check if the given otp value is an otp string that has a valid format.

Parameters:otp – A string containing the one time password, obtained from the YubiKey.

Unfortunately, the modhex format used by YubiKey can be altered by a Drovak-based keyboard. YubiCo’s recommendation is that we only check that the otp has 32-48 printable characters.

user_agent = 'YubiStorm 0.1.1'
validate_cert = True
verify(otp, sl='secure')

Veryify OTP value with YubiCloud server.

Parameters:
  • otp – OTP value provided by a YubiKey hardware device.
  • sl – securelevel value. When given, this should be an integer between 0 and 100, indicating percentage of syncing required by client. You can also use strings “fast” or “secure” to use server-configured values. If absent, let the server decide.
Returns:

Returns a dict that contains a subset of the response from the server. Keys in the response:

  • id - unique identifier of the yubikey

  • timestamp - YubiKey internal timestamp when the key was pressed

  • sessioncounter - YubiKey internal usage counter when key was pressed.

    This will be a strictly increasing number that shows how many times the key was pressed since it was first programmed.

  • sessionuse - YubiKey internal session usage counter when key was pressed

  • sl - percentage of external validation server that replied successfully (0 to 100)

Note

  • When YubiCloud servers are not available, this method will raise a tornado.httpclient.HTTPError
  • When authentication is unsuccessful, this method will raise a YubiStormAPIError.
verify_signature(params)

Verify signature for a response.

Parameters:params – A dict of values as returned by the YubiCloud server. It should contain the hmac signature under the “h” key.
Returns:True if the signature was correct, False otherwise.
exception yubistorm.YubiStormAPIError

Raised when YubiCloud API call returns an error.

Instances of this class mean that they YubiCloud server already responded, and returned a status code that indicates a problem detected on the server side.

exception yubistorm.YubiStormError

Raised for all kinds errors, that are above the https level.

Note

For http level errors, tornado.httpclient.HTTPError is raised instead.

exception yubistorm.YubiStormSecurityBreachError

Raised when the client library detects possible security breach.

Instances of this class mean that they YubiCloud server already responded, but there is a problem with the response: the client side detected a possible security breach.