Key usage policy

The PSKC format allows for specifying key and pin usage policy per key.

Instances of the Policy class provide attributes that describe limits that are placed on key usage and requirements for key PIN protection:

>>> key = pskc.keys[0]
>>> key.policy.may_use(key.policy.KEY_USE_OTP)
True

The Policy class

class pskc.policy.Policy

start_date

datetime.datetime value that indicates that the key must not be used before this date.

expiry_date

datetime.datetime value that indicates that the key must not be used after this date. Systems should not rely upon the device to enforce key usage date restrictions, as some devices do not have an internal clock.

number_of_transactions

The value indicates the maximum number of times a key carried within the PSKC document may be used by an application after having received it.

key_usage

A list of valid usage scenarios for the key that the recipient should check against the intended usage of the key. Also see may_use() and Key usage constants below.

pin_key_id

The unique id of the key within the PSKC file that contains the value of the PIN that protects this key.

pin_key

Instance of the Key (if any) that contains the value of the PIN referenced by pin_key_id.

pin

PIN value referenced by pin_key_id (if any). The value is transparently decrypted if possible.

pin_usage

Describe how the PIN is used during the usage of the key. See Pin usage constants below.

pin_max_failed_attempts

The maximum number of times the PIN may be entered wrongly before it MUST NOT be possible to use the key any more.

pin_min_length

The minimum length of a PIN that can be set to protect the associated key.

pin_max_length

The maximum length of a PIN that can be set to protect this key.

pin_encoding

The encoding of the PIN which is one of DECIMAL, HEXADECIMAL, ALPHANUMERIC, BASE64, or BINARY (see challenge_encoding).

unknown_policy_elements

Boolean that is set to True if the PSKC policy information contains unknown or unsupported definitions or values. A conforming implementation must assume that key usage is not permitted if this value is True to ensure that the lack of understanding of certain extensions does not lead to unintended key usage.

may_use(usage=None, now=None)

Check whether the key may be used for the provided purpose. The key start_date and expiry_date are also checked. The now argument can be used to specify another point in time to check against.

Key usage constants

The Policy class provides the following key use constants (see key_usage and may_use()):

Policy.KEY_USE_OTP = 'OTP'

Key is used for OTP generation.

Policy.KEY_USE_CR = 'CR'

The key is used for challenge-response purposes.

Policy.KEY_USE_ENCRYPT = 'Encrypt'

The key is used for data encryption purposes.

Policy.KEY_USE_INTEGRITY = 'Integrity'

The key is used to generate a keyed message digest for data integrity or authentication purposes.

Policy.KEY_USE_VERIFY = 'Verify'

The key is used to verify a keyed message digest for data integrity or authentication purposes (this is the opposite of KEY_USE_INTEGRITY).

Policy.KEY_USE_UNLOCK = 'Unlock'

The key is used for an inverse challenge-response in the case where a user has locked the device by entering a wrong PIN too many times (for devices with PIN-input capability).

Policy.KEY_USE_DECRYPT = 'Decrypt'

The key is used for data decryption purposes.

Policy.KEY_USE_KEYWRAP = 'KeyWrap'

The key is used for key wrap purposes.

Policy.KEY_USE_UNWRAP = 'Unwrap'

The key is used for key unwrap purposes.

Policy.KEY_USE_DERIVE = 'Derive'

The key is used with a key derivation function to derive a new key.

Policy.KEY_USE_GENERATE = 'Generate'

The key is used to generate a new key based on a random number and the previous value of the key.

Pin usage constants

The following constants for PIN use are defined in the Policy class (see pin_usage):

Policy.PIN_USE_LOCAL = 'Local'

The PIN is checked locally on the device before allowing the key to be used in executing the algorithm.

Policy.PIN_USE_PREPEND = 'Prepend'

The PIN is prepended to the algorithm response. It must be checked by the party validating the response.

Policy.PIN_USE_APPEND = 'Append'

The PIN is appended to the algorithm response. It must be checked by the party validating the response.

Policy.PIN_USE_ALGORITHMIC = 'Algorithmic'

The PIN is used as part of the algorithm computation.