Using Your SSH Key

This page stays here permanently -- bookmark it and come back whenever you need it. It covers what to do with a key you just generated or created yourself, how to connect to a cluster with it, and how to keep it safe.

The rules: expiry, key types, how many

These are the current policy values, read live from the server's configuration, so this table always matches what is actually enforced.

Create a key yourself on the command line

You do not have to let Locksmith generate a key. If you would rather make your own, or you are setting one up on a machine with no browser, use ssh-keygen -- it ships with macOS, Linux, and modern Windows. Only the .pub file gets uploaded.

macOS and Linux

ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/id_ed25519_ccs

Press Enter to accept the location, and enter a passphrase when prompted (recommended -- press Enter twice to skip). Then display the public key so you can copy it:

cat ~/.ssh/id_ed25519_ccs.pub

If something in your environment cannot handle Ed25519, use RSA at 3072 bits or more -- 4096 is a good default:

ssh-keygen -t rsa -b 4096 -C "your_email@example.com" -f ~/.ssh/id_rsa_ccs

Do not use -b 1024 or -b 2048. Those are below the 3072-bit floor and will be refused on upload.

Windows 10 and 11 (PowerShell)

OpenSSH is built in. Open PowerShell and run the same command:

ssh-keygen -t ed25519 -C "your_email@example.com" -f $env:USERPROFILE\.ssh\id_ed25519_ccs
type $env:USERPROFILE\.ssh\id_ed25519_ccs.pub

If ssh-keygen is not recognized, install the OpenSSH client from Settings, Apps, Optional Features -- or just use the browser generator on the Submit Key page instead.

Windows with Git Bash

If you have Git for Windows, launch Git Bash and use the macOS/Linux commands above unchanged.

Windows with PuTTY

PuTTY uses its own key format, so there is one extra step:

1. Open PuTTYgen.
2. For Type of key, choose EdDSA with Ed25519, or RSA with the bits set to 4096.
3. Select Generate and move the mouse over the blank area until the bar fills.
4. Copy the text from the box labelled Public key for pasting into OpenSSH authorized_keys file. That, exactly as shown, is what you paste into Locksmith -- not the contents of a saved .pub file, which PuTTY writes in a different format.
5. Select Save private key and keep the .ppk file somewhere safe. Set a passphrase first if you want one.

Then upload it

Copy the entire single line beginning ssh-ed25519 or ssh-rsa and paste it on the Submit Key page, choosing "I already have a key". Everything below about permissions, connecting, and the support ticket applies exactly the same.

The two files, and which one is secret

An SSH key is a matched pair. If Locksmith generated it for you, you downloaded both halves:

Locksmith never receives your private key. When you generate a key here, it is created inside your own browser and the private half never leaves your machine. We could not produce a copy of it if we wanted to -- which is also why we cannot recover it for you if you lose it.

Put the private key where SSH can find it

Browsers save downloads to ~/Downloads, which is the wrong place: SSH will not look there, and the file permissions are too loose. Move it and lock it down.

macOS and Linux

mkdir -p ~/.ssh && chmod 700 ~/.ssh
mv ~/Downloads/id_ed25519_ccs      ~/.ssh/
mv ~/Downloads/id_ed25519_ccs.pub  ~/.ssh/
chmod 600 ~/.ssh/id_ed25519_ccs
chmod 644 ~/.ssh/id_ed25519_ccs.pub

The chmod 600 matters. SSH refuses to use a private key that other users on the machine can read.

Windows (PowerShell)

mkdir "$env:USERPROFILE\.ssh" -Force
move "$env:USERPROFILE\Downloads\id_ed25519_ccs"     "$env:USERPROFILE\.ssh\"
move "$env:USERPROFILE\Downloads\id_ed25519_ccs.pub" "$env:USERPROFILE\.ssh\"
icacls "$env:USERPROFILE\.ssh\id_ed25519_ccs" /inheritance:r /grant:r "$($env:USERNAME):(R)"

