Search the documentation
Search the documentation...
SplitSecure documentation

On this page

Procedure · 12 steps

Issue certificates from an X.509 CA

Create an X.509 certificate authority in a threshold vault, then issue certificates and sub-CAs that your Guardian Team approves.

Updated

Before you start

  • A Basic or Guardian seat, on any plan. The members who vote need a Guardian seat.

  • The SplitSecure mobile app, set up and signed in to the same account as the Web App. See Set up your device and browser.

  • A Guardian Team, the group of devices that together approve each proposal, formed and usable. See Form your Guardian Team.

  • Use or Edit access to a vault backed by that Guardian Team. Forming a Guardian Team creates one, named after the team.

An X.509 certificate authority (CA) signs the certificates your servers and clients present, for example for TLS. In SplitSecure, the CA’s private key lives in a threshold vault and never leaves it. Your Guardian Team, the group of devices that together approve each proposal, votes on the CA’s creation and on every certificate it issues.

Passkeys, X.509 CAs, SSH principals, signing keys, OpenPGP identities, wallets, secrets and connected apps share one Secrets limit. Each seat adds the allowance your plan sets for its kind. By default, a Guardian seat adds to the limit and a Basic seat adds nothing. An administrator sees the count under Organization → Overview, on the Resource usage card. To make room, delete any of these resources, or add seats of a kind that carries an allowance. See the plans (opens in a new tab).

Create the certificate authority

In the Web App

  1. Open the Web App (opens the SplitSecure web app).
  2. In the sidebar, under Vaults, click your threshold vault.
  3. Click New resource.
  4. Under Signing & certificates, click X.509 CA.

Under Certificate source, keep Self-signed root CA to create a root CA that works at once. Choose Signed by an external issuer if another CA must sign this one: see Have an external issuer sign the CA below.

Field Value
Name Internal root CA Required. The name the Guardian Team sees on the proposal
Description Optional
Common name Acme Corp Root CA Required. The CN of the certificate subject
Organization (O) OptionalAlso Organizational unit (OU), Locality (L), State / province (ST) and Country (C)
Path length constraint OptionalHow many levels of sub-CA may sit below this CA. Empty means no limit. 0 allows no sub-CA
Permitted DNS domains OptionalComma-separated. The CA can only certify these domains
Excluded DNS domains OptionalComma-separated. The CA can never certify these domains
CA key algorithm ECDSA P-256Or ECDSA P-384 or RSA-4096
Validity 10 yearsOr 1 year, 5 years, 20 years or Custom date, up to 30 years

Under Advanced Options, you can turn on Selective notifications and set the Account Sensitivity. Click Continue.

The Review step lists the details, the Location and the Guardian Team under Protected by. The What voters will see box shows the text of the proposal.

  1. Check the details.
  2. If your Guardian Team lets you choose who gets notified, pick the members under Who to Notify.
  3. Optionally, enter a Reason for creation.
  4. Click Propose creation.

The Web App opens the proposal under Requests.

Approve the certificate authority

Now on each member’s device

On each member’s device, the proposal appears under Requests. The member opens it, checks the details, then taps Approve. The proposal passes when the approvals reach the Guardian Team’s threshold.

The proposal reads, for example, “Alice wants to create an X.509 certificate authority named Internal root CA”. Its Certificate authority section shows the Subject, Valid for and, when you set one, the Maximum path length.

The proposal page in the Web App moves through Proposal Published, Collecting Votes, Executing Proposal and Completed.

Issue a certificate

Now in your terminal

On the machine that will use the certificate, create a private key and a certificate signing request (CSR). For example, with OpenSSL:

Shell
openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:P-256 \
  -pkeyopt ec_param_enc:named_curve -nodes \
  -keyout server.key -out server.csr -subj "/CN=app.example.com" \
  -addext "subjectAltName=DNS:app.example.com"

The private key stays on that machine. Only the CSR goes to SplitSecure. If the CA has permitted or excluded DNS domains, repeat the common name as a DNS subject alternative name, as above.

In the Web App

  1. In your vault, open the CA.
  2. Click Propose certificate.
  3. Paste the content of server.csr under Certificate signing request (CSR). The page shows its Subject, Subject alternative names and Public key.
  4. Under Validity, choose how long the certificate lasts. The default is 1 year. It can never outlast the CA or exceed 30 years.
  5. Optionally, open Advanced Settings to change the Key usage and Extended key usage, or to override the CSR’s subject alternative names.
  6. Optionally, enter a Reason for signing.
  7. Click Sign certificate.
