Managing SSH Public Keys#

Users store their SSH public keys on their own account in the client portal. Stored keys can then be selected whenever the user, or an administrator acting on their behalf, reloads the operating system on one of their servers, and they authenticate ISO uploads into a Containerized Console.

Requires SynergyCP 5.5 or newer. Key storage is a user (client) feature. Administrator accounts have no key store of their own: an administrator who needs a key on a server pastes it directly into the OS reload dialog, as described in Using SSH Keys on OS Reloads.

The SSH Public Keys page#

In the client portal, open SSH Public Keys from the main navigation. The page has two panels:

  • SSH Public Keys lists the keys stored on the account, with each key’s Name, its Fingerprint (SHA-256, truncated in the list), and the date it was Stored. Each row has a View button, which opens the full public key and fingerprint so the key can be checked or copied, and a Delete button.
  • Add SSH Public Key is the form for storing a new key.

Keys belong to the user who added them, and a user only ever sees their own keys.

Adding a key#

  1. Generate a key pair on your own machine if you do not already have one. On macOS, Linux, or Windows 10/11 with the built-in OpenSSH client:

    ssh-keygen -t ed25519 -C "[email protected]"

    This writes the private key to ~/.ssh/id_ed25519 and the public key to ~/.ssh/id_ed25519.pub. Keep the private key on your machine. It is never uploaded anywhere.

  2. Copy the contents of the .pub file. It is a single line that starts with the key type, for example ssh-ed25519 AAAA... [email protected]. If you use PuTTYgen on Windows, copy the line shown in the box labelled Public key for pasting into OpenSSH authorized_keys file.

  3. In the client portal, open SSH Public Keys, enter a Name that identifies the key (such as laptop or work-desktop) and paste the public key into the SSH Public Key box.

  4. Click Add Key. The key appears in the list with its fingerprint and the date it was stored.

A name must be given and must be unique among that user’s keys. The key itself must also be new to the account: SynergyCP fingerprints every key on entry and refuses a key whose fingerprint is already stored, even under a different name.

Accepted keys#

SynergyCP accepts any valid OpenSSH-format public key of these types:

  • Ed25519 (ssh-ed25519) — recommended.
  • ECDSA (ecdsa-sha2-nistp256, -nistp384, -nistp521).
  • RSA (ssh-rsa).

The following are rejected with an error when added:

  • Private keys. Anything containing a PRIVATE KEY marker is refused outright. If you see Private keys are not allowed. Paste an SSH public key., you have pasted the wrong file; paste the .pub file instead and consider the pasted private key compromised.
  • DSA keys (ssh-dss). These are no longer accepted by modern OpenSSH servers and are refused with DSA keys are not supported. Use RSA, ECDSA, or Ed25519 instead.
  • Anything that is not a public key, including truncated keys, keys split across several lines, or a key with the type prefix missing. These fail with Not a valid SSH public key.

Only one key is accepted per entry. To store several keys, add them one at a time, each with its own name.

If your only key is an RSA key, note that the SSH stack inside Containerized Console images predates RSA/SHA-2 signatures, so SFTP clients may need an extra option when uploading ISOs. See the note in Uploading ISOs to a Console. Using an Ed25519 key avoids this. Stored RSA keys work normally for OS reloads.

Viewing a key#

Click View on a key to open a dialog showing its name, full fingerprint, the date it was stored, and the complete public key text in a read-only box, from which it can be copied. Comparing the fingerprint with the output of ssh-keygen -lf ~/.ssh/id_ed25519.pub on your machine confirms you stored the right key.

Deleting a key#

Click Delete on a key and confirm. The key is removed from the account immediately and is no longer offered on new OS reloads or shipped to new console sessions.

Deleting a key does not change servers that were already installed with it. The keys for an OS reload are copied into that install when it is created, so a server keeps whatever was written to its /root/.ssh/authorized_keys until it is reloaded again or the file is edited on the server itself. If a key is lost or compromised, remove it from the affected servers directly as well as from the account.

When a client account is deleted, all of its stored keys are deleted with it.

Storage, privacy and logging#

  • Public keys are encrypted at rest in the SynergyCP database with the application key. The fingerprint is stored in the clear so duplicates can be detected.
  • Adding or deleting a key writes an entry to the user’s activity log, for example SSH Public Key “laptop” added (SHA256:…) or SSH Public Key “laptop” deleted (SHA256:…). Administrators can see these entries in the client’s log in the admin panel, which is also the only view administrators have of a user’s keys outside of the OS reload dialog.
  • Keys are only ever sent to two places: into the OS reload an install was created for, and into the Containerized Console container a user launches.

Via the API#

A user’s keys are available through the API when authenticated with that user’s own API key. There is no endpoint for listing or editing another user’s keys, and administrator API keys have no key store.

# List the authenticated user's stored keys
curl -sS --get "https://api.example.com/ssh-key" --data-urlencode "key=$API_KEY"

# Store a key
curl -sS "https://api.example.com/ssh-key" --data-urlencode "key=$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "laptop", "public_key": "ssh-ed25519 AAAA... [email protected]"}'

# Delete a key
curl -sS -X DELETE "https://api.example.com/ssh-key/12" --data-urlencode "key=$API_KEY"

Each key is returned with its id, name, fingerprint, public_key and created_at. The same validation and duplicate rules apply as in the portal, and a rejected key returns a 422 with the reason in the message. The id values returned here are what an integration passes as ssh_key_ids when it creates an OS reload for the user; see Using SSH Keys on OS Reloads.

Backward SSH Public Keys Using SSH Keys on OS Reloads Forward