SSH Key Authentication

SSH keys are a more secure and more convenient alternative to password-based login. Instead of typing a password every time you connect, your device proves its identity using a cryptographic key pair. This guide covers why you should use keys, how to generate them, and how to set them up in RemoteConsoleSSH.

Why Use SSH Keys?

Password authentication has several weaknesses that keys solve:

• No brute-force risk -- Passwords can be guessed. SSH keys are cryptographic secrets that are effectively impossible to brute-force. An ed25519 key has roughly 2^256 possible values -- no attacker is guessing that.
• No password to transmit -- With keys, your secret (the private key) never leaves your device. The server verifies your identity through a cryptographic challenge-response, so there is nothing to intercept.
• Convenience -- Once set up, you connect without typing anything. No passwords to remember or mistype.
• Per-device control -- Each device has its own key pair. If you lose a device, you revoke that one key without changing passwords everywhere.

Key Types

There are two key types you will encounter:

ed25519 is the modern standard. It generates smaller keys, signs faster, and is considered more secure than RSA at equivalent security levels. Use ed25519 unless you have a specific reason to need RSA (e.g., connecting to a very old server that does not support it).

Generate a Key Pair

ssh-keygen -t ed25519 -C "your-email@example.com"

eval "$(ssh-agent -s)"
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Copy Your Public Key to the Server

The public key needs to be added to the ~/.ssh/authorized_keys file on the machine you want to connect to. There are several ways to do this.

Method 1: ssh-copy-id (macOS and Linux)

The easiest method. Run this from the machine where you generated the key:

ssh-copy-id username@hostname

Replace username and hostname with your credentials. For example:

ssh-copy-id john@my-macbook.local
ssh-copy-id john@100.64.0.1

You will be prompted for your password one last time. After this, future connections will use key authentication.

Method 2: Manual Copy (All Platforms)

If ssh-copy-id is not available (e.g., on Windows), you can copy the key manually:

cat ~/.ssh/id_ed25519.pub | ssh username@hostname "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

On Windows PowerShell, use:

type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh username@hostname "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

Method 3: Copy and Paste

If the above methods do not work, you can manually copy the contents of your public key:

1. Display the public key:

   cat ~/.ssh/id_ed25519.pub

2. Copy the entire output (it starts with ssh-ed25519 and ends with your email).
3. SSH into the server with your password.
4. Open (or create) the authorized keys file:

   mkdir -p ~/.ssh && nano ~/.ssh/authorized_keys

5. Paste the public key on a new line, save, and exit.
6. Set the correct permissions:

   chmod 700 ~/.ssh
   chmod 600 ~/.ssh/authorized_keys

Test the Key

After copying the key, verify that it works:

ssh username@hostname

You should be logged in without being prompted for a password (unless you set a passphrase on the key, in which case your SSH agent or keychain handles it).

Using SSH Keys in RemoteConsoleSSH

When adding or editing a connection in RemoteConsoleSSH, you can configure key-based authentication:

Troubleshooting

If key authentication is not working, the most common cause is incorrect file permissions. SSH is strict about this -- if the permissions are too open, it silently falls back to password authentication.

Required Permissions

On the server (the machine you are connecting to), check these permissions:

# Your home directory must not be writable by others
chmod 755 ~
 
# The .ssh directory
chmod 700 ~/.ssh
 
# The authorized_keys file
chmod 600 ~/.ssh/authorized_keys
 
# Your private key (on the machine where you generated it)
chmod 600 ~/.ssh/id_ed25519

Debugging the Connection

If it still does not work, connect with verbose output to see what is happening:

ssh -v username@hostname

Look for lines like:

• Offering public key: /Users/you/.ssh/id_ed25519 -- The client is trying the key.
• Server accepts key -- The key was accepted.
• Authentication succeeded -- You are in.

If you see Permission denied (publickey), the server rejected the key. Double-check that the public key is in ~/.ssh/authorized_keys on the server and that permissions are correct.

Next Steps

• Install tmux for persistent terminal sessions that survive disconnections.
• Set up network access with Tailscale if you have not already.
• Return to the Getting Started guide to install RemoteConsoleSSH on your device.