Differences

This shows you the differences between two versions of the page.

--- howto:sshkey [2025/05/12 21:51] – [Ubuntu] justip6
+++ howto:sshkey [2026/05/12 19:31] (current) – [Note about encrypting your keys] jnilsson
@@ Line 1: / Line 1: @@
-===== Setting up Passwordless SSH-key=====
+====== Setting up SSH Public Key Authentication ======
-==== Ubuntu ====
-=== ssh-keygen ===
+SSH public key authentication lets you log in to a remote Linux server without needing to type a password. Instead SSH uses a key pair:
-You use the tool "ssh-keygen" to create your public-private key pair.  Depending on what you need to do, there are many options available.
-<code bash>
+  * **Private key**: ''id_ed25519'' - stays on your local computer and should never be shared
-[user@host ~]$ ssh-keygen -t ed25519 -C "Add a Description to easily tell which machine this belongs to"
+  * **Public key**: ''id_ed25519.pub'' - copied to the remote server
+When you try to connect, your private key is used to authenticate you, and if your public key is set up correctly on the server, you are allowed to log in.
+You can read more about SSH public key authentication here:
+  * [[https://www.ssh.com/academy/ssh/public-key-authentication|SSH Public Key Authentication]]
+===== Important notes =====
+  * Never share your private key.
+  * It is safe to share your public key.
+  * Your public key file usually ends in ''.pub''.
+  * Confirm that SSH key login works before password login is disabled.
+  * If you need help, contact SocIT at [[socit@uci.edu]].
+===== Step 1: Check Whether You Already Have an SSH Key =====
+If you already have an SSH key pair, you can usually reuse it ([[#step_3_copy_your_public_key_to_the_server|skip to step 3 below]]) instead of generating a new one.
+Use the code below to see if you already have files such as ''id_ed25519'' and ''id_ed25519.pub''.
+==== Windows Users ====
+Open **PowerShell** or **Windows Terminal** and run:<code powershell>
+dir $env:USERPROFILE\.ssh
+</code>
+==== macOS and Linux Users ====
+Open **Terminal** and run:<code bash>
+ls ~/.ssh
+</code>
+===== Step 2: Generate an SSH Key =====
+If you do not already have an SSH key, create one using ''ssh-keygen''.
+==== Windows Users ====
+Open **PowerShell** or **Windows Terminal**. Run:<code powershell>
+ssh-keygen -t ed25519
+</code>
+You will see prompts similar to this (simply press Enter to proceed with the default file names and without encrypting your key):
+<code>
 Generating public/private key pair.
-Enter file in which to save the key (/home/user/.ssh/id_ed25519): [Enter to leave default]
+Enter file in which to save the key (C:\Users\YourUsername/.ssh/id_ed25519):
-Enter passphrase (empty for no passphrase): [Enter to leave empty]
+Enter passphrase (empty for no passphrase):
-Enter same passphrase: [Enter to leave empty]
+Enter same passphrase:
 </code>
-You should leave the default values above by simply hitting Enter three times.  The private key is created in id_ed25519 and the matching public key is id_ed25519.pub. The id_ed25519 file name is what ssh will look for when attempting public-key authentication (unless specified differently in the /etc/ssh/ssh_config in the IdentityFile variable.
-=== Distributing your public key ===
+The default key files are:
-The *.pub file needs to be appended to the ~/.ssh/authorized_keys file to be recognized by ssh.  This should be done on any remote hosts you wish to connect to using public-key authorization.  Be sure each key starts on its own new line, since many users may need to connect to the machine and all be able to add their public keys to the authorized_keys file. The code below should do it:
+<code>
+#private key
+C:\Users\YourUsername\.ssh\id_ed25519
+#public key
+C:\Users\YourUsername\.ssh\id_ed25519.pub
+</code>
+==== macOS and Linux Users ====
+Open **Terminal**. Run:<code bash>
+ssh-keygen -t ed25519
+</code>
+You will see prompts similar to this (simply press Enter to proceed with the default file names and without encrypting your key):
+<code>
+Generating public/private key pair.
+Enter file in which to save the key (/home/user/.ssh/id_ed25519):
+Enter passphrase (empty for no passphrase):
+Enter same passphrase:
+</code>
+The default key files are:
+<code>
+#private key
+~/.ssh/id_ed25519
+#public key
+~/.ssh/id_ed25519.pub
+</code>
+==== Note about encrypting your keys ====
+If you typed a password above during key generation, then your private key is encrypted and you will be prompted for a password every time you try to use the key. This is an optional security feature, but not something covered by this guide.
+===== Step 3: Copy Your Public Key to the Server =====
+Your public key must be added to this file on the remote Linux server:
+<code>
+~/.ssh/authorized_keys
+</code>
+Use a method below to distribute your public key to the server:
+===== Option A: Ask SocIT for Help =====
+If you would like help, contact SocIT at [[socit@uci.edu]]. Please include:
+  * The server name you want to connect to
+  * Your username on that server
+  * The contents of your public key file. You can paste the contents of ''id_ed25519.pub'' into the body of the email, or attach the file.
+  * NOTE: Never share your private key
+===== Option B: Use ssh-copy-id =====
+Use this method if password login is currently enabled on the remote server.
+The ''ssh-copy-id'' command automatically installs your public key on the server. Run this command from your local computer:
 <code bash>
-# Your pub key's filename may differ depending on whether it was ed25519 (id_ed25519.pub), rsa (id_rsa.pub) or dsa (id_dsa.pub)
+ssh-copy-id username@remotehost
-[user@localhost ~]$ scp ~/.ssh/id_ed25519.pub user@remotehost:/home/user/.ssh/my_id.pub
-Enter password for user@remotehost:
-[user@localhost ~]$ ssh user@remotehost
-Enter Password
-[user@remotehost ~]$ cd .ssh
-[user@remotehost .ssh]$ cat my_id.pub >> authorized_keys
-[user@remotehost .ssh]$ rm my_id.pub
 </code>
+Replace:
+  * ''username'' with your username on the remote server
+  * ''remotehost'' with the server hostname
+You will be prompted for your password on the remote server. If the command is not found, use [[#option_a_ask_socit_for_help|Option A: Ask SocIT for Help]].
+===== Option C: Use Local Console Access =====
+Use this method if you can physically access the remote server console or otherwise log in locally.
+  - Copy the contents of ''id_ed25519.pub'', it should be one long line like:<code>
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleKeyDataHere my-laptop
+</code>
+  - On the remote server console, log in as your user account and run:<code bash>
+mkdir -p ~/.ssh
+touch ~/.ssh/authorized_keys
+chmod 700 ~/.ssh
+chmod 600 ~/.ssh/authorized_keys
+</code>
+  - Then append your public key to ''authorized_keys'':<code bash>
+echo "PASTE_YOUR_PUBLIC_KEY_HERE" >> ~/.ssh/authorized_keys
+</code>
+===== Step 4: Test Your SSH Login =====
+After your public key has been added to the server, test your login from your local computer:
+<code bash>
+ssh username@remotehost
+</code>
+If you entered a password when generating your key, then you will be prompted for this password in order to decrypt your private key. This is different from your user account password.
+===== Administrator Instructions =====
+Use this section if you are an administrator adding someone else's public key to their user account. Modify these values as needed:
+<code bash>
+USERNAME=panteater
+TMP_PUBKEY_FILE="/tmp/id_ed25519.pub"
+USER_HOME=/home/panteater
+SSH_DIR="$USER_HOME/.ssh"
+AUTHKEY_FILE="$SSH_DIR/authorized_keys"
+# Create .ssh directory and authorized_keys file
+sudo mkdir -p "$SSH_DIR"
+sudo touch "$AUTHKEY_FILE"
+# Add the key only if it is not already present
+if ! sudo grep -Fxq -f "$TMP_PUBKEY_FILE" "$AUTHKEY_FILE"; then
+  cat "$TMP_PUBKEY_FILE" | sudo tee -a "$AUTHKEY_FILE" > /dev/null
+fi
+# Set correct permissions and ownership
+sudo chmod 700 "$SSH_DIR"
+sudo chmod 600 "$AUTHKEY_FILE"
+sudo chown -R "$USERNAME":"$USERNAME" "$SSH_DIR"
+# Remove temporary public key file
+rm -f "$TMP_PUBKEY_FILE"
+</code>
+===== Troubleshooting =====
+For more detailed troubleshooting output, use:
+<code bash>
+ssh -vv username@remotehost
+</code>
+This can help identify any issues when logging in.
+===== Security Reminders =====
+  * Do not share your private key.
+  * Only share your public key, the file ending in ''.pub''.
+  * Use a passphrase on your private key if you want extra protection.
+  * Confirm SSH key login works before disabling password authentication.
+  * If password authentication will be disabled on a server, make sure all remote users have working SSH keys first.