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.
- Admin access to the servers that will trust the certificates.
An SSH certificate authority (CA) signs short-lived certificates that let people sign in to your servers, so you stop copying public keys into authorized_keys. In SplitSecure, the CA’s private key lives in a threshold vault. Your Guardian Team, the group of devices that together approve each proposal, votes on the CA, on each principal and on every certificate.
The CA signs only through its principals. A principal fixes what its certificates carry: the account name or hostname, how long they last and what they allow.
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 SSH certificate authority.
If you have no seat in this organization, the card reads “You have no seat in this organization.” and you cannot select it.
| Field | Value |
|---|---|
| Name | Production SSHRequired. The name the Guardian Team sees on the proposal |
| Description | Optional |
| Signing key algorithm | Ed25519Or ECDSA P-256, P-384, P-521, or RSA-2048, 3072, 4096. Can’t be changed later |
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.
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 SSH certificate authority named Production SSH.”
The CA is in your vault. Its page shows the CA signing keys card, and Principals appear here with an Add principal button.
Trust the certificate authority on your servers
- In your vault, open the CA.
- On the CA signing keys card, in the key’s Actions column, click the copy icon (Copy OpenSSH public key).
To download the key as a file instead, click SSH trusted CA keys (.pub). On the Export public keys page, click Download.
On each server
Save the key as
/etc/ssh/splitsecure_user_ca.pub.Add this line to
/etc/ssh/sshd_config:TrustedUserCAKeys /etc/ssh/splitsecure_user_ca.pubRestart the SSH server. On Debian and Ubuntu, run
sudo systemctl restart ssh. On most other distributions, runsudo systemctl restart sshd.
From now on, the server accepts a certificate from this CA for any account the certificate names.
Add a user principal
In the Web App
- On the CA’s page, click Add principal.
- Click User.
- Fill in the form, then click Propose principal.
| Field | Value |
|---|---|
| Name | DeployRequired |
| Description | Optional |
| Principal | deployRequired. The account name the servers accept. ${user.email} or ${user.id} builds it from each requester |
| Certificate lifetime | Chosen for each certificateSet a Minimum, Maximum and Default, each from 1 minute to 7 days. Or Same length for every certificate |
| Key ID | Built from each person’s detailsThe server logs the key ID each time a certificate is used |
| Permissions | All checkedTerminal (PTY), Port forwarding, Agent forwarding, X11 forwarding, User rc file |
A fixed principal such as deploy matches the account of the same name. ${user.email} and ${user.id} give each requester their own principal, such as [email protected], or a user ID that starts with s2r:. A Linux account name cannot hold the : of a user ID, and most systems refuse the @ of an email. Map these principals to an account with AuthorizedPrincipalsFile in sshd_config. Once an account has that file, sshd accepts only the principals it lists, so list fixed principals such as deploy there too.
Under Advanced Options, you can set Source addresses, a Forced command, and Require FIDO user verification, and enter a Reason for creation.
A Host principal works the same way, with a Hostname such as *.prod.example.com. Its certificates prove a server’s identity to clients.
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 SSH user principal. Its SSH principal section shows the principal, the certificate lifetime, the key ID, the permissions under Extensions, the source addresses, the forced command, FIDO user verification and the CA signing key.
The principal appears on the CA’s Principals card.
Sign a user key
- If you have no SSH key yet, create one with
ssh-keygen -t ed25519. If the principal requires FIDO user verification, plug in your security key and runssh-keygen -t ed25519-sk -O verify-requiredinstead. - Print the public key and copy the line. For the key
ssh-keygencreates above, runcat ~/.ssh/id_ed25519.pub. For another key, print its own.pubfile, such as~/.ssh/id_ecdsa.pubor~/.ssh/id_ed25519_sk.pub.
In the Web App
- In your vault, open the principal.
- Click Propose certificate. The Mint SSH certificate page opens.
- Paste the line under Subject public key.
- If the principal lets you choose, set the Certificate lifetime inside the range it shows.
- Optionally, under Advanced Options, enter a Reason for access.
- Click Propose 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 SSH user certificate from the principal. Its SSH certificate section shows the principal, the key ID, Valid from, Valid until, the Extensions and the Subject key with its fingerprint.
When the vote passes, the proposal page shows the SSH certificate card. Click Download to save certificate-cert.pub.
In your terminal
- Move the file next to the private key you signed, named after it with
-cert.pub. For~/.ssh/id_ed25519, that is~/.ssh/id_ed25519-cert.pub. For a FIDO key,~/.ssh/id_ed25519_sk, it is~/.ssh/id_ed25519_sk-cert.pub. SSH picks the certificate up with the key of the same name. - Sign in:
ssh [email protected]. For a key outside the default names, such as~/.ssh/deploykey, name it:ssh -i ~/.ssh/deploykey [email protected].
The server accepts the sign-in until the certificate expires. Propose a new certificate when you need access again.
Troubleshooting
| Issue | Solution |
|---|---|
| The card or Add principal is unavailable | You have no seat in this organizationAsk an organization administrator to assign you a seat |
| “Paste a single public key line.” | The field holds several linesPaste only the content of your .pub file |
| The subject public key “cannot be certified” | The key type is not supportedUse an Ed25519, ECDSA or RSA key |
| The RSA key is “under the 2048-bit floor” | The RSA key is too shortUse an RSA key of 2048 bits or more, or an Ed25519 key |
| The subject key “must be a FIDO key” | The principal requires FIDO user verificationCreate a key with ssh-keygen -t ed25519-sk -O verify-required and sign ~/.ssh/id_ed25519_sk.pub |
| The server refuses a FIDO key’s certificate | The key was created without -O verify-requiredCreate the key again with -O verify-required, then propose a new certificate |
| “Choose a lifetime from” a range | The lifetime is outside what the principal allowsChoose a lifetime inside the range |
| The server refuses the certificate | TrustedUserCAKeys is missing, or the account differsCheck the sshd setting, and sign in as the account the principal names |
| 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
- OpenSSH certificates (ssh-keygen manual) (opens in a new tab): The CERTIFICATES section of ssh-keygen(1)
- sshd_config: TrustedUserCAKeys (opens in a new tab): The sshd_config manual
- sshd_config: AuthorizedPrincipalsFile (opens in a new tab): The sshd_config manual