yubikit.piv

Attributes

PublicKey

PrivateKey

SLOT_CARD_MANAGEMENT

SLOT_OCC_AUTH

DEFAULT_MANAGEMENT_KEY

PIN_LEN

TEMPORARY_PIN_LEN

INS_VERIFY

INS_CHANGE_REFERENCE

INS_RESET_RETRY

INS_GENERATE_ASYMMETRIC

INS_AUTHENTICATE

INS_GET_DATA

INS_PUT_DATA

INS_MOVE_KEY

INS_GET_METADATA

INS_ATTEST

INS_SET_PIN_RETRIES

INS_RESET

INS_GET_VERSION

INS_IMPORT_KEY

INS_SET_MGMKEY

TAG_AUTH_WITNESS

TAG_AUTH_CHALLENGE

TAG_AUTH_RESPONSE

TAG_AUTH_EXPONENTIATION

TAG_GEN_ALGORITHM

TAG_OBJ_DATA

TAG_OBJ_ID

TAG_CERTIFICATE

TAG_CERT_INFO

TAG_DYN_AUTH

TAG_LRC

TAG_PIN_POLICY

TAG_TOUCH_POLICY

TAG_METADATA_ALGO

TAG_METADATA_POLICY

TAG_METADATA_ORIGIN

TAG_METADATA_PUBLIC_KEY

TAG_METADATA_IS_DEFAULT

TAG_METADATA_RETRIES

TAG_METADATA_BIO_CONFIGURED

TAG_METADATA_TEMPORARY_PIN

ORIGIN_GENERATED

ORIGIN_IMPORTED

INDEX_PIN_POLICY

INDEX_TOUCH_POLICY

INDEX_RETRIES_TOTAL

INDEX_RETRIES_REMAINING

PIN_P2

PUK_P2

UV_P2

BCD_SS

BCD_FS

BCD_ES

Classes

ALGORITHM

str(object='') -> str

KEY_TYPE

Enum where members are also (and must be) ints

MANAGEMENT_KEY_TYPE

Enum where members are also (and must be) ints

SLOT

Enum where members are also (and must be) ints

OBJECT_ID

Enum where members are also (and must be) ints

PIN_POLICY

Enum where members are also (and must be) ints

TOUCH_POLICY

Enum where members are also (and must be) ints

PinMetadata

ManagementKeyMetadata

SlotMetadata

BioMetadata

FascN

FASC-N data structure

Chuid

PivSession

A session with the PIV application.

Functions

check_key_support(version, key_type, pin_policy, ...)

Check if a key type is supported by a specific YubiKey firmware version.

Module Contents

yubikit.piv.PublicKey
yubikit.piv.PrivateKey
class yubikit.piv.ALGORITHM[source]

Bases: str, enum.Enum

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

EC = 'ec'
RSA = 'rsa'
class yubikit.piv.KEY_TYPE[source]

Bases: enum.IntEnum

Enum where members are also (and must be) ints

RSA1024 = 6
RSA2048 = 7
RSA3072 = 5
RSA4096 = 22
ECCP256 = 17
ECCP384 = 20
ED25519 = 224
X25519 = 225
__str__()[source]

Return str(self).

property algorithm: ALGORITHM
Return type:

ALGORITHM

property bit_len: int
Return type:

int

classmethod from_public_key(key)[source]
Parameters:

key (PublicKey)

Return type:

KEY_TYPE

class yubikit.piv.MANAGEMENT_KEY_TYPE[source]

Bases: enum.IntEnum

Enum where members are also (and must be) ints

TDES = 3
AES128 = 8
AES192 = 10
AES256 = 12
property key_len: int
Return type:

int

property challenge_len: int
Return type:

int

yubikit.piv.SLOT_CARD_MANAGEMENT = 155
yubikit.piv.SLOT_OCC_AUTH = 150
class yubikit.piv.SLOT[source]

Bases: enum.IntEnum

Enum where members are also (and must be) ints

AUTHENTICATION = 154
SIGNATURE = 156
KEY_MANAGEMENT = 157
CARD_AUTH = 158
RETIRED1 = 130
RETIRED2 = 131
RETIRED3 = 132
RETIRED4 = 133
RETIRED5 = 134
RETIRED6 = 135
RETIRED7 = 136
RETIRED8 = 137
RETIRED9 = 138
RETIRED10 = 139
RETIRED11 = 140
RETIRED12 = 141
RETIRED13 = 142
RETIRED14 = 143
RETIRED15 = 144
RETIRED16 = 145
RETIRED17 = 146
RETIRED18 = 147
RETIRED19 = 148
RETIRED20 = 149
ATTESTATION = 249
__str__()[source]

Return str(self).

Return type:

str

class yubikit.piv.OBJECT_ID[source]

