Add documentation on delta CRLs

Signed-off-by: Alexander Scheel <[email protected]>

website/content/api-docs/secret/pki.mdx

@@ -1104,18 +1104,35 @@ the newer `/pki/issuer/:issuer_ref/crl` path; the latter correctly places the
 PEM-encoded CRL in the `crl` field whereas the former incorrectly places it
 in the `certificate` field.
 
+Endpoints with type `complete` are full CRLs containing all revoked
+certificates (as of the time of generation. Endpoints with type `delta`
+contain incremental CRLs on top of the last complete CRL, with any new
+certificates that have been revoked. See the [revocation configuration
+section](#set-crl-configuration) for more information about these options.
+The delta CRL clears when the next complete CRL is rebuilt. Consumers of
+delta CRLs will need to update their client to support fetching the
+corresponding full CRL when it has been regenerated; otherwise, some serial
+numbers may not appear in the local copy of the full CRL if the remote
+complete and delta CRLs has been regenerated.
+
 These are unauthenticated endpoints.
 
 ~> **Note**: As of Vault 1.11.0, these endpoints now serve a [version 2](https://datatracker.ietf.org/doc/html/rfc5280#section-5.1.2.1) CRL response.
 
-| Method | Path                              | Issuer    | Format                                                                            |
-| :----- | :-------------------------------- | :-------- |:----------------------------------------------------------------------------------|
-| `GET`  | `/pki/cert/crl`                   | `default` | JSON                                                                              |
-| `GET`  | `/pki/crl`                        | `default` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") |
-| `GET`  | `/pki/crl/pem`                    | `default` | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") |
-| `GET`  | `/pki/issuer/:issuer_ref/crl`     | Selected  | JSON                                                                              |
-| `GET`  | `/pki/issuer/:issuer_ref/crl/der` | Selected  | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") |
-| `GET`  | `/pki/issuer/:issuer_ref/crl/pem` | Selected  | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") |
+| Method | Path                                    | Issuer    | Format                                                                            | Type     |
+| :----- | :-------------------------------------- | :-------- | :-------------------------------------------------------------------------------- | :------- |
+| `GET`  | `/pki/cert/crl`                         | `default` | JSON                                                                              | Complete |
+| `GET`  | `/pki/crl`                              | `default` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete |
+| `GET`  | `/pki/crl/pem`                          | `default` | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete |
+| `GET`  | `/pki/cert/delta-crl`                   | `default` | JSON                                                                              | Delta    |
+| `GET`  | `/pki/crl/delta`                        | `default` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta    |
+| `GET`  | `/pki/crl/delta/pem`                    | `default` | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta    |
+| `GET`  | `/pki/issuer/:issuer_ref/crl`           | Selected  | JSON                                                                              | Complete |
+| `GET`  | `/pki/issuer/:issuer_ref/crl/der`       | Selected  | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete |
+| `GET`  | `/pki/issuer/:issuer_ref/crl/pem`       | Selected  | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete |
+| `GET`  | `/pki/issuer/:issuer_ref/crl/delta`     | Selected  | JSON                                                                              | Delta    |
+| `GET`  | `/pki/issuer/:issuer_ref/crl/delta/der` | Selected  | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta    |
+| `GET`  | `/pki/issuer/:issuer_ref/crl/delta/pem` | Selected  | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta    |
 
 #### Parameters
 
@@ -2992,7 +3009,9 @@ $ curl \
     "ocsp_disable": false,
     "ocsp_expiry": "12h",
     "auto_rebuild": false,
-    "auto_rebuild_grace_period": "12h"
+    "auto_rebuild_grace_period": "12h",
+    "enable_delta": false,
+    "delta_rebuild_interval": "15m"
   },
   "auth": null
 }
@@ -3025,6 +3044,10 @@ the CRL.
    should not be relied upon for the latest certificate status information,
    and OCSP should be used instead.
 
+~> Note: The periodic function which controls automatic rebuilding of CRLs
+   and delta CRLs only executes once a minute; this prevents high system load
+   but limits the granularity of the temporal options below.
+
 | Method | Path              |
 | :----- | :---------------- |
 | `POST` | `/pki/config/crl` |
@@ -3041,6 +3064,12 @@ the CRL.
   the CRL upon expiry.
 - `auto_rebuild_grace_period` `(string: "12h")` - Grace period before CRL expiry
   to attempt rebuild of CRL. Must be shorter than the CRL expiry period.
+- `enable_delta` `(bool: false)` - Enables or disables building of delta CRLs
+  with up-to-date revocation information, augmenting the last complete CRL.
+  This option requires `auto_rebuild` to also be enabled.
+- `delta_rebuild_interval` `(string: "15m")` - Interval to check for new
+  revocations on, to regenerate the delta CRL. Must be shorter than CRL
+  expiry.
 
 #### Sample Payload
 
@@ -3051,7 +3080,9 @@ the CRL.
   "ocsp_disable": "false",
   "ocsp_expiry": "12h",
   "auto_rebuild": "true",
-  "auto_rebuild_grace_period": "8h"
+  "auto_rebuild_grace_period": "8h",
+  "enable_delta": "true",
+  "delta_rebuild_interval": "10m",
 }
 ```