Generating an SSH key (Windows, macOS, Linux)

An SSH key lets you connect to your server without a password. The key is a pair of files. The private key stays only on your computer. You add the public key to BLACKBOX: on the “Chei SSH” (SSH keys) page (blackbox.md/account/ssh-keys, “Contul meu” (My account) → “Chei SSH”) or directly on the server, from the app.blackbox.md panel (“My Servers” → “Add SSH key”).

Available to: anyone, on their own computer. Adding the key to your account and to a server: the blackbox.md account holder.

The blackbox.md website is available in Romanian and Russian; this article quotes the Romanian labels with their English meaning.

Which key type to choose

BLACKBOX accepts the types ssh-ed25519, ssh-rsa (at least 2048 bits), ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, sk-ssh-ed25519@openssh.com and sk-ecdsa-sha2-nistp256@openssh.com. DSA keys (ssh-dss) and RSA keys shorter than 2048 bits are rejected.

Generating the key on macOS and Linux

1. Open the Terminal app.

2. Run the command below. Replace the comment laptop-ion with a name that helps you recognize the computer:

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

3. At “Enter file in which to save the key”, press Enter. The key is saved in the default location, ~/.ssh/id_ed25519.

4. At “Enter passphrase”, type a passphrase, then repeat it at “Enter same passphrase again”. The characters don't appear on the screen.

5. At the end, ssh-keygen shows where it saved the two files and the key's fingerprint, in the form SHA256:….

The passphrase encrypts the private key: anyone who copies the file cannot use it without the passphrase. You can press Enter twice to create a key without a passphrase, but we don't recommend it.

The comment you set with -C appears at the end of the public key. In the panel, in the “Installed keys” list, you recognize your keys by this comment.

If a program asks you for an RSA key, generate it like this (the files will be id_rsa and id_rsa.pub):

ssh-keygen -t rsa -b 4096 -C "laptop-ion"

If ssh-keygen asks “already exists. Overwrite (y/n)?”, type n. You already have a key with this name: if you overwrite it, you lose access to the servers where the old key is installed. Use the existing key, or create a new one with a different file name:

ssh-keygen -t ed25519 -C "laptop-ion" -f ~/.ssh/id_ed25519_blackbox

Generating the key on Windows

PowerShell

Windows 10 and 11 include the OpenSSH client, so the command is the same.

1. Open PowerShell (Start menu → type “PowerShell”).

2. Run:

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

3. Answer the prompts as on macOS and Linux: Enter for the default location, then the passphrase twice.

The files are saved in the .ssh folder of your user profile: C:\Users\USERNAME\.ssh\. If Windows replies that ssh-keygen is not recognized as a command, add the OpenSSH Client component in Windows Settings, under optional features.

PuTTYgen

Use PuTTYgen if you connect with PuTTY. It is installed together with PuTTY.

1. Open PuTTYgen. At the bottom, under “Type of key to generate”, choose “EdDSA”, and in the list next to it, “Ed25519 (255 bits)”. In older versions, the option is called simply “ED25519”.
2. Click “Generate” and move the mouse over the empty area of the window until the progress bar fills up.
3. In “Key comment”, replace the default text with a name, for example laptop-ion.
4. Fill in “Key passphrase” and “Confirm passphrase”.
5. Click “Save private key” and save the .ppk file. This is the file you choose in PuTTY.
6. Copy all the text in the “Public key for pasting into OpenSSH authorized_keys file” field: a single line that starts with ssh-ed25519. This is what you paste into BLACKBOX.

Don't use the file saved with “Save public key”. It starts with ---- BEGIN SSH2 PUBLIC KEY ----, has several lines, and is rejected. To use the same key with ssh in PowerShell as well, choose “Conversions” → “Export OpenSSH key” and save the file as C:\Users\USERNAME\.ssh\id_ed25519, with no extension. The reverse conversion, from OpenSSH to .ppk, is covered in Connecting to your server over SSH (Windows, macOS, Linux).

Where the files are

For an RSA key, the files are id_rsa and id_rsa.pub, in the same folder.

Warning Never send your private key to anyone, not even BLACKBOX support, and never paste it into any form: BLACKBOX needs only the public key. The private key is the file without .pub, or text that starts with -----BEGIN.

Display and copy the public key

On macOS and Linux:

cat ~/.ssh/id_ed25519.pub

On Windows (PowerShell):

Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub

The output is a single line. Copy all of it:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI… laptop-ion

To see the key's fingerprint, use the command below (on Windows, with the path $env:USERPROFILE\.ssh\id_ed25519.pub). The SHA256:… value is the same one that BLACKBOX shows in the “Amprentă” (Fingerprint) column and, for “key-only” servers, in the email with the subject “Serverul dvs. este gata” (Your server is ready).

ssh-keygen -lf ~/.ssh/id_ed25519.pub

Add the public key to BLACKBOX

In your account, for new servers

1. Sign in to blackbox.md, click “Cont client” (Customer account) and choose “Chei SSH” in the left menu.
2. In the “Adaugă o cheie SSH” (Add an SSH key) card, fill in “Nume cheie” (Key name) (at most 80 characters) and paste the line into “Cheie publică SSH” (Public SSH key).
3. Click “Adaugă cheia” (Add key). The key appears in the table, with its “Tip” (Type) and “Amprentă” (Fingerprint).
4. When you order a server, in the “Cheie SSH pentru server” (SSH key for the server) step, check the key under “Chei salvate” (Saved keys). The “Dezactivează autentificarea prin parolă (doar cheie SSH)” (Disable password authentication (SSH key only)) box is checked automatically. If you leave it checked, the server is created as “key-only”.

