Search the documentation
Search the documentation...
SplitSecure documentation

On this page

Procedure · 13 steps

Sign SSH keys with a certificate authority

Create an SSH certificate authority in a threshold vault, add a user principal, and sign a user key into a short-lived certificate 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.

  • 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

  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 SSH certificate authority.
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.

  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.

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 SSH certificate authority named Production SSH.”

Trust the certificate authority on your servers

Now in the Web App
  1. In your vault, open the CA.
  2. 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

  1. Save the key as /etc/ssh/splitsecure_user_ca.pub.

  2. Add this line to /etc/ssh/sshd_config:

    TrustedUserCAKeys /etc/ssh/splitsecure_user_ca.pub
  3. Restart the SSH server. On Debian and Ubuntu, run sudo systemctl restart ssh. On most other distributions, run sudo 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

  1. On the CA’s page, click Add principal.
  2. Click User.
  3. 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

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.

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 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.

Sign a user key

Now in your terminal
  1. 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 run ssh-keygen -t ed25519-sk -O verify-required instead.
  2. Print the public key and copy the line. For the key ssh-keygen creates above, run cat ~/.ssh/id_ed25519.pub. For another key, print its own .pub file, such as ~/.ssh/id_ecdsa.pub or ~/.ssh/id_ed25519_sk.pub.

In the Web App

  1. In your vault, open the principal.
  2. Click Propose certificate. The Mint SSH certificate page opens.
  3. Paste the line under Subject public key.
  4. If the principal lets you choose, set the Certificate lifetime inside the range it shows.
  5. Optionally, under Advanced Options, enter a Reason for access.
  6. Click Propose 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 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.

Now in the Web App

When the vote passes, the proposal page shows the SSH certificate card. Click Download to save certificate-cert.pub.

In your terminal

  1. 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.
  2. Sign in: ssh [email protected]. For a key outside the default names, such as ~/.ssh/deploykey, name it: ssh -i ~/.ssh/deploykey [email protected].

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