diff --git a/website/content/api-docs/secret/pki.mdx b/website/content/api-docs/secret/pki.mdx index 08764d4f99..cd280b138d 100644 --- a/website/content/api-docs/secret/pki.mdx +++ b/website/content/api-docs/secret/pki.mdx @@ -3641,6 +3641,20 @@ expiration time. if present). Migration will only occur after `issuer_safety_buffer` has passed since the last successful migration. +- `tidy_revocation_queue` `(bool: false)` - Set to true to remove stale + revocation request entries that haven't been confirmed by any active + node of a performance replication (PR) cluster. Only runs on the active + node of the primary cluster. + +~> Note: this tidy is only applicable on Vault Enterprise. + +- `tidy_cross_cluster_revoked_certs` `(bool: false)` - Set to true to remove + expired, cross-cluster revocation entries. This is the cross-cluster + equivalent of `tidy_revoked_certs`. Only runs on the active node of the + primary cluster. + +~> Note: this tidy is only applicable on Vault Enterprise. + - `safety_buffer` `(string: "")` - Specifies a duration using [duration format strings](/vault/docs/concepts/duration-format) used as a safety buffer to ensure certificates are not expunged prematurely; as an example, this can keep certificates from being removed from the CRL that, due to clock skew, might @@ -3697,68 +3711,15 @@ status endpoint described below. #### Parameters +The below parameters are in addition to the regular parameters accepted by the +[`/pki/tidy` endpoint](#tidy) documented above. + - `enabled` `(bool: false)` - Specifies whether automatic tidy is enabled or not. - `interval_duration` `(string: "")` - Specifies the duration between automatic tidy operations; note that this is from the end of one operation to the start of the next so the time of the operation itself does not need to be considered. -- `tidy_cert_store` `(bool: false)` - Specifies whether to tidy up the certificate - store. - -- `tidy_revoked_certs` `(bool: false)` - Set to true to remove all invalid and - expired certificates from storage. A revoked storage entry is considered - invalid if the entry is empty, or the value within the entry is empty. If a - certificate is removed due to expiry, the entry will also be removed from the - CRL, and the CRL will be rotated. - -- `tidy_revoked_cert_issuer_associations` `(bool: false)` - Set to true to associate - revoked certificates with their corresponding issuers; this improves the - performance of OCSP and CRL building, by shifting work to a tidy operation - instead. - -- `tidy_expired_issuers` `(bool: false)` - Set to true to automatically remove - expired issuers after the `issuer_safety_buffer` duration has elapsed. We - log the issuer certificate on removal to allow recovery; no keys are removed - during this process. - -~> Note: The default issuer will not be removed even if it has expired and is - past the `issuer_safety_buffer` specified. - -- `tidy_move_legacy_ca_bundle` `(bool: false)` - Set to true to backup any - legacy CA/issuers bundle (from Vault versions earlier than 1.11) to - `config/ca_bundle.bak`. This can be restored with `sys/raw` back to - `config/ca_bundle` if necessary, but won't impact mount startup (as - mounts will attempt to read the latter and do a migration of CA issuers - if present). Migration will only occur after `issuer_safety_buffer` has - passed since the last successful migration. - -- `safety_buffer` `(string: "")` - Specifies a duration using [duration format strings](/vault/docs/concepts/duration-format) - used as a safety buffer to ensure certificates are not expunged prematurely; as an example, this can keep - certificates from being removed from the CRL that, due to clock skew, might - still be considered valid on other hosts. For a certificate to be expunged, - the time must be after the expiration time of the certificate (according to - the local clock) plus the duration of `safety_buffer`. Defaults to `72h`. - -- `issuer_safety_buffer` `(string: "")` - Specifies a duration that issuers - should be kept for, past their `NotAfter` validity period. Defaults to - 365 days as hours (`8760h`). - -- `pause_duration` `(string: "0s")` - Specifies the duration to pause - between tidying individual certificates. This releases the revocation - lock and allows other operations to continue while tidy is running. - This allows an operator to control tidy's resource utilization within - a timespan: the LIST operation will remain in memory, but the space - between reading, parsing, and updates on-disk cert entries will be - increased, decreasing resource utilization. - - Does not affect `tidy_expired_issuers`. - -~> Note: Using too long of a `pause_duration` can result in tidy operations - not concluding during this lifetime! Using too short of a pause duration - (but non-zero) can lead to lock contention. Use [tidy's cancellation](#cancel-tidy) - to stop a running operation after the sleep period is over. - #### Sample Payload ```json @@ -3785,6 +3746,7 @@ This is a read only endpoint that returns information about the current tidy operation, or the most recent if none are currently running. The result includes the following fields: + * `safety_buffer`: the value of this parameter when initiating the tidy operation * `tidy_cert_store`: the value of this parameter when initiating the tidy operation * `tidy_revoked_certs`: the value of this parameter when initiating the tidy operation @@ -3796,6 +3758,15 @@ The result includes the following fields: *Tidying revoked certificates: checking certificate N of TOTAL* * `cert_store_deleted_count`: The number of certificate storage entries deleted * `revoked_cert_deleted_count`: The number of revoked certificate entries deleted +* `missing_issuer_cert_count`: The number of revoked certificates which were missing a valid issuer reference +* `tidy_expired_issuers`: the value of this parameter when initiating the tidy operation +* `issuer_safety_buffer`: the value of this parameter when initiating the tidy operation +* `tidy_move_legacy_ca_bundle`: the value of this parameter when initiating the tidy operation +* `tidy_revocation_queue`: the value of this parameter when initiating the tidy operation +* `revocation_queue_deleted_count`: the number of revocation queue entries deleted +* `tidy_cross_cluster_revoked_certs`: the value of this parameter when initiating the tidy operation +* `cross_revoked_cert_deleted_count`: the number of cross-cluster revoked certificate entries deleted + | Method | Path | | :----- | :----------------- |