4
4
The :mod:`pskc` module implements a simple and efficient API for parsing PSKC
5
files. The :class:`~pskc.PSKC` class is used to access the file as a whole
6
which provides access to a list of :class:`~pskc.key.Key` instances which
7
contain most of the useful information from the PSKC file.
13
Importing data from a PSKC file can be done by instantiating a :class:`PSKC`
17
pskc = PSKC('somefile.pskcxml')
19
.. class:: PSKC(filename)
15
Importing data from a PSKC file can be done by instantiating a
16
:class:`~pskc.PSKC` class::
18
>>> from pskc import PSKC
19
>>> pskc = PSKC('somefile.pskcxml')
24
.. class:: PSKC([filename])
21
26
The :class:`PSKC` class is used as a wrapper to access information from a
22
PSKC file. The whole file is parsed in one go. Instances of this class
23
provide the following attributes:
29
The whole file is parsed in one go. Instances of this class provide the
30
following attributes: If parsing the PSKC file fails, a
31
:exc:`~pskc.exceptions.ParseError` exception is raised.
25
33
.. attribute:: version
27
The PSKC format version used. Only version ``1.0`` is currently specified
28
in `RFC6030 <https://tools.ietf.org/html/rfc6030#section-1.2>`__.
35
The PSKC format version used. Only version ``1.0`` is currently
37
`RFC 6030 <https://tools.ietf.org/html/rfc6030#section-1.2>`__
34
44
.. attribute:: keys
36
A list of :class:`pskc.key.Key` instances that represent the keys
46
A list of :class:`~pskc.key.Key` instances that represent the keys
37
47
within the PSKC file.
39
49
.. attribute:: encryption
41
Instance of the :class:`pskc.encryption.Encryption` class that handles
51
:class:`~pskc.encryption.Encryption` instance that handles PSKC file
46
Instance of the :class:`pskc.mac.MAC` class that handles integrity
56
:class:`~pskc.mac.MAC` instance that handles integrity checking.
53
62
.. module:: pskc.key
55
The :attr:`pskc.PSKC.keys` attribute provides access to the keys contained in
56
the PSKC file. Instances of the :class:`Key` class provide access to a number
57
of attributes that provide information on the transmitted keys::
64
The :attr:`~pskc.PSKC.keys` attribute of a :class:`~pskc.PSKC` instance
65
provides access to a list of keys contained in the PSKC file. :class:`Key`
66
instances provide access to a number of attributes that provide information
67
on the transmitted keys::
59
pskc = PSKC('somefile.pskcxml')
60
first_key = pskc.keys[0]
69
>>> pskc = PSKC('somefile.pskcxml')
70
>>> first_key = pskc.keys[0]
73
>>> first_key.algorithm
74
'urn:ietf:params:xml:ns:keyprov:pskc:hotp'
62
78
Attribute values will be ``None`` if it the value is not present in the PSKC
79
file. If any of the :attr:`~pskc.key.Key.secret`,
80
:attr:`~pskc.key.Key.counter`, :attr:`~pskc.key.Key.time_offset`,
81
:attr:`~pskc.key.Key.time_interval` or :attr:`~pskc.key.Key.time_drift`
82
values are accessed while they are encrypted and decryption is unsuccessful a
83
:exc:`~pskc.exceptions.DecryptionError` exception is raised.
91
112
The binary value of the transported secret key. If the key information
92
113
is encrypted in the PSKC file it is transparently decrypted if
114
possible. Accessing the value may raise
115
:exc:`~pskc.exceptions.DecryptionError` if decryption fails.
95
117
.. attribute:: counter
97
The event counter for event-based OTP algorithms.
119
The event counter for event-based OTP algorithms. Will also be
120
transparently decrypted and may also raise
121
:exc:`~pskc.exceptions.DecryptionError`.
99
123
.. attribute:: time_offset
101
125
The time offset offset for time-based OTP algorithms. If time intervals
102
126
are used it carries the number of time intervals passed from an
103
algorithm-dependent start point.
127
algorithm-dependent start point. Will also be transparently decrypted
128
and may also raise :exc:`~pskc.exceptions.DecryptionError`.
105
130
.. attribute:: time_interval
107
132
The time interval in seconds for time-based OTP algorithms (usually
133
``30`` or ``60``). Will also be transparently decrypted and may also
134
raise :exc:`~pskc.exceptions.DecryptionError`.
110
136
.. attribute:: time_drift
112
138
For time-based OTP algorithms this contains the device clock drift in
139
number of intervals. Will also be transparently decrypted and may also
140
raise :exc:`~pskc.exceptions.DecryptionError`.
115
142
.. attribute:: issuer
122
149
A reference to a pre-shared key profile agreed upon between the sending
123
150
and receiving parties. The profile information itself is not
124
151
transmitted within the container.
125
See `RFC6030 <https://tools.ietf.org/html/rfc6030#section-4.4>`__.
152
See `RFC 6030 <https://tools.ietf.org/html/rfc6030#section-4.4>`__.
127
154
.. attribute:: key_reference
142
169
.. attribute:: manufacturer
144
171
The name of the manufacturer of the device to which the key is
145
provisioned. `RFC6030 <https://tools.ietf.org/html/rfc6030#section-4.3.1>`__
173
`RFC 6030 <https://tools.ietf.org/html/rfc6030#section-4.3.1>`__
146
174
prescribes that the value is of the form ``oath.prefix`` for `OATH
147
175
Manufacturer Prefixes <http://www.openauthentication.org/oath-id/prefixes/>`_
148
176
or ``iana.organisation`` for `IANA Private Enterprise Numbers
153
181
.. attribute:: serial
155
183
The serial number of the device to which the key is provisioned.
156
Together with :attr:`manufacturer` (and perhaps :attr:`issue_no`)
157
this should uniquely identify the device.
184
Together with :attr:`manufacturer` (and possibly :attr:`issue_no`) this
185
should uniquely identify the device.
159
187
.. attribute:: model
242
270
.. attribute:: policy
244
Instance of :class:`pskc.policy.Policy` that provides key and PIN
245
policy information. See :doc:`policy`.
272
:class:`~pskc.policy.Policy` instance that provides key and PIN policy
273
information. See :doc:`policy`.
247
275
.. function:: check()
249
277
Check if any MACs in the key data embedded in the PSKC file are valid.
250
Will return a boolean or ``None`` if no MACs are defined for the key.
278
This will return None if there is no MAC to be checked. It will return
279
True if all the MACs match. If any MAC fails a
280
:exc:`~pskc.exceptions.DecryptionError` exception is raised.
added
removed
docs/usage.rst
