# 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.