> Markdown version of https://docs.laavat.io/gui/admin/truststore/ from the LAAVAT PKI and Signing Platform documentation. All pages: https://docs.laavat.io/llms.txt # Truststore Management ## Overview The Truststore page lets administrators submit new PEM-encoded CA bundles that back the tenant's mTLS, EST, and provisioning endpoints. Each submission is a **request** that must be approved before the new bundle replaces the live truststore. A truststore holds the CA certificates the platform uses to verify the client certificates presented by callers when they connect over mutual TLS, EST, or the provisioning custom domain. Replacing the active bundle is a sensitive operation, so all changes go through the platform's standard approval flow. > **Tip: Prerequisites** > Truststore management is only relevant if the tenant uses mTLS, EST, or > the provisioning custom domain. If client authentication uses only OAuth > tokens, no truststore configuration is required. --- ## Types The platform manages three distinct truststores, selected by the `truststoreType` field on each request. | Type | Backs | Notes | | --- | --- | --- | | `mtls` | mTLS-protected API endpoints | CA bundle used to verify client certificates on mTLS-protected APIs. | | `est` | EST enrolment endpoints | CA bundle used to verify client certificates on EST enrolment endpoints. | | `provisioning` | Provisioning custom domain | CA bundle used to verify client certificates on the provisioning endpoint. | The list view is tabbed by type, so each truststore is managed in its own tab. The "currently deployed" bundle for a given type is the latest request whose state is `Ready` for that type. --- ## PEM Bundle A truststore request carries one PEM-encoded CA bundle, base64 encoded for JSON transport. Once stored, the bundle can be downloaded again from the request detail view in the GUI for review or backup purposes. ### Bundle Format The PEM bundle is one or more complete chains of trust, each starting from the issuing CA certificate and continuing to the root CA certificate. - **Maximum chain length**: 4 certificates per chain. - **Multiple chains**: Concatenate the chains in the same PEM file. - **No leaf / end-entity certificates**: The bundle is a CA trust list, not a certificate store. ### Supported Algorithms The following algorithms are supported in truststore certificates: - SHA-256 or stronger - RSA-2048 or stronger - ECDSA-256 or ECDSA-384 ### Creating a Request 1. Navigate to **Admin > Truststores**. 2. Select the tab for the truststore type you want to update (`mTLS`, `EST`, or `Provisioning`). 3. Click **New request**. 4. Fill in the request fields: | Field | Required | Description | | --- | --- | --- | | **Name** | Yes | Short request name, e.g. `Operator mTLS roots 2026-Q2`. | | **Description** | No | Detailed info about the truststore change. | | **Truststore type** | Yes | Pre-selected from the tab; one of `mtls`, `est`, `provisioning`. | | **Certificates (PEM bundle)** | Yes | Concatenated CA chains in PEM format, uploaded as a file or pasted into the form. | 5. Submit the request. The platform parses the bundle, counts the certificates, runs validation, and shows the outcome before the request moves to `Pending` approval. > **Warning: Submit complete chains** > Each chain in the bundle must end at a root CA. Incomplete chains will be > flagged by the validation step and should be rejected by approvers. --- ## Approval Flow Truststore changes follow the platform's standard two-person principle. | State | Meaning | | --- | --- | | `Pending` | Request submitted, awaiting approver action. The new bundle is staged but not deployed. | | `Approved` | An approver accepted the request; the new bundle is being deployed. | | `Ready` | Bundle is live; new client connections are validated against the new CA list. | | `Rejected` | An approver rejected the request; the staged bundle is discarded. | | `Cancelled` | The submitter cancelled the request before approval. | --- ## Validation Results When a truststore request is submitted, the platform parses every certificate in the PEM bundle and produces a per-certificate validation summary in the `validationResult` field. The summary is JSON-encoded and is shown to approvers in the request detail view. For each certificate, the validation reports: - **CA flag** — whether the certificate is marked as a CA (Basic Constraints `cA: TRUE`). - **Expiry** — `notBefore` / `notAfter` window; expired or not-yet-valid certificates are flagged. - **Subject** — Distinguished Name (CN, O, etc.) used to identify the certificate in the bundle. The `certificateCount` field shows how many certificates were parsed from the bundle, which approvers can cross-check against what the submitter intended to upload. > **Tip: Compare against the active bundle** > Before approving, compare the submitted bundle to the currently deployed > bundle. The platform stores deployed bundles by type; approvers can verify > that the new bundle adds the intended CAs and does not drop CAs that are > still in use. --- ## Truststore Swap When an approver promotes a request, the new bundle is deployed by a background job. The deployment is not instantaneous — the new bundle becomes active a short time after approval. Promoting one type does not affect the other types. > **Warning: Brief mTLS connection interruption during the swap** > For the `mtls` and `est` truststores, activating the new bundle causes a > brief interruption of mTLS connections to the affected endpoint. Plan the > swap during a maintenance window if continuous connectivity is required. > **Warning: Clients whose CA is removed will stop connecting** > After the swap, any client whose CA has been removed from the new bundle > will fail to complete the TLS handshake. Coordinate with affected clients > before approving a swap that drops CAs. --- ## Approve / Reject To act on a pending request: 1. Open the request from the **Approvals > Truststores** list. 2. Review the request metadata, certificate count, and `validationResult`. 3. Click either: - **Approve** — promotes the staged bundle to live. Deployment is handled by the platform; the request moves to `Approved` and then to `Ready` once the custom domain has been updated. - **Reject** — discards the staged bundle and marks the request as `Rejected`. The submitter must create a new request to retry. If the validation summary shows any certificate failure (not a CA, expired, or otherwise invalid), reject the request and have the submitter rebuild the bundle. --- ## Best Practices > **Warning: Stage CA rollovers** > When rolling over a root CA, submit a bundle that contains **both** the old > and the new root for the overlap period. Drop the old root only after all > clients have moved to the new chain. - **Verify chain completeness.** Each chain in the bundle should end at a root CA. Use `openssl crl2pkcs7 -nocrl -certfile bundle.pem | openssl pkcs7 -print_certs` to inspect chains before uploading. - **Match the CA list to active clients.** Before approving a swap, confirm that every active client's certificate chains back to a CA in the new bundle. - **Use descriptive names and dates.** Include the truststore type and the date in the request name, e.g. `mTLS roots 2026-Q2`. Audit trails are significantly easier to read. - **Coordinate with affected teams.** Changes to a truststore affect every client that connects through the corresponding endpoint. Notify those teams before submitting and approving a swap.