Generate SSH Key Pairs

Overview¶

SSH key pairs are generated using the ssh-keygen command, which is available on Linux, macOS, and Windows 10/11.

Ed25519 keys required

The SCDF user portal only accepts Ed25519 keys (ssh-ed25519, and the hardware-token form sk-ssh-ed25519@openssh.com). RSA, DSA and ECDSA keys are rejected on upload, and the error message will tell you which type it saw and how to generate a replacement.

RSA keys that were uploaded before this change continue to work and have not been removed. They are listed on the portal with a Deprecated badge and can still be deleted. Please replace them with an Ed25519 key when convenient.

Up to five keys per account

You may have up to 5 SSH keys on your account at the same time, for example one per machine you connect from. Each key is added and deleted individually. See Using SSH Keys.

Generate a New Key Pair¶

The steps below apply to Linux, macOS, and Windows 10/11. On Windows, open PowerShell or Command Prompt; no third-party software is required.

1. Run ssh-keygen:

ssh-keygen -t ed25519 -C "work-laptop"

The -C comment labels the key, not you. Name the machine the key lives on (work-laptop, desktop-office). The comment is shown in the key list on the portal, and with several keys on one account it is how you tell them apart when deciding which one to delete.

You will see output similar to:

Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/<user>/.ssh/id_ed25519):

2. Accept the default location by pressing Enter, or enter a custom path.

3. Enter a passphrase when prompted. A passphrase protects your private key. Omitting it means anyone with access to the file can use it.

Enter passphrase (empty for no passphrase):
Enter same passphrase again:

4. Key generation completes with output like:

Your identification has been saved in /home/<user>/.ssh/id_ed25519
Your public key has been saved in /home/<user>/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:H9CefK+BnTnucBnYVVWbyoFDc/gQQib7OTQRV7dPwYE work-laptop
The key's randomart image is:
+--[ED25519 256]--+
|        . oo+    |
|       . o =.o   |
|      . o + +.   |
...
+----[SHA256]-----+

Two files are created:

Private key: ~/.ssh/id_ed25519 (keep this secret, never share it)
Public key: ~/.ssh/id_ed25519.pub (this is what you add to your SCDF account)

5. Add your public key to your account by browsing to:

https://useraccount.sdcc.bnl.gov/ssh-key

You will need to log in with your SCDF account. The page lists the keys already on your account and has an Add a key form with two fields:

SSH Key Content: paste the full contents of your .pub file. Print it with:

cat ~/.ssh/id_ed25519.pub                          # Linux/macOS
type $env:USERPROFILE\.ssh\id_ed25519.pub          # Windows (PowerShell)

SSH Key Fingerprint: paste the fingerprint of the same key. The portal computes the fingerprint from the key you pasted and compares the two, which catches a paste that was truncated or altered on the way. Print it with:
```
ssh-keygen -lf ~/.ssh/id_ed25519.pub                # Linux/macOS
ssh-keygen -lf $env:USERPROFILE\.ssh\id_ed25519.pub # Windows (PowerShell)
```
That prints one line, for example:
```
256 SHA256:H9CefK+BnTnucBnYVVWbyoFDc/gQQib7OTQRV7dPwYE work-laptop (ED25519)
```
Paste the whole line or just the SHA256:... part. An MD5 fingerprint (ssh-keygen -l -E md5 -f ~/.ssh/id_ed25519.pub) is accepted too.

Then click Add Key. The new key appears in the list with its type, fingerprint and comment. Keys are stored in the facility directory and are available on all gateway machines within a few minutes.

If the same key is already on your account (even with a different comment) it is reported as a duplicate. If you already have 5 keys, the form is disabled until you delete one.

Use an Existing Key Pair¶

If you already have an Ed25519 key pair, retrieve its fingerprint with:

ssh-keygen -l -f ~/.ssh/id_ed25519.pub

Output will look like:

256 SHA256:H9CefK+BnTnucBnYVVWbyoFDc/gQQib7OTQRV7dPwYE work-laptop (ED25519)

Confirm the key type shown is (ED25519), then add the key using the portal link above.

If the type shown is (RSA), (ECDSA) or (DSA), that key cannot be added. Generate a new Ed25519 key as described above; the old key can stay in place for other services.

Windows Notes¶

Windows 10 (version 1809 and later) and Windows 11 include OpenSSH as a built-in optional feature. If ssh-keygen is not found in PowerShell, install it via:

Settings → Apps → Optional Features → Add a feature → OpenSSH Client

Once installed, the commands above work identically in PowerShell or Command Prompt. Your keys are saved to C:\Users\<username>\.ssh\ by default.

PuTTY users¶

PuTTYgen can generate Ed25519 keys (select EdDSA under Type of key to generate). To add the key on the portal:

Paste the text from the box labelled Public key for pasting into OpenSSH authorized_keys file into SSH Key Content. The file written by Save public key (the ---- BEGIN SSH2 PUBLIC KEY ---- format) is also accepted.
Copy the value in the Key fingerprint box into SSH Key Fingerprint.

A PuTTY .ppk file is a private key. Never paste it into the portal.