Setting up SSH Keys for WAVE: A Step-by-Step Guide

Introduction

Secure access is essential in the world of high-performance computing (HPC). WAVE, Santa Clara University's HPC unit, allows users to securely connect via SSH (Secure Shell) for command-line access. Setting up SSH keys is a common and effective solution to streamline this process and avoid repeatedly entering your password.

Whether you're new to SSH keys or have used them before, this guide will walk you through generating, configuring, and managing SSH keys for use with WAVE.

What Are SSH Keys?

SSH keys are a pair of cryptographic keys, a public key and a private key, that authenticate you to a remote server without needing a password every time. When you log into WAVE using SSH, the system uses these keys to verify your identity securely.

Public Key: This key is shared with the WAVE system.
Private Key: This key stays on your machine and should never be shared.

Why Use SSH Keys?

Convenience: You won’t need to type your password each time you log in.
Security: SSH keys provide stronger security than traditional passwords.

Step-by-Step Guide for Setting Up SSH Keys

Step 1: Generate an SSH Key Pair

A. Open your terminal (Mac/Linux) or Bash (Windows).
This is where you will run commands to generate your keys.

B. Run the following command:

ssh-keygen -t rsa -b 4096 -C "username@scu.edu"

-t rsa: Specifies the RSA algorithm.
-b 4096: Generates a 4096-bit key for robust security.
-C: Adds a comment (usually your email) for easier identification.

C. Follow the prompts:

Save the file to the default location (`~/.ssh/id_rsa`).
Optionally, add a passphrase for extra security.

Step 2: Copy the Public Key to WAVE

Automatically copy the key:

ssh-copy-id username@login.wave.scu.edu

Or, copy manually:
1. Display your public key:

 cat ~/.ssh/id_rsa.pub

2. Copy the output. Then log into WAVE and paste the key into the ~/.ssh/authorized_keys file:

ssh username@login.wave.scu.edu
mkdir -p ~/.ssh
echo "your_copied_public_key" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

Step 3: Testing the SSH Connection

Test your setup by attempting to SSH into WAVE:

ssh username@login.wave.scu.edu

If everything is set up correctly, you should be logged in without entering your password.

For Windows Users

Using Windows 10/11 Built-in OpenSSH or Windows Subsystem for Linux (WSL)

Built-in OpenSSH: Recent versions of Windows 10 and 11 come with an integrated OpenSSH client. Open Command Prompt or PowerShell and follow the same steps as for Mac/Linux above.

Using Windows Subsystem for Linux (WSL): If you have WSL installed, open the Linux terminal and follow the instructions provided above.

Using PuTTY

If you prefer PuTTY:
1. Generate Keys with PuTTYgen:

a. Download and open PuTTYgen.

b. Choose the RSA algorithm (4096 bits) and click “Generate.”

c. Save the private key and copy the public key.

2. Transfer the Public Key to WAVE:

a. Log into WAVE via PuTTY.

b. Open or create the ~/.ssh/authorized_keys file and paste the public key.

c. Ensure correct permissions with: chmod 600 ~/.ssh/authorized_keys

3. Configure PuTTY to Use Your Private Key:

In PuTTY’s settings, under Connection > SSH > Auth, browse and select your private key file.

Advanced SSH Key Management

Using Multiple SSH Keys

Your SSH config file (usually located at ~/.ssh/config) allows you to simplify and centralize all your SSH settings. Instead of typing out the full hostname, username, and key every time, you can define a short alias.

# ~/.ssh/config
 
Host wave
    HostName login.wave.scu.edu
    User username
    IdentityFile ~/.ssh/wave_rsa
    Port 22
    TCPKeepAlive yes

Host wave: Defines the alias you’ll use on the command line (for example, `ssh wave`).
HostName login.wave.scu.edu: Specifies the real server address.
User username: Sets the default login user for that alias.
IdentityFile ~/.ssh/wave_rsa: Points SSH to the private key you want to use.

Once saved, you only have to run:

ssh wave

to log in, instead of:

ssh -i ~/.ssh/wave_rsa username@login.wave.scu.edu

Using SSH Agent

SSH agent allows you to load your private key into memory, so you don’t need to enter a passphrase each time you use it:

Add your key to the agent:

ssh-add ~/.ssh/id_rsa

Verify the loaded key:

ssh-add -l

Rotating SSH Keys

For security, periodically regenerate your SSH keys:
- Follow the key generation process to create a new key.
- Update your ~/.ssh/authorized_keys on WAVE with the new key.
- Remove old keys to maintain security.

Troubleshooting Common Issues

Permission Denied (publickey)

Ensure the public key is correctly copied to the WAVE server in ~/.ssh/authorized_keys.
Verify file permissions:

chmod 600 ~/.ssh/authorized_keys

Agent Admitted Failure to Sign Using the Key

This error may occur if your SSH agent is not running or if your key is not loaded.
Try reloading your key with:

ssh-add ~/.ssh/id_rsa

SSH Key Tutorial