From a5109badad6a06f0039b033f04439d00e332ea41 Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Tue, 5 May 2026 13:33:50 -0600 Subject: [PATCH 1/5] docs(pki): add multi-intermediate chain guidance and generate-ca flag limitation (DOCS-423) --- .../build-your-chain-of-trust.md | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/build-your-chain-of-trust.md b/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/build-your-chain-of-trust.md index 543b41fd6..b8fc6370e 100644 --- a/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/build-your-chain-of-trust.md +++ b/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/build-your-chain-of-trust.md @@ -113,3 +113,39 @@ Where: * `csr-file-path`: Path to the CSR that was created earlier. Running the command above will create a certificate with the called `example.com`, where clicking the **View Certificate Details** button will show the full certificate chain. + +## Multi-Intermediate PKI Chains + +In some compliance environments you may need a deeper PKI hierarchy, for example: + +```text +Root CA → Intermediate CA 1 → Intermediate CA 2 → Leaf Certificate +``` + +`generate-ca` creates a single Root → Intermediate chain in one step. To build a deeper chain, repeat the intermediate layer manually: + +1. Run `generate-ca` to create the Root CA and the first Intermediate CA (Intermediate 1). +2. Use `generate-pki` to create a second PKI issuer (Intermediate 2) and sign it using Intermediate 1 as the issuing CA. +3. Issue leaf certificates from Intermediate 2. + +### Known Limitation: `--allow-subdomains` and Other Flags + +When `generate-ca` creates the chain internally, it calls `generate-pki` to create the Root and Intermediate issuers. Flags such as `--allow-subdomains` that you pass to `generate-ca` are **not** forwarded to the internal `generate-pki` call. + +> ❗ **Important:** +> +> If your intermediate issuer requires `--allow-subdomains` or similar flags, you must create the intermediate issuer manually using `generate-pki` and pass the flags directly, rather than relying on `generate-ca` to set them automatically. + +For example, to create an intermediate issuer that allows subdomains: + +```shell +akeyless generate-pki \ +--name /My-First-Chain/pki/issuers/intermediate-2/issuer \ +--signer-key-name /My-First-Chain/pki/keys/intermediate-1/key \ +--allowed-domains example.com \ +--allow-subdomains \ +--ttl 10d \ +--gateway-url 'https://:8000' +``` + +Refer to the [CLI Reference — Certificates section](https://docs.akeyless.io/docs/cli-reference-certificates) for the full list of `generate-pki` parameters. From fa70377e028f6a85c3178d5ad000b171b9ce372a Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Tue, 5 May 2026 13:51:06 -0600 Subject: [PATCH 2/5] fix(pki): correct CLI command from generate-pki to create-pki-cert-issuer and fix --gateway-url flag --- .../build-your-chain-of-trust.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/build-your-chain-of-trust.md b/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/build-your-chain-of-trust.md index b8fc6370e..ac43e8910 100644 --- a/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/build-your-chain-of-trust.md +++ b/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/build-your-chain-of-trust.md @@ -125,27 +125,27 @@ Root CA → Intermediate CA 1 → Intermediate CA 2 → Leaf Certificate `generate-ca` creates a single Root → Intermediate chain in one step. To build a deeper chain, repeat the intermediate layer manually: 1. Run `generate-ca` to create the Root CA and the first Intermediate CA (Intermediate 1). -2. Use `generate-pki` to create a second PKI issuer (Intermediate 2) and sign it using Intermediate 1 as the issuing CA. +2. Use `create-pki-cert-issuer` to create a second PKI issuer (Intermediate 2), setting `--signer-key-name` to the key of Intermediate 1 as the issuing CA. 3. Issue leaf certificates from Intermediate 2. ### Known Limitation: `--allow-subdomains` and Other Flags -When `generate-ca` creates the chain internally, it calls `generate-pki` to create the Root and Intermediate issuers. Flags such as `--allow-subdomains` that you pass to `generate-ca` are **not** forwarded to the internal `generate-pki` call. +`generate-ca` does not expose all PKI issuer configuration options. Flags such as `--allow-subdomains` are not available in `generate-ca` and cannot be applied to the issuers it creates. > ❗ **Important:** > -> If your intermediate issuer requires `--allow-subdomains` or similar flags, you must create the intermediate issuer manually using `generate-pki` and pass the flags directly, rather than relying on `generate-ca` to set them automatically. +> If your intermediate issuer requires `--allow-subdomains` or similar options, you must create it manually using `create-pki-cert-issuer` and pass the flags directly, rather than relying on `generate-ca` to set them automatically. For example, to create an intermediate issuer that allows subdomains: ```shell -akeyless generate-pki \ +akeyless create-pki-cert-issuer \ --name /My-First-Chain/pki/issuers/intermediate-2/issuer \ --signer-key-name /My-First-Chain/pki/keys/intermediate-1/key \ --allowed-domains example.com \ --allow-subdomains \ --ttl 10d \ ---gateway-url 'https://:8000' +--gw-cluster-url 'https://:8000' ``` -Refer to the [CLI Reference — Certificates section](https://docs.akeyless.io/docs/cli-reference-certificates) for the full list of `generate-pki` parameters. +Refer to the [CLI Reference — Certificates section](https://docs.akeyless.io/docs/cli-reference-certificates) for the full list of `create-pki-cert-issuer` parameters. From f373e84aed0e8b1c29f70a18b7bc0168f8de7934 Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Tue, 5 May 2026 15:27:40 -0600 Subject: [PATCH 3/5] DOCS-423: add generate-ca limitation note to manual chain guide --- .../ca-chain-of-trust-manually.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/ca-chain-of-trust-manually.md b/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/ca-chain-of-trust-manually.md index a48949db7..08c2a78b7 100644 --- a/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/ca-chain-of-trust-manually.md +++ b/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/ca-chain-of-trust-manually.md @@ -125,6 +125,14 @@ The next step will be the creation of an **Intermediate Signer Key** with a sign Intermediate certificates act as a middle-man between the secure root certificates and the server certificates distributed to the public. While a chain will always include at least one intermediate certificate, it may contain multiple ones as well. +### If You Started with `generate-ca` + +If you used `generate-ca` as an initial bootstrap, continue this manual flow to add additional intermediate layers. + +`generate-ca` creates a single Root → Intermediate chain in one step and does not expose all PKI issuer options. For example, flags such as `--allow-subdomains` must be set manually on `create-pki-cert-issuer`. + +For full details, see [Build Your Chain of Trust](https://docs.akeyless.io/docs/build-your-chain-of-trust#multi-intermediate-pki-chains). + ### Create an Intermediate Signer Key Run the following command to create a **CSR** and a **Key** that will be used as our **Intermediate Signer Key**: From f53a2f437fdacf06c8e8620430b69559bae00c45 Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Tue, 5 May 2026 15:29:15 -0600 Subject: [PATCH 4/5] DOCS-423: tighten chain-of-trust docs consistency and wording --- .../build-your-chain-of-trust.md | 8 ++++---- .../ca-chain-of-trust-manually.md | 5 ++--- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/build-your-chain-of-trust.md b/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/build-your-chain-of-trust.md index ac43e8910..23d0e96d6 100644 --- a/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/build-your-chain-of-trust.md +++ b/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/build-your-chain-of-trust.md @@ -26,7 +26,7 @@ The certificate chain includes the following components: The whole chain of trust can be generated using one dedicated CLI command, which automatically creates: -* **Root** and **Intermediate**PKI Issuers. +* **Root** and **Intermediate** PKI Issuers. * **Signer key** with a signed certificate for each issuer which includes the following parameters: @@ -65,7 +65,7 @@ Running the command above will create a **Certificate Chain** under **/My-First- > ✅ **Tip:** > -> The `pathlen` value can be change by using the `--max-path-len` flag. +> You can change the `pathlen` value by using the `--max-path-len` flag. You can find the complete list of parameters for this command in the [CLI Reference - Certificates section.](https://docs.akeyless.io/docs/cli-reference-certificates#chain-of-trust) @@ -112,7 +112,7 @@ Where: * `csr-file-path`: Path to the CSR that was created earlier. -Running the command above will create a certificate with the called `example.com`, where clicking the **View Certificate Details** button will show the full certificate chain. +Running the command above will create a certificate with the `example.com` Common Name. Clicking **View Certificate Details** shows the full certificate chain. ## Multi-Intermediate PKI Chains @@ -141,7 +141,7 @@ For example, to create an intermediate issuer that allows subdomains: ```shell akeyless create-pki-cert-issuer \ --name /My-First-Chain/pki/issuers/intermediate-2/issuer \ ---signer-key-name /My-First-Chain/pki/keys/intermediate-1/key \ +--signer-key-name /My-First-Chain/pki/keys/intermediate/key \ --allowed-domains example.com \ --allow-subdomains \ --ttl 10d \ diff --git a/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/ca-chain-of-trust-manually.md b/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/ca-chain-of-trust-manually.md index 08c2a78b7..9e46a45f7 100644 --- a/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/ca-chain-of-trust-manually.md +++ b/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/ca-chain-of-trust-manually.md @@ -74,7 +74,6 @@ Where: * `name`: A unique name for the DFC Key. The name can include a path to the virtual folder where you want to create a new DFC Key using the slash / separators. If the folder does not exist, it will be created together with the item. * `alg`: DFC Key type, options: `AES128GCM`, `AES256GCM`, `AES128SIV`, `AES256SIV`, `AES128CBC`, `AES256CBC`, `RSA1024`, `RSA2048`, `RSA3072`, `RSA4096`. - . * `generate-self-signed-certificate`: Whether to generate a self signed certificate with the key. If set, `--certificate-ttl` must be provided. @@ -115,7 +114,7 @@ At this point, we have created the following: * **Root CA Key**: A Signer Key with a Self Signed Certificate. * **Root PKI Cert Issuer**: To sign new Intermediate CA. -Where **only** certificates with the domain `example.com` will be accepted and valid for 100 days, they will be automatically stored under the `/MyChain/IntermediateCertificates/` folder, with basic constraints of `CA: TRUE` and the mentioned **KeyUsage**, **OU**, and **Location** settings as defined in the issuer. An event about the upcoming expiration will be triggered 30 days before expiration. +Where **only** certificates with the domain `example.com` will be accepted and valid for 100 days, they will be automatically stored under the `/Chain/Intermediate/Certificates` folder, with basic constraints of `CA: TRUE` and the mentioned **KeyUsage**, **OU**, and **Location** settings as defined in the issuer. An event about the upcoming expiration will be triggered 30 days before expiration. You can find the complete list of parameters for this command in the [CLI Reference - Certificates](https://docs.akeyless.io/docs/cli-reference-certificates#create-pki-cert-issuer) section. @@ -186,7 +185,7 @@ akeyless create-pki-cert-issuer \ --locality NY ``` -Where **only** certificates with the domain `myexample.com` will be accepted and valid for 30 days, and they will be automatically stored under the `/MyChain/Intermediate/Leaf/` folder, with the **Extended Key Usage** of `client auth`, **OU**, and **Location** settings as defined in the issuer. An event about the upcoming expiration will be triggered 30 days before expiration. +Where **only** certificates with the domain `myexample.com` will be accepted and valid for 30 days, and they will be automatically stored under the `/MyChain/Intermediate/Leaf/` folder, with the **Extended Key Usage** of `client auth`, **OU**, and **Location** settings as defined in the issuer. An event about the upcoming expiration will be triggered 10 days before expiration. > ℹ️ **Note:** > From 2935343f97c1f7bca676a4a3a8baa0d1381424a7 Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Tue, 5 May 2026 15:31:09 -0600 Subject: [PATCH 5/5] DOCS-423: fix multi-intermediate signer-key flow accuracy --- .../build-your-chain-of-trust.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/build-your-chain-of-trust.md b/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/build-your-chain-of-trust.md index 23d0e96d6..001f9949e 100644 --- a/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/build-your-chain-of-trust.md +++ b/docs/Certificate Lifecycle Management/ssh-and-pkitls-certificates/build-your-chain-of-trust.md @@ -125,8 +125,10 @@ Root CA → Intermediate CA 1 → Intermediate CA 2 → Leaf Certificate `generate-ca` creates a single Root → Intermediate chain in one step. To build a deeper chain, repeat the intermediate layer manually: 1. Run `generate-ca` to create the Root CA and the first Intermediate CA (Intermediate 1). -2. Use `create-pki-cert-issuer` to create a second PKI issuer (Intermediate 2), setting `--signer-key-name` to the key of Intermediate 1 as the issuing CA. -3. Issue leaf certificates from Intermediate 2. +2. Create an Intermediate 2 signer key and CSR, then sign that CSR using the Intermediate 1 issuer. +3. Attach the signed certificate to the Intermediate 2 signer key. +4. Use `create-pki-cert-issuer` to create a second PKI issuer (Intermediate 2), setting `--signer-key-name` to the Intermediate 2 signer key. +5. Issue leaf certificates from Intermediate 2. ### Known Limitation: `--allow-subdomains` and Other Flags @@ -139,11 +141,15 @@ Root CA → Intermediate CA 1 → Intermediate CA 2 → Leaf Certificate For example, to create an intermediate issuer that allows subdomains: ```shell +# Prerequisite: /My-First-Chain/pki/keys/intermediate-2/key already exists +# and has a certificate signed by /My-First-Chain/pki/issuers/intermediate/issuer. + akeyless create-pki-cert-issuer \ --name /My-First-Chain/pki/issuers/intermediate-2/issuer \ ---signer-key-name /My-First-Chain/pki/keys/intermediate/key \ +--signer-key-name /My-First-Chain/pki/keys/intermediate-2/key \ --allowed-domains example.com \ --allow-subdomains \ +--is-ca true \ --ttl 10d \ --gw-cluster-url 'https://:8000' ```