Basic usage =========== The :mod:`pskc` module implements a simple and efficient API for parsing PSKC files. Opening a PSKC file ------------------- .. module:: pskc Importing data from a PSKC file can be done by instantiating a :class:`PSKC` class:: from pskc import PSKC pskc = PSKC('somefile.pskcxml') .. class:: PSKC(filename) The :class:`PSKC` class is used as a wrapper to access information from a PSKC file. The whole file is parsed in one go. Instances of this class provide the following attributes: .. attribute:: version The PSKC format version used. Only version ``1.0`` is currently specified in `RFC6030 `__. .. attribute:: id A unique identifier for the container. .. attribute:: keys A list of :class:`pskc.key.Key` instances that represent the keys within the PSKC file. .. attribute:: encryption Instance of the :class:`pskc.encryption.Encryption` class that handles PSKC file encryption. .. attribute:: mac Instance of the :class:`pskc.mac.MAC` class that handles integrity checking. Examining keys -------------- .. module:: pskc.key The :attr:`pskc.PSKC.keys` attribute provides access to the keys contained in the PSKC file. Instances of the :class:`Key` class provide access to a number of attributes that provide information on the transmitted keys:: pskc = PSKC('somefile.pskcxml') first_key = pskc.keys[0] Attribute values will be ``None`` if it the value is not present in the PSKC file. .. class:: Key() .. attribute:: id A unique identifier for the key. If there are multiple interactions with the same key in multiple instances of PSKC files the `id` is supposed to remain the same. .. attribute:: algorithm A URI that identifies the PSKC algorithm profile. The algorithm profile associates specific semantics to the key. Some `known profiles `__ are: * ``urn:ietf:params:xml:ns:keyprov:pskc:pin``: `Symmetric static credential comparison `_ * ``urn:ietf:params:xml:ns:keyprov:pskc:hotp``: `OATH event-based OTP `_ * ``urn:ietf:params:xml:ns:keyprov:pskc#totp`` or ``urn:ietf:params:xml:ns:keyprov:pskc:totp``: `OATH time-based OTP `_ * ``urn:ietf:params:xml:ns:keyprov:pskc#OCRA-1``: `OATH challenge-response algorithm `_ .. attribute:: secret The binary value of the transported secret key. If the key information is encrypted in the PSKC file it is transparently decrypted if possible. .. attribute:: counter The event counter for event-based OTP algorithms. .. attribute:: time_offset The time offset offset for time-based OTP algorithms. If time intervals are used it carries the number of time intervals passed from an algorithm-dependent start point. .. attribute:: time_interval The time interval in seconds for time-based OTP algorithms (usually ``30`` or ``60``). .. attribute:: time_drift For time-based OTP algorithms this contains the device clock drift in number of intervals. .. attribute:: issuer The name of the party that issued the key. This may be different from the :attr:`manufacturer` of the device. .. attribute:: key_profile A reference to a pre-shared key profile agreed upon between the sending and receiving parties. The profile information itself is not transmitted within the container. See `RFC6030 `__. .. attribute:: key_reference A reference to an external key that is not contained within the PSKC file (e.g., a PKCS #11 key label). If this attribute is present, the :attr:`secret` attribute will generally be missing. .. attribute:: friendly_name A human-readable name for the secret key. .. attribute:: key_userid The distinguished name of the user associated with the key. Also see :attr:`device_userid`. .. attribute:: manufacturer The name of the manufacturer of the device to which the key is provisioned. `RFC6030 `__ prescribes that the value is of the form ``oath.prefix`` for `OATH Manufacturer Prefixes `_ or ``iana.organisation`` for `IANA Private Enterprise Numbers `_ however, it is generally just a string. The value may be different from the :attr:`issuer` of the key on the device. .. attribute:: serial The serial number of the device to which the key is provisioned. Together with :attr:`manufacturer` (and perhaps :attr:`issue_no`) this should uniquely identify the device. .. attribute:: model A manufacturer specific description of the model of the device. .. attribute:: issue_no The issue number in case there are devices with the same :attr:`serial` number so that they can be distinguished by different issue numbers. .. attribute:: device_binding Reference to a device identifier (e.g. IMEI) that allows a provisioning server to ensure that the key is going to be loaded into a specific device. .. attribute:: start_date :class:`datetime.datetime` value that indicates that the device should only be used after this date. .. attribute:: expiry_date :class:`datetime.datetime` value that indicates that the device should only be used before this date. Systems should not rely upon the device to enforce key usage date restrictions, as some devices do not have an internal clock. .. attribute:: device_userid The distinguished name of the user associated with the device. Also see :attr:`key_userid`. .. attribute:: crypto_module Implementation specific unique identifier of the cryptographic module on the device to which the keys have been (or will be) provisioned. .. attribute:: algorithm_suite Additional algorithm specific characteristics. For example, in an HMAC-based algorithm it could designate the hash algorithm used (SHA1 or SHA256). .. attribute:: challenge_encoding Encoding of the challenge accepted by the device for challenge-response authentication. One of: * ``DECIMAL``: only numerical digits * ``HEXADECIMAL``: hexadecimal * ``ALPHANUMERIC``: all letters and numbers (case sensitive) * ``BASE64``: base-64 encoded * ``BINARY``: binary data .. attribute:: challenge_min_length The minimum size of the challenge accepted by the device. .. attribute:: challenge_max_length The maximum size of the challenge accepted by the device. .. attribute:: challenge_check Boolean that indicates whether the device will check an embedded `Luhn check digit `_ contained in the challenge. .. attribute:: response_encoding Format of the response that is generated by the device. If must be one of the values as described under :attr:`challenge_encoding`. .. attribute:: response_length The length of the response generated by the device. .. attribute:: response_check Boolean that indicates whether the device will append a `Luhn check digit `_ to the response. .. attribute:: policy Instance of :class:`pskc.policy.Policy` that provides key and PIN policy information. See :doc:`policy`. .. function:: check() Check if any MACs in the key data embedded in the PSKC file are valid. Will return a boolean or ``None`` if no MACs are defined for the key. See :doc:`mac`.