Bases: enum.IntEnum

Enum where members are also (and must be) ints

CAPABILITY = 6275335
CHUID = 6275330
AUTHENTICATION = 6275333
FINGERPRINTS = 6275331
SECURITY = 6275334
FACIAL = 6275336
PRINTED = 6275337
SIGNATURE = 6275338
KEY_MANAGEMENT = 6275339
CARD_AUTH = 6275329
DISCOVERY = 126
KEY_HISTORY = 6275340
IRIS = 6275361
RETIRED1 = 6275341
RETIRED2 = 6275342
RETIRED3 = 6275343
RETIRED4 = 6275344
RETIRED5 = 6275345
RETIRED6 = 6275346
RETIRED7 = 6275347
RETIRED8 = 6275348
RETIRED9 = 6275349
RETIRED10 = 6275350
RETIRED11 = 6275351
RETIRED12 = 6275352
RETIRED13 = 6275353
RETIRED14 = 6275354
RETIRED15 = 6275355
RETIRED16 = 6275356
RETIRED17 = 6275357
RETIRED18 = 6275358
RETIRED19 = 6275359
RETIRED20 = 6275360
ATTESTATION = 6291201
classmethod from_slot(slot)[source]
Parameters:

slot (SLOT)

Return type:

OBJECT_ID

class yubikit.piv.PIN_POLICY[source]

Bases: enum.IntEnum

Enum where members are also (and must be) ints

DEFAULT = 0
NEVER = 1
ONCE = 2
ALWAYS = 3
MATCH_ONCE = 4
MATCH_ALWAYS = 5
class yubikit.piv.TOUCH_POLICY[source]

Bases: enum.IntEnum

Enum where members are also (and must be) ints

DEFAULT = 0
NEVER = 1
ALWAYS = 2
CACHED = 3
yubikit.piv.DEFAULT_MANAGEMENT_KEY = b'\x01\x02\x03\x04\x05\x06\x07\x08\x01\x02\x03\x04\x05\x06\x07\x08\x01\x02\x03\x04\x05\x06\x07\x08'
yubikit.piv.PIN_LEN = 8
yubikit.piv.TEMPORARY_PIN_LEN = 16
yubikit.piv.INS_VERIFY = 32
yubikit.piv.INS_CHANGE_REFERENCE = 36
yubikit.piv.INS_RESET_RETRY = 44
yubikit.piv.INS_GENERATE_ASYMMETRIC = 71
yubikit.piv.INS_AUTHENTICATE = 135
yubikit.piv.INS_GET_DATA = 203
yubikit.piv.INS_PUT_DATA = 219
yubikit.piv.INS_MOVE_KEY = 246
yubikit.piv.INS_GET_METADATA = 247
yubikit.piv.INS_ATTEST = 249
yubikit.piv.INS_SET_PIN_RETRIES = 250
yubikit.piv.INS_RESET = 251
yubikit.piv.INS_GET_VERSION = 253
yubikit.piv.INS_IMPORT_KEY = 254
yubikit.piv.INS_SET_MGMKEY = 255
yubikit.piv.TAG_AUTH_WITNESS = 128
yubikit.piv.TAG_AUTH_CHALLENGE = 129
yubikit.piv.TAG_AUTH_RESPONSE = 130
yubikit.piv.TAG_AUTH_EXPONENTIATION = 133
yubikit.piv.TAG_GEN_ALGORITHM = 128
yubikit.piv.TAG_OBJ_DATA = 83
yubikit.piv.TAG_OBJ_ID = 92
yubikit.piv.TAG_CERTIFICATE = 112
yubikit.piv.TAG_CERT_INFO = 113
yubikit.piv.TAG_DYN_AUTH = 124
yubikit.piv.TAG_LRC = 254
yubikit.piv.TAG_PIN_POLICY = 170
yubikit.piv.TAG_TOUCH_POLICY = 171
yubikit.piv.TAG_METADATA_ALGO = 1
yubikit.piv.TAG_METADATA_POLICY = 2
yubikit.piv.TAG_METADATA_ORIGIN = 3
yubikit.piv.TAG_METADATA_PUBLIC_KEY = 4
yubikit.piv.TAG_METADATA_IS_DEFAULT = 5
yubikit.piv.TAG_METADATA_RETRIES = 6
yubikit.piv.TAG_METADATA_BIO_CONFIGURED = 7
yubikit.piv.TAG_METADATA_TEMPORARY_PIN = 8
yubikit.piv.ORIGIN_GENERATED = 1
yubikit.piv.ORIGIN_IMPORTED = 2
yubikit.piv.INDEX_PIN_POLICY = 0
yubikit.piv.INDEX_TOUCH_POLICY = 1
yubikit.piv.INDEX_RETRIES_TOTAL = 0
yubikit.piv.INDEX_RETRIES_REMAINING = 1
yubikit.piv.PIN_P2 = 128
yubikit.piv.PUK_P2 = 129
yubikit.piv.UV_P2 = 150
class yubikit.piv.PinMetadata[source]
default_value: bool
total_attempts: int
attempts_remaining: int
class yubikit.piv.ManagementKeyMetadata[source]
key_type: MANAGEMENT_KEY_TYPE
default_value: bool
touch_policy: TOUCH_POLICY
class yubikit.piv.SlotMetadata[source]
key_type: KEY_TYPE
pin_policy: PIN_POLICY
touch_policy: TOUCH_POLICY
generated: bool
public_key_encoded: bytes
property public_key
class yubikit.piv.BioMetadata[source]
configured: bool
attempts_remaining: int
temporary_pin: bool
yubikit.piv.BCD_SS = '11010'
yubikit.piv.BCD_FS = '10110'
yubikit.piv.BCD_ES = '11111'
class yubikit.piv.FascN[source]

