Differences

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

--- howto:sshkey [2025/07/08 23:50] – jnilsson
+++ 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 ======
-===== Generating keys =====
-=== 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. Here is an example session showing how you can run ssh-keygen:
-<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 using the IdentityFile variable in the global config file /etc/ssh/ssh_config or your local config file ~/.ssh/config).
-===== 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. Each key in this file needs to be added on its own line and the file needs to have specific permissions and ownership in order to be recognized:
-  * owner: the user whose home directory it resides in
-  * permissions: 0600, writable by the owner and no one else
-There are different ways to distribute and set up the authorized_keys file depending on your situation:
+<code>
+#private key
+C:\Users\YourUsername\.ssh\id_ed25519
+#public key
+C:\Users\YourUsername\.ssh\id_ed25519.pub
+</code>
-==== Ask for help from SSCS ====
+==== macOS and Linux Users ====
-You can always ask for help from [[sscs@uci.edu]] and we'll work with you to get your public key set up.
+Open **Terminal**. Run:<code bash>
+ssh-keygen -t ed25519
+</code>
-If you want to DIY, you can try one of the methods below:
+You will see prompts similar to this (simply press Enter to proceed with the default file names and without encrypting your key):
-==== Local Console Access ====
+<code>
-If you have access to the console of the remote host (i.e. you can physically access the console in-person), then you can set up the authorized_keys file like this (note that this does not require admin/sudo privileges):
+Generating public/private key pair.
-  - Generate your SSH key on your computer that you will use to access the remote host using ssh-keygen as described above
+Enter file in which to save the key (/home/user/.ssh/id_ed25519):
-  - Save the .pub key file either in email to yourself or on a USB drive
+Enter passphrase (empty for no passphrase):
-  - On the local console of the remote host, login as your user account:
+Enter same passphrase:
-    - Copy the contents of the new public key (either from email or a USB drive) to a temp file:<code bash>
+</code>
-TMP_NEWKEY_FILE=/tmp/newkey.pub
-echo "ssh-ed25519 AAAAasdfghjklQWERTYPOIUzxcvbnm/00/PLokIJuhYG12345 this is a comment" > $TMP_NEWKEY_FILE
+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>
+ssh-copy-id username@remotehost
+</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>
-    - Set up your ~/.ssh directory and authorized_keys file with correct permissions. This is safe to do even if they already exist and will not erase or overwrite existing keys:<code bash>
+  - On the remote server console, log in as your user account and run:<code bash>
 mkdir -p ~/.ssh
 touch ~/.ssh/authorized_keys
@@ Line 40: / Line 144: @@
 chmod 600 ~/.ssh/authorized_keys
 </code>
-    - Append your new public key:<code bash>
+  - Then append your public key to ''authorized_keys'':<code bash>
-cat $TMP_NEWKEY_FILE >> ~/.ssh/authorized)_keys
+echo "PASTE_YOUR_PUBLIC_KEY_HERE" >> ~/.ssh/authorized_keys
-</code>
-    - Delete the temp file:<code bash>
-rm $TMP_NEWKEY_FILE
 </code>
-==== Password authentication is enabled on the remote host ====
+===== Step 4: Test Your SSH Login =====
-If you can log in to the remote host using a password, then you can use the command **ssh-copy-id** to set up your public key. Here is an example session showing how ssh-copy-id works:
-<file>
-[user@localhost ~]$ ssh-copy-id user@remotehost
-/usr/bin/ssh-copy-id: INFO: Source of key(s) to be installed: "/Users/username/.ssh/id_ed25519.pub"
-/usr/bin/ssh-copy-id: INFO: attempting to log in with the new key(s), to filter out any that are already installed
-/usr/bin/ssh-copy-id: INFO: 1 key(s) remain to be installed -- if you are prompted now it is to install the new keys
-user@remotehosts's password:
-Number of key(s) added:        1
+After your public key has been added to the server, test your login from your local computer:
-Now try logging into the machine, with: "ssh 'user@remotehost'"
+<code bash>
-and check to make sure that only the key(s) you wanted were added.
+ssh username@remotehost
+</code>
-</file>
+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.
-If ssh-copy-id does not work or is not available, then you can manually accomplish the same steps like this:
+===== Administrator Instructions =====
-<file>
-# 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)
-[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]$ chmod 600 authorized_keys
-[user@remotehost .ssh]$ rm my_id.pub
-</file>
-==== Password authentication is disabled on the remote host ====
-If password authentication is already disabled, then you will have to give your public key file to someone with admin access who already has public key authentication set up, or follow the above instructions for local console access to set it up yourself.
+Use this section if you are an administrator adding someone else's public key to their user account. Modify these values as needed:
-If you have admin access and have been asked to add someone else's public key to their user account, the following example code should guide you on the steps to take. This assumes that they have somehow given you their public key and it is stored in a file called /tmp/newkey.pub and their username is "example". Modify these variables appropriately to meet your needs:
 <code bash>
-USERNAME=example
+USERNAME=panteater
-TMP_PUBKEY_FILE="/tmp/newkey.pub"
+TMP_PUBKEY_FILE="/tmp/id_ed25519.pub"
-USER_HOME=$(eval echo "~$USERNAME")
-AUTHKEY_FILE="$USER_HOME/.ssh/authorized_keys"
-# Ensure .ssh exists
+USER_HOME=/home/panteater
-sudo mkdir -p "$USER_HOME/.ssh"
+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"
-# Append key if not already present
+# 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 permissions
+# Set correct permissions and ownership
-sudo chmod 700 "$USER_HOME/.ssh"
+sudo chmod 700 "$SSH_DIR"
 sudo chmod 600 "$AUTHKEY_FILE"
-sudo chown -R "$USERNAME" "$USER_HOME/.ssh"
+sudo chown -R "$USERNAME":"$USERNAME" "$SSH_DIR"
-# Clean up temp file
+# 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.