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.

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¶

Navigate to Admin > Truststores.
Select the tab for the truststore type you want to update (mTLS, EST, or Provisioning).
Click New request.

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.

Submit the request. The platform parses the bundle, counts the certificates, runs validation, and shows the outcome before the request moves to Pending approval.

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.

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.

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.

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:

Open the request from the Approvals > Truststores list.
Review the request metadata, certificate count, and validationResult.
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¶

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.