Saving the key in your account does not install it on your existing servers. Details: SSH keys in your account (blackbox.md) and The SSH key at order time and “key-only” servers.

On a running server

1. Open the app.blackbox.md panel (“Contul meu” → “Panou de administrare” (Admin panel)) and go to “My Servers”.
2. On the server card, click “Add SSH key”.
3. Choose “Use a saved key” and pick the key from “Select a key…”, or choose “Paste a new key” and paste the line.
4. Click “Add key”. The result is “Key added.”, and the key appears in “Installed keys”.

The panel installs the key for root without needing your password or your old keys. Details: Adding and removing SSH keys on the server.

From the terminal, with ssh-copy-id

On Linux and macOS, ssh-copy-id adds the public key to the server. It works only if you can already connect: with the password, on a “Password + key” server, or with another installed key.

ssh-copy-id -i ~/.ssh/id_ed25519.pub root@SERVER_IP

If prompted, enter the root password. The key then also appears in the panel, in “Installed keys”, but it is not saved in “Chei SSH” (SSH keys). On Windows, ssh-copy-id does not exist: use the panel.

Check the connection

ssh -i ~/.ssh/id_ed25519 root@SERVER_IP

If the key has a passphrase, SSH asks “Enter passphrase for key”: type the key's passphrase, not the server password. Steps for each system: Connecting to your server over SSH (Windows, macOS, Linux). Once you can log in with the key, you can turn off password login from the panel: Enabling and disabling SSH password login.

More convenient: ssh-agent and the config file

ssh-agent

The SSH agent keeps the key unlocked in memory, so you don't have to type the passphrase every time you connect. On macOS and Linux:

ssh-add ~/.ssh/id_ed25519

If ssh-add cannot connect to the agent (for example, with the message “Could not open a connection to your authentication agent”), start the agent in the current terminal and run ssh-add again:

eval "$(ssh-agent -s)"

On Windows, the agent service is turned off by default. Start it once, from PowerShell run as administrator:

Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent

Then, in a regular PowerShell window:

ssh-add $env:USERPROFILE\.ssh\id_ed25519

To see the keys loaded in the agent:

ssh-add -l

The ~/.ssh/config file

In the ~/.ssh/config file, you can give the server a short name. On Windows, the file is C:\Users\USERNAME\.ssh\config, without a .txt extension. Add a block:

Host server-web
    HostName SERVER_IP
    User root
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

Then you connect with just:

ssh server-web

The name also works with scp and rsync: Transferring files to the server (scp, rsync, SFTP). IdentitiesOnly yes makes SSH offer only the specified key, which avoids the “Too many authentication failures” error when you have many keys.

Hardware security keys (FIDO2)

With a FIDO2 security key (for example, a YubiKey), the secret part stays on the device. You need OpenSSH 8.2 or newer on your computer. Check the version:

ssh -V

1. Plug the security key into your computer.

2. Run:

   ssh-keygen -t ed25519-sk -C "yubikey-ion"

3. Touch the key when ssh-keygen shows “You may need to touch your authenticator”, then set the passphrase as described above.

This creates id_ed25519_sk (a reference to the device; keep it) and id_ed25519_sk.pub, which starts with sk-ssh-ed25519@openssh.com. You add the public one to BLACKBOX the same way as any other key. Every time you connect, the security key must be plugged in and touched.

If the device does not support Ed25519, ssh-keygen shows an error. In that case, generate an ECDSA key, which BLACKBOX also accepts:

ssh-keygen -t ecdsa-sk -C "yubikey-ion"

On macOS, the OpenSSH that comes with the system may not support FIDO2 keys: ssh-keygen then shows an error for both ed25519-sk and ecdsa-sk. In that case, install OpenSSH from Homebrew, open a new terminal and run the command again:

brew install openssh

Backups and losing your key

• Keep a copy of the private key and the passphrase in a safe place, for example in a password manager or on an encrypted USB drive. A forgotten passphrase cannot be recovered.

• You can change the passphrase without changing the key:

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

• The safest approach is to generate a separate key for each computer. If you lose a device, you revoke only its key.

• If you have lost the key or your computer was stolen, generate a new key and add it from the panel with “Paste a new key”. Then remove the old key from “Installed keys” on each server and delete it from “Chei SSH” (SSH keys).

Important On a “Key-only” server, you can no longer connect over SSH without the private key, and customers have no web console. If the panel can't help either, follow Lost access to your server (password or key).

Frequently asked questions

I lost the .pub file, but I still have the private key. What do I do? The command below displays the public key again so you can copy it. On Windows, use the path $env:USERPROFILE\.ssh\id_ed25519.

ssh-keygen -y -f ~/.ssh/id_ed25519

Why does the “Chei SSH” (SSH keys) page reject my key? Most often, you pasted the private key, several lines, or an RSA key shorter than 2048 bits. All the error messages are explained in SSH keys in your account (blackbox.md).

I created the key without a passphrase. Can I add one later? Yes, with the same command you use to change the passphrase, in the section above. The public key does not change, so you don't need to add it to your servers again.