1"""
2PKCS#11 constants.
3
4See the Python :mod:`enum` documentation for more information on how to
5use these classes.
6"""
7
8try:
9    from enum import IntEnum, IntFlag, unique
10except ImportError:
11    from aenum import IntEnum, IntFlag, unique
12
13
14DEFAULT = object()
15"""Sentinel value used in templates.
16
17Not all pkcs11 attribute sets are accepted by HSMs.
18Use this value to remove the attribute from the template
19sent to the HSM or to use the HSM default value.
20"""
21
22
23@unique
24class UserType(IntEnum):
25    """PKCS#11 user types."""
26
27    NOBODY = 999
28    """
29    Not officially in the PKCS#11 spec. Used to represent a session that is not
30    logged in.
31    """
32    SO = 0
33    """Security officer."""
34    USER = 1
35
36
37class ObjectClass(IntEnum):
38    """
39    PKCS#11 :class:`Object` class.
40
41    This is the type of object we have.
42    """
43    DATA = 0x00000000
44    CERTIFICATE = 0x00000001
45    """See :class:`pkcs11.Certificate`."""
46    PUBLIC_KEY = 0x00000002
47    """See :class:`pkcs11.PublicKey`."""
48    PRIVATE_KEY = 0x00000003
49    """See :class:`pkcs11.PrivateKey`."""
50    SECRET_KEY = 0x00000004
51    """See :class:`pkcs11.SecretKey`."""
52    HW_FEATURE = 0x00000005
53    DOMAIN_PARAMETERS = 0x00000006
54    """See :class:`pkcs11.DomainParameters`."""
55    MECHANISM = 0x00000007
56    OTP_KEY = 0x00000008
57
58    _VENDOR_DEFINED = 0x80000000
59
60    def __repr__(self):
61        return '<ObjectClass.%s>' % self.name
62
63
64_ARRAY_ATTRIBUTE = 0x40000000
65"""Attribute consists of an array of values."""
66
67
68class Attribute(IntEnum):
69    """
70    PKCS#11 object attributes.
71
72    Not all attributes are relevant to all objects.
73    Relevant attributes for each object type are given in `PKCS #11
74    <http://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/pkcs11-curr-v2.40.html>`_.
75    """
76
77    CLASS = 0x00000000
78    """Object type (:class:`ObjectClass`)."""
79    TOKEN = 0x00000001
80    """
81    If True object will be stored to token.
82    Otherwise has session lifetime (:class:`bool`).
83    """
84    PRIVATE = 0x00000002
85    """
86    True if user must be authenticated to access this object (:class:`bool`).
87    """
88    LABEL = 0x00000003
89    """Object label (:class:`str`)."""
90    APPLICATION = 0x00000010
91    VALUE = 0x00000011
92    """
93    Object value. Usually represents a secret or private key.
94    For certificates this is the complete certificate in the certificate's
95    native format (e.g. BER-encoded X.509 or WTLS encoding).
96
97    May be `SENSITIVE` (:class:`bytes`).
98    """
99    OBJECT_ID = 0x00000012
100    CERTIFICATE_TYPE = 0x00000080
101    """
102    Certificate type (:class:`CertificateType`).
103    """
104    ISSUER = 0x00000081
105    """
106    Certificate issuer in certificate's native format
107    (e.g. X.509 DER-encoding or WTLS encoding) (:class:`bytes`).
108    """
109    SERIAL_NUMBER = 0x00000082
110    """
111    Certificate serial number in certificate's native format
112    (e.g. X.509 DER-encoding) (:class:`bytes`).
113    """
114    AC_ISSUER = 0x00000083
115    """
116    Attribute Certificate Issuer. Different from `ISSUER` because the
117    encoding is different (:class:`bytes`).
118    """
119    OWNER = 0x00000084
120    """
121    Attribute Certificate Owner. Different from `SUBJECT` because the
122    encoding is different (:class:`bytes`).
123    """
124    ATTR_TYPES = 0x00000085
125    """
126    BER-encoding of a sequence of object identifier values corresponding to the
127    attribute types contained in the certificate. When present, this field
128    offers an opportunity for applications to search for a particular attribute
129    certificate without fetching and parsing the certificate itself.
130    """
131    TRUSTED = 0x00000086
132    """
133    This key can be used to wrap keys with `WRAP_WITH_TRUSTED` set;
134    or this certificate can be trusted.
135    (:class:`bool`).
136    """
137    CERTIFICATE_CATEGORY = 0x00000087
138    """
139    Certificate category (:class:`CertificateCategory`).
140    """
141    JAVA_MIDP_SECURITY_DOMAIN = 0x00000088
142    URL = 0x00000089
143    """URL where the complete certificate can be obtained."""
144    HASH_OF_SUBJECT_PUBLIC_KEY = 0x0000008A
145    """Hash of the certificate subject's public key."""
146    HASH_OF_ISSUER_PUBLIC_KEY = 0x0000008B
147    """Hash of the certificate issuer's public key."""
148    CHECK_VALUE = 0x00000090
149    """`VALUE` checksum. Key Check Value (:class:`bytes`)."""
150
151    KEY_TYPE = 0x00000100
152    """Key type (:class:`KeyType`)."""
153    SUBJECT = 0x00000101
154    """
155    Certificate subject in certificate's native format
156    (e.g. X.509 DER-encoding or WTLS encoding) (:class:`bytes`).
157    """
158    ID = 0x00000102
159    """Key ID (bytes)."""
160    SENSITIVE = 0x00000103
161    """
162    Sensitive attributes cannot be retrieved from the HSM
163    (e.g. `VALUE` or `PRIVATE_EXPONENT`) (:class:`bool`).
164    """
165    ENCRYPT = 0x00000104
166    """Key supports encryption (:class:`bool`)."""
167    DECRYPT = 0x00000105
168    """Key supports decryption (:class:`bool`)."""
169    WRAP = 0x00000106
170    """Key supports wrapping (:class:`bool`)."""
171    UNWRAP = 0x00000107
172    """Key supports unwrapping (:class:`bool`)."""
173    SIGN = 0x00000108
174    """Key supports signing (:class:`bool`)."""
175    SIGN_RECOVER = 0x00000109
176    VERIFY = 0x0000010A
177    """Key supports signature verification (:class:`bool`)."""
178    VERIFY_RECOVER = 0x0000010B
179    DERIVE = 0x0000010C
180    """Key supports key derivation (:class:`bool`)."""
181    START_DATE = 0x00000110
182    """Start date for the object's validity (:class:`datetime.date`)."""
183    END_DATE = 0x00000111
184    """End date for the object's validity (:class:`datetime.date`)."""
185    MODULUS = 0x00000120
186    """RSA private key modulus (n) (`biginteger` as :class:`bytes`)."""
187    MODULUS_BITS = 0x00000121
188    """
189    RSA private key modulus length. Use this for private key generation
190    (:class:`int`).
191    """
192    PUBLIC_EXPONENT = 0x00000122
193    """
194    RSA public exponent (e) (`biginteger` as :class:`bytes`).
195
196    Default is b'\1\0\1' (65537).
197    """
198    PRIVATE_EXPONENT = 0x00000123
199    """RSA private exponent (d) (`biginteger` as :class:`bytes`)."""
200    PRIME_1 = 0x00000124
201    """
202    RSA private key prime #1 (p). May not be stored.
203    (`biginteger` as :class:`bytes`).
204    """
205    PRIME_2 = 0x00000125
206    """
207    RSA private key prime #2 (q). May not be stored.
208    (`biginteger` as :class:`bytes`).
209    """
210    EXPONENT_1 = 0x00000126
211    """
212    RSA private key exponent #1 (d mod p-1). May not be stored.
213    (`biginteger` as :class:`bytes`).
214    """
215    EXPONENT_2 = 0x00000127
216    """
217    RSA private key exponent #2 (d mod q-1). May not be stored.
218    (`biginteger` as :class:`bytes`).
219    """
220    COEFFICIENT = 0x00000128
221    """
222    RSA private key CRT coefficient (q^-1 mod p). May not be stored.
223    (`biginteger` as :class:`bytes`).
224    """
225    PRIME = 0x00000130
226    """
227    Prime number 'q' (used for DH).
228    (`biginteger` as :class:`bytes`).
229    """
230    SUBPRIME = 0x00000131
231    """
232    Subprime number 'q' (used for DH).
233    (`biginteger` as :class:`bytes`).
234    """
235    BASE = 0x00000132
236    """
237    Base number 'g' (used for DH).
238    (`biginteger` as :class:`bytes`).
239    """
240
241    PRIME_BITS = 0x00000133
242    SUBPRIME_BITS = 0x00000134
243
244    VALUE_BITS = 0x00000160
245    VALUE_LEN = 0x00000161
246    """
247    `VALUE` length in bytes. Use this for secret key generation
248    (:class:`int`).
249    """
250    EXTRACTABLE = 0x00000162
251    """Key can be extracted wrapped."""
252    LOCAL = 0x00000163
253    """True if generated on the token, False if imported."""
254    NEVER_EXTRACTABLE = 0x00000164
255    """`EXTRACTABLE` has always been False."""
256    ALWAYS_SENSITIVE = 0x00000165
257    """`SENSITIVE` has always been True."""
258    KEY_GEN_MECHANISM = 0x00000166
259    """Key generation mechanism (:class:`pkcs11.mechanisms.Mechanism`)."""
260
261    MODIFIABLE = 0x00000170
262    """Object can be modified (:class:`bool`)."""
263    COPYABLE = 0x00000171
264    """Object can be copied (:class:`bool`)."""
265
266    EC_PARAMS = 0x00000180
267    """
268    DER-encoded ANSI X9.62 Elliptic-Curve domain parameters (:class:`bytes`).
269
270    These can packed using :mod:`pkcs11.util.ec.encode_named_curve_parameters`:
271
272    ::
273
274        from pkcs11.util.ec import encode_named_curve_parameters
275
276        ecParams = encode_named_curve_parameters('secp256r1')
277
278    Or output by OpenSSL:
279
280    ::
281
282        openssl ecparam -outform der -name <curve name> | base64
283
284    """
285
286    EC_POINT = 0x00000181
287    """
288    DER-encoded ANSI X9.62 Public key for :attr:`KeyType.EC` (:class:`bytes`).
289    """
290
291    SECONDARY_AUTH = 0x00000200
292    AUTH_PIN_FLAGS = 0x00000201
293
294    ALWAYS_AUTHENTICATE = 0x00000202
295    """
296    User has to provide pin with each use (sign or decrypt) (:class:`bool`).
297    """
298
299    WRAP_WITH_TRUSTED = 0x00000210
300    """Key can only be wrapped with a `TRUSTED` key."""
301    WRAP_TEMPLATE = (_ARRAY_ATTRIBUTE | 0x00000211)
302    UNWRAP_TEMPLATE = (_ARRAY_ATTRIBUTE | 0x00000212)
303    DERIVE_TEMPLATE = (_ARRAY_ATTRIBUTE | 0x00000213)
304
305    OTP_FORMAT = 0x00000220
306    OTP_LENGTH = 0x00000221
307    OTP_TIME_INTERVAL = 0x00000222
308    OTP_USER_FRIENDLY_MODE = 0x00000223
309    OTP_CHALLENGE_REQUIREMENT = 0x00000224
310    OTP_TIME_REQUIREMENT = 0x00000225
311    OTP_COUNTER_REQUIREMENT = 0x00000226
312    OTP_PIN_REQUIREMENT = 0x00000227
313    OTP_COUNTER = 0x0000022E
314    OTP_TIME = 0x0000022F
315    OTP_USER_IDENTIFIER = 0x0000022A
316    OTP_SERVICE_IDENTIFIER = 0x0000022B
317    OTP_SERVICE_LOGO = 0x0000022C
318    OTP_SERVICE_LOGO_TYPE = 0x0000022D
319
320    GOSTR3410_PARAMS = 0x00000250
321    GOSTR3411_PARAMS = 0x00000251
322    GOST28147_PARAMS = 0x00000252
323
324    HW_FEATURE_TYPE = 0x00000300
325    RESET_ON_INIT = 0x00000301
326    HAS_RESET = 0x00000302
327
328    PIXEL_X = 0x00000400
329    PIXEL_Y = 0x00000401
330    RESOLUTION = 0x00000402
331    CHAR_ROWS = 0x00000403
332    CHAR_COLUMNS = 0x00000404
333    COLOR = 0x00000405
334    BITS_PER_PIXEL = 0x00000406
335    CHAR_SETS = 0x00000480
336    ENCODING_METHODS = 0x00000481
337    MIME_TYPES = 0x00000482
338    MECHANISM_TYPE = 0x00000500
339    REQUIRED_CMS_ATTRIBUTES = 0x00000501
340    DEFAULT_CMS_ATTRIBUTES = 0x00000502
341    SUPPORTED_CMS_ATTRIBUTES = 0x00000503
342    ALLOWED_MECHANISMS = (_ARRAY_ATTRIBUTE | 0x00000600)
343
344    _VENDOR_DEFINED = 0x80000000
345
346    def __repr__(self):
347        return '<Attribute.%s>' % self.name
348
349
350class CertificateType(IntEnum):
351    """
352    Certificate type of a :class:`pkcs11.Certificate`.
353    """
354    X_509 = 0x00000000
355    X_509_ATTR_CERT = 0x00000001
356    WTLS = 0x00000002
357    _VENDOR_DEFINED = 0x80000000
358
359
360@unique
361class MechanismFlag(IntFlag):
362    """
363    Describes the capabilities of a :class:`pkcs11.mechanisms.Mechanism`
364    or :class:`pkcs11.Object`.
365
366    Some objects and mechanisms are symmetric (i.e. can be used for encryption
367    and decryption), some are asymmetric (e.g. public key cryptography).
368    """
369    HW = 0x00000001
370    """Mechanism is performed in hardware."""
371
372    ENCRYPT = 0x00000100
373    """Can be used for encryption."""
374    DECRYPT = 0x00000200
375    """Can be used for decryption."""
376    DIGEST = 0x00000400
377    """Can make a message digest (hash)."""
378    SIGN = 0x00000800
379    """Can calculate digital signature."""
380    SIGN_RECOVER = 0x00001000
381    VERIFY = 0x00002000
382    """Can verify digital signature."""
383    VERIFY_RECOVER = 0x00004000
384    GENERATE = 0x00008000
385    """Can generate key/object."""
386    GENERATE_KEY_PAIR = 0x00010000
387    """Can generate key pair."""
388    WRAP = 0x00020000
389    """Can wrap a key for export."""
390    UNWRAP = 0x00040000
391    """Can unwrap a key for import."""
392    DERIVE = 0x00080000
393    """Can derive a key from another key."""
394
395    EC_F_P = 0x00100000
396    EC_F_2M = 0x00200000
397    EC_ECPARAMETERS = 0x00400000
398    EC_NAMEDCURVE = 0x00800000
399    EC_UNCOMPRESS = 0x01000000
400    EC_COMPRESS = 0x02000000
401
402    EXTENSION = 0x80000000
403
404
405@unique
406class SlotFlag(IntFlag):
407    """:class:`pkcs11.Slot` flags."""
408
409    TOKEN_PRESENT = 0x00000001
410    """
411    A token is present in the slot
412    (N.B. some hardware known not to set this for soft-tokens.)
413    """
414    REMOVABLE_DEVICE = 0x00000002
415    """Removable devices."""
416    HW_SLOT = 0x00000004
417    """Hardware slot."""
418
419
420@unique
421class TokenFlag(IntFlag):
422    """:class:`pkcs11.Token` flags."""
423
424    RNG = 0x00000001
425    """Has random number generator."""
426    WRITE_PROTECTED = 0x00000002
427    """Token is write protected."""
428    LOGIN_REQUIRED = 0x00000004
429    """User must login."""
430    USER_PIN_INITIALIZED = 0x00000008
431    """Normal user's pin is set."""
432
433    RESTORE_KEY_NOT_NEEDED = 0x00000020
434    """
435    If it is set, that means that *every* time the state of cryptographic
436    operations of a session is successfully saved, all keys needed to continue
437    those operations are stored in the state.
438    """
439
440    CLOCK_ON_TOKEN = 0x00000040
441    """
442    If it is set, that means that the token has some sort of clock.  The time
443    on that clock is returned in the token info structure.
444    """
445
446    PROTECTED_AUTHENTICATION_PATH = 0x00000100
447    """
448    If it is set, that means that there is some way for the user to login
449    without sending a PIN through the Cryptoki library itself.
450    """
451
452    DUAL_CRYPTO_OPERATIONS = 0x00000200
453    """
454    If it is true, that means that a single session with the token can perform
455    dual simultaneous cryptographic operations (digest and encrypt; decrypt and
456    digest; sign and encrypt; and decrypt and sign).
457    """
458
459    TOKEN_INITIALIZED = 0x00000400
460    """
461    If it is true, the token has been initialized using C_InitializeToken or an
462    equivalent mechanism outside the scope of PKCS #11.  Calling
463    C_InitializeToken when this flag is set will cause the token to be
464    reinitialized.
465    """
466
467    USER_PIN_COUNT_LOW = 0x00010000
468    """
469    If it is true, an incorrect user login PIN has been entered at least once
470    since the last successful authentication.
471    """
472
473    USER_PIN_FINAL_TRY = 0x00020000
474    """
475    If it is true, supplying an incorrect user PIN will it to become locked.
476    """
477
478    USER_PIN_LOCKED = 0x00040000
479    """
480    If it is true, the user PIN has been locked. User login to the token is not
481    possible.
482    """
483
484    USER_PIN_TO_BE_CHANGED = 0x00080000
485    """
486    If it is true, the user PIN value is the default value set by token
487    initialization or manufacturing, or the PIN has been expired by the card.
488    """
489
490    SO_PIN_COUNT_LOW = 0x00100000
491    """
492    If it is true, an incorrect SO (security officer) login PIN has been
493    entered at least once since the last successful authentication.
494    """
495
496    SO_PIN_FINAL_TRY = 0x00200000
497    """
498    If it is true, supplying an incorrect SO (security officer) PIN will it to
499    become locked.
500    """
501
502    SO_PIN_LOCKED = 0x00400000
503    """
504    If it is true, the SO (security officer) PIN has been locked. SO login to
505    the token is not possible.
506    """
507
508    SO_PIN_TO_BE_CHANGED = 0x00800000
509    """
510    If it is true, the SO PIN value is the default value set by token
511    initialization or manufacturing, or the PIN has been expired by the card.
512    """
513
514    ERROR_STATE = 0x01000000
515