Unclear documentation around cert auth CRLs

[bmendric]

Describe the bug Vault docs on certificate auth revocation checking contains the statement:

An authorized user can submit PEM-formatted CRLs identified by a given name; these can be updated or deleted at will. They may also set the URL of a trusted CRL distribution point, and have Vault fetch the CRL as needed.

This makes mention of configuring a CRL by providing a CRL distribution point, however, there is no mention of that configuration within the api docs. Digging in a bit further, we see that there is, in fact, a url configuration option on the CRL creation endpoint.

To Reproduce N/A

Expected behavior Consistent documentation and guidance on publicly available APIs/configuration.

Environment:

• Vault Server Version (retrieve with vault status): 1.12.0
• Vault CLI Version (retrieve with vault version): 1.12.1
• Server Operating System/Architecture: N/A

Vault server configuration file(s): N/A

Additional context Couple of other interesting questions not found in the documentation:

1. With what cadence is the CRL distribution point queried (and thereby the CRL refreshed)? This is particularly interesting since the answer seems to be a combo of the CRL validity period and when the periodicFunc is called, with the CRL validity period being the most interesting as the documentation also mentions:

   In addition, since the method does not fetch the CRLs itself, the CRL's designated time to next update is not considered.

2. Why is the signature of the CRL not validated in either the direct CRL nor distribution point configuration?

3. Why is PEM the only supported format when setting it manually and DER the only support format when the distribution point is queried?

Happy to move these last two to feature requests if necessary.

[bmendric]

Another undocumented parameter I just ran across -- allowed_metadata_extensions

The corresponding config option is also undocumented -- enabled_identity_alias_metadata

[cipherboy]

@bmendric Happy to take docs PRs around this if you'd like to submit one.

Note that the periodic func gets called every minute, so in general it isn't that relevant (compared to the lifetime of the CRL itself).

For 2, I think on the distribution point configuration we could support verifying the CRL signature, but note in general the CRL might be issued from a dedicated CRL signer. Other server applications like nginx/... punt on CRL verification and trust that you've properly verified the CRL before setting it in the config, and Vault is no different.

For 3, I think a feature request is in order for the setting side, but note that DER is the mandated format for distribution point:

When the HTTP or FTP URI scheme is used, the URI MUST point to a single DER encoded CRL as specified in [RFC2585].

[bmendric]

@cipherboy Thanks for the response!

I am quite loaded on work through the end of the year, but can look at submitting a docs PR.

Good to know on the periodic function call

For 2, I think that makes sense in the context of manually setting CRLs (ie. the automation you use to ship the CRL into Vault should be the responsible party for validating the signature). I am less convinced that argument applies when we are asking Vault to retrieve the CRL from a distribution point. In any case, I do agree this should be possible to implement from my medium-level understanding of the cert plugin.

For 3, that is interesting. I was not aware the rfc mandated the DER format. As such, I am fine letting that stand as the manual CRL endpoint does, in fact, support both formats (albeit via the deprecated x509.ParseCRL function)