@@ -111,7 +111,7 @@ the root of trust:
111
111
112
112
.. versionadded :: 43.0.0
113
113
114
- .. versionchanged :: 44 .0.0
114
+ .. versionchanged :: 45 .0.0
115
115
Made ``subjects `` optional with the addition of custom extension policies.
116
116
117
117
.. attribute :: subjects
@@ -133,6 +133,11 @@ the root of trust:
133
133
134
134
.. versionadded :: 43.0.0
135
135
136
+ .. versionchanged :: 45.0.0
137
+ ``verification_time `` and ``max_chain_depth `` were deprecated and will be
138
+ removed in version 46.0.0.
139
+ The new ``policy `` property should be used to access these values instead.
140
+
136
141
A ClientVerifier verifies client certificates.
137
142
138
143
It contains and describes various pieces of configurable path
@@ -142,17 +147,11 @@ the root of trust:
142
147
ClientVerifier instances cannot be constructed directly;
143
148
:class: `PolicyBuilder ` must be used.
144
149
145
- .. attribute :: validation_time
146
-
147
- :type: :class: `datetime.datetime `
148
-
149
- The verifier's validation time.
150
-
151
- .. attribute :: max_chain_depth
150
+ .. attribute :: policy
152
151
153
- :type: :class: `int `
152
+ :type: :class: `Policy `
154
153
155
- The verifier's maximum intermediate CA chain depth.
154
+ The policy used by the verifier. Can be used to access verification time, maximum chain depth, etc .
156
155
157
156
.. attribute :: store
158
157
@@ -181,6 +180,12 @@ the root of trust:
181
180
182
181
.. versionadded :: 42.0.0
183
182
183
+ .. versionchanged :: 45.0.0
184
+ ``subject ``, ``verification_time `` and ``max_chain_depth `` were deprecated and will be
185
+ removed in version 46.0.0.
186
+ The new ``policy `` property should be used to access these values instead.
187
+
188
+
184
189
A ServerVerifier verifies server certificates.
185
190
186
191
It contains and describes various pieces of configurable path
@@ -191,23 +196,11 @@ the root of trust:
191
196
ServerVerifier instances cannot be constructed directly;
192
197
:class: `PolicyBuilder ` must be used.
193
198
194
- .. attribute :: subject
195
-
196
- :type: :class: `Subject `
197
-
198
- The verifier's subject.
199
-
200
- .. attribute :: validation_time
201
-
202
- :type: :class: `datetime.datetime `
203
-
204
- The verifier's validation time.
199
+ .. attribute :: policy
205
200
206
- .. attribute :: max_chain_depth
207
-
208
- :type: :class: `int `
201
+ :type: :class: `Policy `
209
202
210
- The verifier's maximum intermediate CA chain depth.
203
+ The policy used by the verifier. Can be used to access verification time, maximum chain depth, etc .
211
204
212
205
.. attribute :: store
213
206
@@ -276,6 +269,20 @@ the root of trust:
276
269
277
270
:returns: A new instance of :class: `PolicyBuilder `
278
271
272
+ .. method :: extension_policies(new_ee_policy, new_ca_policy)
273
+
274
+ .. versionadded :: 45.0.0
275
+
276
+ Sets the EE and CA extension policies for the verifier.
277
+ The default policies used are those returned by :meth: `ExtensionPolicy.webpki_defaults_ee `
278
+ and :meth: `ExtensionPolicy.webpki_defaults_ca `.
279
+
280
+ :param ExtensionPolicy new_ca_policy: The CA extension policy to use.
281
+ :param ExtensionPolicy new_ee_policy: The EE extension policy to use.
282
+
283
+ :returns: A new instance of :class: `PolicyBuilder `
284
+
285
+
279
286
.. method :: build_server_verifier(subject)
280
287
281
288
Builds a verifier for verifying server certificates.
@@ -297,3 +304,185 @@ the root of trust:
297
304
for server verification.
298
305
299
306
:returns: An instance of :class: `ClientVerifier `
307
+
308
+ .. class :: ExtensionPolicy
309
+
310
+ .. versionadded :: 45.0.0
311
+
312
+ ExtensionPolicy provides a set of static methods to construct predefined
313
+ extension policies, and a builder-style interface for modifying them.
314
+
315
+ .. note :: Calling any of the builder methods (:meth:`require_not_present`, :meth:`may_be_present`, or :meth:`require_present`)
316
+ multiple times with the same extension type will raise an exception.
317
+
318
+ .. note :: Currently only the following extension types are supported in the ExtensionPolicy API:
319
+ :class: `~cryptography.x509.AuthorityInformationAccess `,
320
+ :class: `~cryptography.x509.AuthorityKeyIdentifier `,
321
+ :class: `~cryptography.x509.SubjectKeyIdentifier `,
322
+ :class: `~cryptography.x509.KeyUsage `,
323
+ :class: `~cryptography.x509.SubjectAlternativeName `,
324
+ :class: `~cryptography.x509.BasicConstraints `,
325
+ :class: `~cryptography.x509.NameConstraints `,
326
+ :class: `~cryptography.x509.ExtendedKeyUsage `.
327
+
328
+ .. staticmethod :: permit_all()
329
+
330
+ Creates an ExtensionPolicy initialized with a policy that does
331
+ not put any constraints on a certificate's extensions.
332
+ This can serve as a base for a fully custom extension policy.
333
+
334
+ :returns: An instance of :class: `ExtensionPolicy `
335
+
336
+ .. staticmethod :: webpki_defaults_ca()
337
+
338
+ Creates an ExtensionPolicy initialized with a
339
+ CA extension policy based on CA/B Forum guidelines.
340
+
341
+ This is the CA extension policy used by :class: `PolicyBuilder `.
342
+
343
+ :returns: An instance of :class: `ExtensionPolicy `
344
+
345
+ .. staticmethod :: webpki_defaults_ee()
346
+
347
+ Creates an ExtensionPolicy initialized with an
348
+ EE extension policy based on CA/B Forum guidelines.
349
+
350
+ This is the EE extension policy used by :class: `PolicyBuilder `.
351
+
352
+ :returns: An instance of :class: `ExtensionPolicy `
353
+
354
+ .. method :: require_not_present(extension_type)
355
+
356
+ Specifies that the extension identified by `extension_type ` must not be present (must be absent).
357
+
358
+ :param type[ExtensionType] extension_type: The extension_type of the extension that must not be present.
359
+
360
+ :returns: An instance of :class: `ExtensionPolicy `
361
+
362
+ .. method :: may_be_present(extension_type, criticality, validator_cb)
363
+
364
+ Specifies that the extension identified by `extension_type ` is optional.
365
+ If it is present, it must conform to the given criticality constraint.
366
+ An optional validator callback may be provided.
367
+
368
+ If a validator callback is provided, the callback will be invoked
369
+ when :meth: `ClientVerifier.verify ` or :meth: `ServerVerifier.verify ` is called on a verifier
370
+ that uses the extension policy. For details on the callback signature, see :type: `MaybeExtensionValidatorCallback `.
371
+
372
+ :param type[ExtensionType] extension_type: A concrete class derived from :type: `~cryptography.x509.ExtensionType `
373
+ indicating which extension may be present.
374
+ :param Criticality criticality: The criticality of the extension
375
+ :param validator_cb: An optional Python callback to validate the extension value.
376
+ Must accept extensions of type `extension_type `.
377
+ :type validator_cb: :type: `MaybeExtensionValidatorCallback ` or None
378
+
379
+ :returns: An instance of :class: `ExtensionPolicy `
380
+
381
+ .. method :: require_present(extension_type, criticality, validator_cb)
382
+
383
+ Specifies that the extension identified by `extension_type`` must be present
384
+ and conform to the given criticality constraint. An optional validator callback may be provided.
385
+
386
+ If a validator callback is provided, the callback will be invoked
387
+ when :meth: `ClientVerifier.verify ` or :meth: `ServerVerifier.verify ` is called on a verifier
388
+ that uses the extension policy. For details on the callback signature, see :type: `PresentExtensionValidatorCallback `.
389
+
390
+ :param type[ExtensionType] extension_type: A concrete class derived from :type: `~cryptography.x509.ExtensionType `
391
+ indicating which extension is required to be present.
392
+ :param Criticality criticality: The criticality of the extension
393
+ :param validator_cb: An optional Python callback to validate the extension value.
394
+ Must accept extensions of type `extension_type `.
395
+ :type validator_cb: :type: `PresentExtensionValidatorCallback ` or None
396
+
397
+ :returns: An instance of :class: `ExtensionPolicy `
398
+
399
+ .. class :: Criticality
400
+
401
+ .. versionadded :: 45.0.0
402
+
403
+ An enumeration of criticality constraints for certificate extensions.
404
+
405
+ .. attribute :: CRITICAL
406
+
407
+ The extension must be marked as critical.
408
+
409
+ .. attribute :: AGNOSTIC
410
+
411
+ The extension may be marked either as critical or non-critical.
412
+
413
+ .. attribute :: NON_CRITICAL
414
+
415
+ The extension must not be marked as critical.
416
+
417
+ .. class :: Policy
418
+
419
+ .. versionadded :: 45.0.0
420
+
421
+ Represents a policy for certificate verification. Passed to extension validator callbacks and
422
+ accessible via :class: `ClientVerifier ` and :class: `ServerVerifier `.
423
+
424
+ .. attribute :: max_chain_depth
425
+
426
+ The maximum chain depth (as described in :meth: `PolicyBuilder.max_chain_depth `).
427
+
428
+ :type: int
429
+
430
+ .. attribute :: subject
431
+
432
+ The subject used during verification.
433
+ Will be None if the verifier is a :class: `ClientVerifier `.
434
+
435
+ :type: x509.verification.Subject or None
436
+
437
+ .. attribute :: validation_time
438
+
439
+ The validation time.
440
+
441
+ :type: datetime.datetime
442
+
443
+ .. attribute :: extended_key_usage
444
+
445
+ The Extended Key Usage required by the policy.
446
+
447
+ :type: x509.ObjectIdentifier
448
+
449
+ .. attribute :: minimum_rsa_modulus
450
+
451
+ The minimum RSA modulus size required by the policy.
452
+
453
+ :type: int
454
+
455
+ .. type :: MaybeExtensionValidatorCallback
456
+ :canonical: Callable[[Policy, Certificate, Optional[ExtensionType]], None]
457
+
458
+ .. versionadded :: 45.0.0
459
+
460
+
461
+ A Python callback that validates an extension that may or may not be present.
462
+ If the extension is not present, the callback will be invoked with `ext ` set to `None `.
463
+
464
+ To fail the validation, the callback must raise an exception.
465
+
466
+ :param Policy policy: The verification policy.
467
+ :param Certificate certificate: The certificate being verified.
468
+ :param ExtensionType or None extension: The extension value or `None ` if the extension is not present.
469
+
470
+ :returns: An extension validator callback must return `None `.
471
+ If the validation fails, the validator must raise an exception.
472
+
473
+ .. type :: PresentExtensionValidatorCallback
474
+ :canonical: Callable[[Policy, Certificate, ExtensionType], None]
475
+
476
+ .. versionadded :: 45.0.0
477
+
478
+
479
+ A Python callback that validates an extension that must be present.
480
+
481
+ To fail the validation, the callback must raise an exception.
482
+
483
+ :param Policy policy: The verification policy.
484
+ :param Certificate certificate: The certificate being verified.
485
+ :param ExtensionType extension: The extension value.
486
+
487
+ :returns: An extension validator callback must return `None `.
488
+ If the validation fails, the validator must raise an exception.
0 commit comments