FASC-N data structure

https://www.idmanagement.gov/docs/pacs-tig-scepacs.pdf

agency_code: int
system_code: int
credential_number: int
credential_series: int
individual_credential_issue: int
person_identifier: int
organizational_category: int
organizational_identifier: int
organization_association_category: int
__bytes__()[source]
classmethod from_bytes(value)[source]
Parameters:

value (bytes)

Return type:

FascN

__str__()[source]
class yubikit.piv.Chuid[source]
buffer_length: int | None = None
fasc_n: FascN
agency_code: bytes | None = None
organizational_identifier: bytes | None = None
duns: bytes | None = None
guid: bytes
expiration_date: datetime.date
authentication_key_map: bytes | None = None
asymmetric_signature: bytes
lrc: int | None = None
__post_init__()[source]
__bytes__()[source]
classmethod from_bytes(value)[source]
Parameters:

value (bytes)

Return type:

Chuid

yubikit.piv.check_key_support(version, key_type, pin_policy, touch_policy, generate=True)[source]

Check if a key type is supported by a specific YubiKey firmware version.

This method will return None if the key (with PIN and touch policies) is supported, or it will raise a NotSupportedError if it is not.

Deprecated:

Use PivSession.check_key_support() instead.

Parameters:
Return type:

None

class yubikit.piv.PivSession(connection, scp_key_params=None)[source]

A session with the PIV application.

Parameters:
protocol
property version: yubikit.core.Version

The version of the PIV application, typically the same as the YubiKey firmware.

Return type:

yubikit.core.Version

property management_key_type: MANAGEMENT_KEY_TYPE

The algorithm of the management key currently in use.

Return type:

MANAGEMENT_KEY_TYPE

reset()[source]

Factory reset the PIV application data.

This deletes all user-data from the PIV application, and resets the default values for PIN, PUK, and management key.

Return type:

None

authenticate(management_key: bytes) → None[source]
authenticate(key_type: MANAGEMENT_KEY_TYPE, management_key: bytes) → None

Authenticate to PIV with management key.

Parameters:

management_key (bytes) – The management key in raw bytes.

set_management_key(key_type, management_key, require_touch=False)[source]

Set a new management key.

Parameters:

  • key_type (MANAGEMENT_KEY_TYPE) – The management key type.

  • management_key (bytes) – The management key in raw bytes.

  • require_touch (bool) – The touch policy.

Return type:

None

verify_pin(pin)[source]

Verify the user by PIN.

Parameters:

pin (str) – The PIN.

Return type:

None

verify_uv(temporary_pin=False, check_only=False)[source]

Verify the user by fingerprint (YubiKey Bio only).

Fingerprint verification will allow usage of private keys which have a PIN policy allowing MATCH. For those using MATCH_ALWAYS, the fingerprint must be verified just prior to using the key, or by first requesting a temporary PIN and then later verifying the PIN just prior to key use.

Parameters:

  • temporary_pin (bool) – Request a temporary PIN for later use within the session.

  • check_only (bool) – Do not verify the user, instead immediately throw an InvalidPinException containing the number of remaining attempts.

Return type:

Optional[bytes]

verify_temporary_pin(pin)[source]

Verify the user via temporary PIN.

Parameters:

pin (bytes) – A temporary PIN previously requested via verify_uv.

Return type:

None

get_pin_attempts()[source]

Get remaining PIN attempts.

Return type:

int

change_pin(old_pin, new_pin)[source]

Change the PIN.

Parameters:

  • old_pin (str) – The current PIN.

  • new_pin (str) – The new PIN.

Return type:

None

change_puk(old_puk, new_puk)[source]

Change the PUK.

Parameters:

  • old_puk (str) – The current PUK.

  • new_puk (str) – The new PUK.

