From dddbdbda36db25ddf33b4008494d777599eeb22d Mon Sep 17 00:00:00 2001 From: Alexander Scheel Date: Wed, 25 Jan 2023 11:54:14 -0500 Subject: [PATCH] Document setting manual_chain after cross-signing (#18839) Signed-off-by: Alexander Scheel Signed-off-by: Alexander Scheel --- .../docs/secrets/pki/rotation-primitives.mdx | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/website/content/docs/secrets/pki/rotation-primitives.mdx b/website/content/docs/secrets/pki/rotation-primitives.mdx index e0d5e8ffa3..2b83796266 100644 --- a/website/content/docs/secrets/pki/rotation-primitives.mdx +++ b/website/content/docs/secrets/pki/rotation-primitives.mdx @@ -261,6 +261,28 @@ cert and its `ca_chain` value. name parameters from the existing issuer; it merely reuses the same key material. +##### Notes on `manual_chain` + +If an intermediate is cross-signed and imported into the same mount as its +pair, Vault will not detect the cross-signed pairs during automatic chain +building. As a result, leaf issuance will have a chain that only includes +one of these pairs of chains. This is because the leaf issuance's `ca_chain` +parameter copies the value from signing issuer directly, rather than computing +its own copy of the chain. + +To fix this, update the `manual_chain` field on the [issuers](/api-docs/secret/pki#update-issuer) +to include the chains of both pairs. For instance, given `intA` signed by +`rootA` and `intB` signed by `rootB` as its cross-signed version, one +could do the following: + +``` +$ vault patch pki/issuer/intA manual_chain=self,rootA,intB,rootB +$ vault patch pki/issuer/intB manual_chain=self,rootB,intA,rootA +``` + +This will ensure that issuance with either copy of the intermediate reports +the full cross-signed chain when signing leaf certs. + ### Reissuance Primitive The second most common type of rotation primitive. In this scheme, the existing