x509 Verification: Extension policies documentation. #11800
Conversation
deivse
changed the title
deivse
force-pushed
the
x509_verification_extension_policy_builder_docs
branch
from
d7c5ebd
to
649dd50
Compare
docs/x509/verification.rst
Outdated
| .. staticmethod:: webpki_defaults_ca() | ||
|
|
||
| Creates an ExtensionPolicyBuilder initialized with a | ||
| CA extension policy based on CA/B Forum guidelines. | ||
|
|
||
| This is the CA extension policy used by :class:`PolicyBuilder`. | ||
|
|
||
| :returns: An instance of :class:`ExtensionPolicyBuilder` | ||
|
|
||
| .. staticmethod:: webpki_defaults_ee() | ||
|
|
||
| Creates an ExtensionPolicyBuilder initialized with an | ||
| EE extension policy based on CA/B Forum guidelines. | ||
|
|
||
| This is the EE extension policy used by :class:`PolicyBuilder`. | ||
|
|
||
| :returns: An instance of :class:`ExtensionPolicyBuilder` |
There was a problem hiding this comment.
@woodruffw right now our extension policies are basically "CABF, but with some things loosened where necessary in practice", is there a good way of articulating that for users?
There was a problem hiding this comment.
@woodruffw right now our extension policies are basically "CABF, but with some things loosened where necessary in practice", is there a good way of articulating that for users?
Sorry, missed this ping originally!
Maybe something like "these extension policies are intended to be strictly consistent with CABF, which dictates the requirements for certificates on the public web. However, we make limited exceptions to CABF where necessary in practice, i.e. behaviors that CABF forbids but are nonetheless present in the current Web PKI."
But maybe that's too much of a mouthful.
There was a problem hiding this comment.
We can put it in a glossary entry or something
There was a problem hiding this comment.
I'm not quite sure how to formulate this as a glossary entry. What would be the entry name? I would appreciate if someone could write out the full text of the entry here (or just made a separate PR for this).
|
Hey, @alex, friendly ping 😄 |
|
Not forgotten! On my TODO list, hopefully this evening. Thanks so much for your patience, and sorry I've been so slow. Don't feel bad about pinging me. |
|
No worries at all, my plate is also very full right now, so I wouldn't have gotten to doing any actual changes before this weekend at the earliest anyways. |
| .. versionchanged:: 44.0.0 | ||
| ``verification_time`` and ``max_chain_depth`` were replaced by the | ||
| ``policy`` property that provides access to these values. | ||
|
|
There was a problem hiding this comment.
We may want to keep these around as proxies, but this isn't terrible important.
| Creates an ExtensionPolicy initialized with a policy that does | ||
| not put any constraints on a certificate's extensions. |
There was a problem hiding this comment.
I'd maybe add a sentence that expresses that this is what you call if you're trying to do something custom.
|
|
||
| :returns: An instance of :class:`ExtensionPolicy` | ||
|
|
||
| .. method:: require_not_present(oid) |
There was a problem hiding this comment.
Do these methods raise an exception if you call them with the same OID multiple times?
There was a problem hiding this comment.
No, not currently. Good catch since this is inconsistent with PolicyBuilder behaviour. It won't be too pretty in code but I would guess API consistency takes precedence here.
Finally coming back with another PR. The idea is that this one will serve to confirm the user-facing API for custom extension policy support, and the next one will have the first parts of the implementation.