Return type:

None

unblock_pin(puk, new_pin)[source]

Reset PIN with PUK.

Parameters:

  • puk (str) – The PUK.

  • new_pin (str) – The new PIN.

Return type:

None

set_pin_attempts(pin_attempts, puk_attempts)[source]

Set PIN retries for PIN and PUK.

Both PIN and PUK will be reset to default values when this is executed.

Requires authentication with management key and PIN verification.

Parameters:

  • pin_attempts (int) – The PIN attempts.

  • puk_attempts (int) – The PUK attempts.

Return type:

None

get_pin_metadata()[source]

Get PIN metadata.

Return type:

PinMetadata

get_puk_metadata()[source]

Get PUK metadata.

Return type:

PinMetadata

get_management_key_metadata()[source]

Get management key metadata.

Return type:

ManagementKeyMetadata

get_slot_metadata(slot)[source]

Get slot metadata.

Parameters:

slot (SLOT) – The slot to get metadata from.

Return type:

SlotMetadata

get_bio_metadata()[source]

Get YubiKey Bio metadata.

This tells you if fingerprints are enrolled or not, how many fingerprint verification attempts remain, and whether or not a temporary PIN is currently active.

Return type:

BioMetadata

sign(slot, key_type, message, hash_algorithm, padding=None)[source]

Sign message with key.

Requires PIN verification.

Parameters:
Return type:

bytes

decrypt(slot, cipher_text, padding)[source]

Decrypt cipher text.

Requires PIN verification.

Parameters:
Return type:

bytes

calculate_secret(slot, peer_public_key)[source]

Calculate shared secret using ECDH.

Requires PIN verification.

Parameters:
Return type:

bytes

get_object(object_id)[source]

Get object by ID.

Requires PIN verification for protected objects.

Parameters:

object_id (int) – The object identifier.

Return type:

bytes

put_object(object_id, data=None)[source]

Write data to PIV object.

Requires authentication with management key.

Parameters:

  • object_id (int) – The object identifier.

  • data (Optional[bytes]) – The object data.

Return type:

None

get_certificate(slot)[source]

Get certificate from slot.

Parameters:

slot (SLOT) – The slot to get the certificate from.

Return type:

cryptography.x509.Certificate

put_certificate(slot, certificate, compress=False)[source]

Import certificate to slot.

Requires authentication with management key.

Parameters:

  • slot (SLOT) – The slot to import the certificate to.

  • certificate (cryptography.x509.Certificate) – The certificate to import.

  • compress (bool) – If the certificate should be compressed or not.

Return type:

None

delete_certificate(slot)[source]

Delete certificate.

Requires authentication with management key.

Parameters:

slot (SLOT) – The slot to delete the certificate from.

Return type:

None

put_key(slot, private_key, pin_policy=PIN_POLICY.DEFAULT, touch_policy=TOUCH_POLICY.DEFAULT)[source]

Import a private key to slot.

Requires authentication with management key.

Parameters:

  • slot (SLOT) – The slot to import the key to.

  • private_key (PrivateKey) – The private key to import.

  • pin_policy (PIN_POLICY) – The PIN policy.

  • touch_policy (TOUCH_POLICY) – The touch policy.

Return type:

KEY_TYPE

generate_key(slot, key_type, pin_policy=PIN_POLICY.DEFAULT, touch_policy=TOUCH_POLICY.DEFAULT)[source]

Generate private key in slot.

Requires authentication with management key.

Parameters:

  • slot (SLOT) – The slot to generate the private key in.

  • key_type (KEY_TYPE) – The key type.

  • pin_policy (PIN_POLICY) – The PIN policy.

  • touch_policy (TOUCH_POLICY) – The touch policy.

Return type:

PublicKey

attest_key(slot)[source]

Attest key in slot.

Parameters:

slot (SLOT) – The slot where the key has been generated.

Returns:

A X.509 certificate.

Return type:

cryptography.x509.Certificate

move_key(from_slot, to_slot)[source]

Move key from one slot to another.

Requires authentication with management key.

Parameters:

  • from_slot (SLOT) – The slot containing the key to move.

  • to_slot (SLOT) – The new slot to move the key to.

Return type:

None

delete_key(slot)[source]

Delete a key in a slot.

Requires authentication with management key.

Parameters:

slot (SLOT) – The slot containing the key to delete.

Return type:

None

check_key_support(key_type, pin_policy, touch_policy, generate, fips_restrictions=False)[source]

Check if a key type is supported by this YubiKey.

This method will return None if the key (with PIN and touch policies) is supported, or it will raise a NotSupportedError if it is not.

Set the generate parameter to True to check if generating the key is supported (in addition to importing).

Set fips_restrictions to True to apply restrictions based on FIPS status.

Parameters:
Return type:

None