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
- Open the Web App (opens the SplitSecure web app).
- In the sidebar, under Vaults, click your threshold vault.
- Click New resource.
- Under Signing & certificates, click X.509 CA.
If you have no seat in this organization, the card reads “You have no seat in this organization.” and you cannot select it.
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.
- Check the details.
- If your Guardian Team lets you choose who gets notified, pick the members under Who to Notify.
- Optionally, enter a Reason for creation.
- Click Propose creation.
The Web App opens the proposal under Requests.
Approve the certificate authority
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.
The CA is in your vault. Its page shows the status Active and a Certificate 1 card. Click Download on that card to save the root certificate, then add it to the trust store of the machines that must trust this CA.
Issue a certificate
On the machine that will use the certificate, create a private key and a certificate signing request (CSR). For example, with OpenSSL:
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
- In your vault, open the CA.
- Click Propose certificate.
- Paste the content of
server.csrunder Certificate signing request (CSR). The page shows its Subject, Subject alternative names and Public key. - Under Validity, choose how long the certificate lasts. The default is 1 year. It can never outlast the CA or exceed 30 years.
- Optionally, open Advanced Settings to change the Key usage and Extended key usage, or to override the CSR’s subject alternative names.
- Optionally, enter a Reason for signing.
- Click Sign certificate.
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.
When the vote passes, the proposal page shows a Signed certificate card.
- Click Download to save
certificate.pem, or Copy to copy it. The file holds the certificate, then its issuing chain up to the root. - Install the file next to
server.keyon your machine.
A client that trusts the root certificate accepts the new certificate.
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.
- In your vault, open the CA.
- Click Create sub-CA.
- 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.
- Click Propose creation.
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.
The sub-CA is at the top level of your vault. It issues certificates through Propose certificate, like any CA.
Have an external issuer sign the CA
Choose this path when a public CA or your existing PKI must sign your SplitSecure CA.
- 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.
- After the vote, open the CA. Its status reads Pending signature.
- 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 keyCertSignin 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.
- On the CA’s page, click Adopt certificate.
- Paste the signed certificate and its issuing chain under Certificate and issuing chain.
- Click Propose creation. The members vote on the device as before.
The CA’s status reads Active. It issues certificates through Propose certificate.
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
- RFC 5280: X.509 certificates (opens in a new tab): Internet X.509 Public Key Infrastructure Certificate and CRL Profile
- SplitSecure plans (opens in a new tab): See the plans and their limits