django-otp-yubikey

PyPI Documentation Source

This is a django-otp plugin that handles YubiKey devices using the Yubico OTP algorithm. This includes two device definitions: one to verify YubiKey tokens locally and another to verify them against a web service.

See django-otp for more information on the OTP framework.

Installation

django-otp-yubikey can be installed via pip:

pip install django-otp-yubikey

Once installed it should be added to INSTALLED_APPS after django_otp core:

INSTALLED_APPS = [
    ...
    'django_otp',
    'django_otp.plugins.otp_totp',
    'django_otp.plugins.otp_hotp',
    'django_otp.plugins.otp_static',

    'otp_yubikey',
]

Local Verification

class otp_yubikey.models.YubikeyDevice(*args, **kwargs)[source]

Represents a locally-verified YubiKey OTP Device.

private_id

CharField: The 6-byte private ID (hex-encoded).

key

CharField: The 16-byte AES key shared with this YubiKey (hex-encoded).

session

PositiveIntegerField: The non-volatile session counter most recently used by this device.

counter

PositiveIntegerField: The volatile session usage counter most recently used by this device.

exception DoesNotExist
exception MultipleObjectsReturned
public_id()[source]

The public ID of this device is the four-byte, big-endian, modhex-encoded primary key.

verify_token(token)[source]

Verifies a token. As a rule, the token should no longer be valid if this returns True.

Parameters:token (string) – The OTP token provided by the user.
Return type:bool

Remote Verification

class otp_yubikey.models.ValidationService(*args, **kwargs)[source]

Represents a YubiKey validation web service. By default, this will point to Yubico’s official hosted service, which you can customize. You can also create instances to point at any other service implementing the same protocol.

name

CharField: The name of this validation service.

api_id

IntegerField: Your API ID. The server needs this to sign responsees. (Default: 1)

api_key

CharField: Your base64-encoded API key, used to sign requests. This is optional but strongly recommended. (Default: '')

base_url

URLField: The base URL of the verification service. Defaults to Yubico’s hosted API.

api_version

CharField: The version of the validation API to use: ‘1.0’, ‘1.1’, or ‘2.0’. (Default: ‘2.0’)

use_ssl

BooleanField: If True, we’ll use the HTTPS versions of the default URLs. (Default: True).

param_sl

CharField: The level of syncing required. See YubiClient20.

param_timeout

CharField: The time to allow for syncing. See YubiClient20.

exception DoesNotExist
exception MultipleObjectsReturned
class otp_yubikey.models.RemoteYubikeyDevice(*args, **kwargs)[source]

Represents a YubiKey device that is to be verified with a remote validation service. In order create these devices, you must have at least one ValidationService in the database.

service

ForeignKey: The validation service to use for this device.

public_id

CharField: The public identity of the YubiKey (modhex-encoded).

exception DoesNotExist
exception MultipleObjectsReturned
verify_token(token)[source]

Verifies a token. As a rule, the token should no longer be valid if this returns True.

Parameters:token (string) – The OTP token provided by the user.
Return type:bool

Admin

The following ModelAdmin subclasses are registered with the default admin site. We recommend their use with custom admin sites as well:

class otp_yubikey.admin.YubikeyDeviceAdmin(model, admin_site)[source]

ModelAdmin for YubikeyDevice.

class otp_yubikey.admin.ValidationServiceAdmin(model, admin_site)[source]

ModelAdmin for ValidationService.

class otp_yubikey.admin.RemoteYubikeyDeviceAdmin(model, admin_site)[source]

ModelAdmin for RemoteYubikeyDevice.

Changes

Change Log

License

Copyright (c) 2012, Peter Sagerson All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.