Skip to content

Commit e8bf6a1

Browse files
authored
x509 Verification: Extension policies documentation. (#11800)
* Add docs related to custom x509 verification extension policies. * Improve naming of extension policy builder methods. * Use single method to set both extension policies. * Slight adjustment to ExtensionPolicy documentation to use x509 spec terms. * Replace some fields on [Client|Server]Verifier with `policy` property. (docs) * Doc updates per PR discussion. * Update versionadded to 45. * Correct order of ca and ee policy args. * Update docs to reflect ExtensionPolicy API changes. * Fix remnants from previous API iteration. * Reflect that properties were deprecated not removed in favor of policy property. * Document which extension types are supported by ExtensionPolicy.
1 parent 3b676cf commit e8bf6a1

File tree

2 files changed

+215
-25
lines changed

2 files changed

+215
-25
lines changed

docs/spelling_wordlist.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ committers
2828
conda
2929
CPython
3030
Cryptanalysis
31+
criticalities
3132
crypto
3233
cryptographic
3334
cryptographically

docs/x509/verification.rst

Lines changed: 214 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ the root of trust:
111111

112112
.. versionadded:: 43.0.0
113113

114-
.. versionchanged:: 44.0.0
114+
.. versionchanged:: 45.0.0
115115
Made ``subjects`` optional with the addition of custom extension policies.
116116

117117
.. attribute:: subjects
@@ -133,6 +133,11 @@ the root of trust:
133133

134134
.. versionadded:: 43.0.0
135135

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+
136141
A ClientVerifier verifies client certificates.
137142

138143
It contains and describes various pieces of configurable path
@@ -142,17 +147,11 @@ the root of trust:
142147
ClientVerifier instances cannot be constructed directly;
143148
:class:`PolicyBuilder` must be used.
144149

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
152151

153-
:type: :class:`int`
152+
:type: :class:`Policy`
154153

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

157156
.. attribute:: store
158157

@@ -181,6 +180,12 @@ the root of trust:
181180

182181
.. versionadded:: 42.0.0
183182

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+
184189
A ServerVerifier verifies server certificates.
185190

186191
It contains and describes various pieces of configurable path
@@ -191,23 +196,11 @@ the root of trust:
191196
ServerVerifier instances cannot be constructed directly;
192197
:class:`PolicyBuilder` must be used.
193198

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
205200

206-
.. attribute:: max_chain_depth
207-
208-
:type: :class:`int`
201+
:type: :class:`Policy`
209202

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

212205
.. attribute:: store
213206

@@ -276,6 +269,20 @@ the root of trust:
276269

277270
:returns: A new instance of :class:`PolicyBuilder`
278271

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+
279286
.. method:: build_server_verifier(subject)
280287

281288
Builds a verifier for verifying server certificates.
@@ -297,3 +304,185 @@ the root of trust:
297304
for server verification.
298305

299306
: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

Comments
 (0)