If you renamed the file

You can call the key whatever you like. SSH only looks for default names automatically, so a renamed key must be pointed at explicitly. For example, if you renamed it for a specific cluster:

mv ~/Downloads/id_ed25519_ccs ~/.ssh/id_ed25519_mcc
chmod 600 ~/.ssh/id_ed25519_mcc

then connect with -i pointing at that exact file:

ssh -i ~/.ssh/id_ed25519_mcc jdoe@mcc.ccs.uky.edu

Connect to a cluster

Use the hostname of the cluster your account is on. If you are not sure which, the answer is in the account request you submitted, or ask in your support ticket.

Your cluster username is not always the same as the username shown on your Locksmith dashboard. Use the one issued with your cluster account.

If the key sits at a default name (~/.ssh/id_ed25519), you can drop the -i entirely:

ssh jdoe@mcc.ccs.uky.edu

Several keys? Use an SSH config file

If you have more than one key in ~/.ssh, SSH tries them in turn and can be refused for trying too many before reaching the right one. Naming the key per host avoids that entirely. Create or edit ~/.ssh/config:

Host mcc
    HostName mcc.ccs.uky.edu
    User jdoe
    IdentityFile ~/.ssh/id_ed25519_mcc
    IdentitiesOnly yes

Host lcc
    HostName lcc.ccs.uky.edu
    User jdoe
    IdentityFile ~/.ssh/id_ed25519_ccs
    IdentitiesOnly yes

chmod 600 ~/.ssh/config

Now the short name is enough, and the correct key is used every time:

ssh mcc

IdentitiesOnly yes is the important line. Without it SSH may still offer every key it can find before the one you named.

Check that it worked

Confirm the private key is readable and see its fingerprint:

ssh-keygen -l -f ~/.ssh/id_ed25519_ccs

That fingerprint should match the one shown for the key on your Locksmith dashboard. To watch the negotiation in detail when something is not working:

ssh -v -i ~/.ssh/id_ed25519_ccs jdoe@mcc.ccs.uky.edu

Add a passphrase (recommended)

Keys generated here have no passphrase, so the file alone is enough to log in. Adding one means an attacker needs the file and the passphrase. It does not change the key itself, so nothing needs re-uploading:

ssh-keygen -p -f ~/.ssh/id_ed25519_ccs

To avoid retyping it every connection, add the key to your agent:

ssh-add ~/.ssh/id_ed25519_ccs        # macOS/Linux
ssh-add --apple-use-keychain ~/.ssh/id_ed25519_ccs   # macOS, remember in Keychain

Keeping your key safe

• Never share the private key. Not with colleagues, not with CCS staff, not in a ticket. No one here will ever ask you for it -- a request for your private key is a sign that something is wrong.
• One key, one person. Registering a key that belongs to someone else, or letting someone use yours, violates acceptable use policy and results in permanent suspension of the account.
• Delete the copy in your Downloads folder once the key is in ~/.ssh. Downloads folders get synced, backed up and shared.
• Do not put a private key on a shared or lab machine you do not control. Generate a separate key on each machine you connect from -- you can register up to 2.
• If you think a key was exposed, upload a replacement immediately and open a ticket saying so. Uploading a new key under the same label retires the old one.

Expiry and rotation

Every key is valid for 180 days -- see the rules above for the full picture. Your dashboard shows each key's status and date at all times.

To rotate: get a new key (in the browser or on the command line), upload the new public key under the same label as the old one, and the old key is retired automatically. Then open a ticket so an administrator copies it to the cluster.

Last step: open a support ticket

Uploading a key to Locksmith records it, but an administrator still has to copy it onto the cluster. Your key does not work until that happens. Open a ticket at the HPC User Support Request portal and say that you have uploaded a new key.

Troubleshooting

Still stuck? Open a ticket at the HPC User Support Request portal and include the output of ssh -v -i ~/.ssh/<your key> jdoe@<cluster>. Never include the contents of the private key file itself.