Now on each member’s device

On each member’s device, the proposal appears under Requests. The member opens it, checks the details, then taps Approve. The proposal passes when the approvals reach the Guardian Team’s threshold.

The proposal asks to issue an X.509 certificate. Its X.509 certificate section shows the Subject, Valid for, the key usages and the subject alternative names.

Now in the Web App

When the vote passes, the proposal page shows a Signed certificate card.

  1. Click Download to save certificate.pem, or Copy to copy it. The file holds the certificate, then its issuing chain up to the root.
  2. Install the file next to server.key on your machine.

Create a sub-CA

In the Web App

A sub-CA, or intermediate CA, is a CA signed by your CA. Use one to issue certificates for a team or an environment while the root CA stays unused. The Create sub-CA button appears only on an Active CA whose path length is not 0.

  1. In your vault, open the CA.
  2. Click Create sub-CA.
  3. Fill in the Name, the Common name and the other fields, as for the root CA. Validity offers 1 year, 5 years, 10 years or 20 years, with no custom date, and cannot outlast the parent CA. If the parent has a path length limit, the sub-CA needs one too, at least one lower than the parent’s.
  4. Click Propose creation.
Now on each member’s device

On each member’s device, the proposal appears under Requests. The member opens it, checks the details, then taps Approve. The proposal passes when the approvals reach the Guardian Team’s threshold.

The proposal asks to create an X.509 sub-CA.

Have an external issuer sign the CA

Now in the Web App

Choose this path when a public CA or your existing PKI must sign your SplitSecure CA.

  1. Create the CA as above, with Certificate source set to Signed by an external issuer. The wizard then has no Permitted DNS domains, Excluded DNS domains or Validity fields, since the external issuer sets the validity. The proposal asks to create a pending X.509 certificate authority.
  2. After the vote, open the CA. Its status reads Pending signature.
  3. On the Certificate signing request card, click Download CSR, and send the file to the external issuer.

The external issuer must sign a CA certificate that carries:

  • the CA’s own key, from the CSR
  • exactly the subject you approved, with no attribute added or removed
  • basic constraints CA:TRUE
  • keyCertSign in its key usage, if it has a key usage
  • a path length no looser than the one you asked for

The page checks the key, CA:TRUE and that a chain is present. The other checks run after the vote, and a certificate that fails them fails the proposal.

  1. On the CA’s page, click Adopt certificate.
  2. Paste the signed certificate and its issuing chain under Certificate and issuing chain.
  3. Click Propose creation. The members vote on the device as before.

Troubleshooting

Issue Solution
The X.509 CA card cannot be selected You have no seat in this organizationAsk an organization administrator to assign you a seat
“parsing CSR: x509: invalid ECDSA parameters” The key in the CSR names its curve with explicit parameters, as LibreSSL on macOS writes by defaultCreate the key again with -pkeyopt ec_param_enc:named_curve, as in the sample command
“No PEM block found in the provided text” The pasted text is not a PEM-encoded CSRPaste the whole file, from -----BEGIN CERTIFICATE REQUEST----- to the end
A name “is not permitted by the issuing CA’s name constraints” The CSR asks for a domain outside the CA’s permitted domainsUse a domain the CA permits, or another CA
The proposal fails with “must also be presented as a DNS subject alternative name” The CA has DNS name constraints, and the CSR’s common name is not among its subject alternative namesAdd the common name as a DNS subject alternative name in the CSR, or under Advanced Settings
The proposal fails with “validity window … exceeds the maximum allowed” The certificate or CA would last more than 30 yearsChoose a shorter Validity and propose again
“Validity can’t exceed the issuing CA’s expiry.” The certificate would outlast the CAChoose a shorter Validity
Create sub-CA is missing The CA’s path length is 0, or the CA is Pending signatureAdopt the CA’s certificate first, or create the sub-CA from a CA with a higher path length
The adoption fails with “does not match the approved subject attributes” The external issuer changed the subject, for example by adding an organizationAsk the issuer to sign with exactly the subject in the CSR, then adopt the new certificate
Sign certificate is disabled with “Your cert is not signed yet” The CA still waits for its external signatureAdopt the signed certificate first
The CA cannot be deleted It still has active sub-CAsDelete its sub-CAs first
The proposal stays at Collecting Votes The approvals have not reached the threshold yetAsk the Guardian Team members to open Requests on their devices

External resources