The SSH Key Manager service is used to upload public SSH keys for use with course accounts or other services in the Computer Science Department that use public key authentication for access. To access the SSH Key Manager service, visit: https://keymanager.cs.princeton.edu/.
What follows is information about SSH keys including how to create them and how to upload them with the SSH Key Manager service.
While there are many different ways of creating and using SSH keys, this document assumes the typical use case of an instructor who first logs in to their personal account on either portal.cs.princeton.edu (for CS account holders) and then from there logs in to a course account on portal.
Instructions for connecting to your personal account on OIT servers are here: Secure Shell (SSH) and Secure FTP: How to connect to OIT Unix servers (pay particular attention about enabling your Unix account)
For CS account holders, instructions for connecting to your personal account on CS servers are here: Secure Shell (SSH)
This document is not intended to describe all the details of SSH (version 2) or its implementation of public-key cryptography and challenge-response authentication. For that, there are many good references on the Internet. This document was based, in part, on these:
An "SSH Key" is really a key-pair
When you generate an "SSH key" what you create is two text files representing the public key and the private key of a "key pair." As part of the process, you will be asked for a passphrase which is associated with the private key.
To login to a server from your machine, the public key must be installed on the server you want to connect to and the private key is installed on the machine you want to connect from.
Note that if you create a public/private key-pair on machine A (with the private key in the appropriate place on machine A) and then upload the public key to server S, this only lets you login from machine A to server S. If you want to connect from machine B to server S, you will either need to copy the private key from machine A to machine B, or create a second key-pair with the private key on machine B and the public key on server S. The SSH Key Manager supports multiple keys from each user.
Creating SSH Keys
If you don't already have an SSH version 2 key, you will need to create one.
First, login to your personal account on portal.cs.princeton.edu (for CS account holders) or nobel.princeton.edu (for OIT account holders).
Second, change directory into ~/.ssh
If it does not exist, create it with the correct permissions, and change into it:
mkdir ~/.ssh ; chmod 700 ~/.ssh ; cd ~/.ssh
Third, run the ssh-keygen command following this example. Be sure to specify id_rsa as the filename [note]. Remember that the passphrase protects the private key; be sure to choose one like you would a strong password.
$ ssh-keygen Generating public/private rsa key pair. Enter file in which to save the key (/u/johndoe/.ssh/id_rsa): id_rsa Enter passphrase (empty for no passphrase): <DO NOT USE AN EMPTY PASSPHRASE> Enter same passphrase again: <SAME NON-EMPTY PASSPHRASE> Your identification has been saved in id_rsa. Your public key has been saved in id_rsa.pub. The key fingerprint is: 09:e2:24:a7:d6:24:78:e5:df:9f:9c:5e:bf:2f:36:fc johndoe@hostname The key's randomart image is: +--[ RSA 2048]----+ |+oo. .. . | |oo .. + | | . . . | |... . | |oE. S | |.o.o . o | |o + o = | |o. . + . | |. | +-----------------+
The fingerprint and randomart will, of course, be different.
If you followed the above steps/template, your public key will be in ~/.ssh/id_rsa.pub and the corresponding private key will be in ~/.ssh/id_rsa (no filename extension). To print the public key, simply use cat:
$ cat ~/.ssh/id_rsa.pub ssh-rsa AAAAB3NzaC1yc...a long string of characters...velTdiwV joeuser@hostname
It's this entire string (in red, above) that you will cut-and-paste into the appropriate field on the SSH Key Manager page as described in the next section.
Note: If your key is named something other than id_rsa (or not in your ~/.ssh directory), you will need to inform your SSH client to use the alternately-named file. This usage is beyond the scope of this document. (For the curious, lookup the -i command line option to ssh or uses of the ~/.ssh/config file.)
Uploading Your Public Key to the SSH Key Manager service
Once you have generated your key-pair, login (using your OIT NetId and password) to the SSH Key Manager site (https://keymanager.cs.princeton.edu/) to add the public key (the red string, above). As part of the upload process you can give the key a label. This will be the name of the key in the key manager service and is only used to label each key so you can more easily keep track of them. After you finished, hit the "Submit" button to validate and save the key to the system. Once the key is saved you will see a list of all the keys you have stored on the system. You can edit or delete any keys you have stored.
Associating Your Public Key with the Correct CS Course
If your NetID is already associated with a particular course, all your public keys will be automatically pushed to the appropriate course account. (We get the mappings of TAs to courses from Nicki or from the faculty instructors.)
The SSH keys are pushed out automatically for CS course accounts every hour at 15 minutes after the top of the hour.
If you are having problems with your SSH key not working, please contact csstaff with the course account you are trying to use and on what system you are trying to access the course account either CS or OIT.
Accessing Course Accounts
CS course accounts can be accessed via SSH by way of the department public login servers -- cycles/portal/courselab. An example of this workflow would be to login to a cycles or courselab server with your personal netID, pass the Duo two-factor authentication step, then login to the course account.
ssh netID@portal.cs.princeton.edu . . . Duo two-factor login for $user Enter a passcode or select one of the following options: 1. Duo Push to XXX-XXX-1234 2. Phone call to XXX-XXX-1234 3. SMS passcodes to XXX-XXX-1234 (next code starts with: 2) Passcode or option (1-3): [netID@spin ~]$ ssh classAccount@portal.cs.princeton.edu
This nested approach may not be efficient per your use case scenario, however. For example, in the case of SCP or SFTP operations, you can use the "ProxyJump" option. See ProxyJump Documentation for more information on how to use this approach.
Installing and Protecting Your Private Key
If you followed the above instructions, your private key is already in the correct location (~/.ssh) and will have the correct permissions (readable and maybe writable but only by the owner).
Frequently Asked Questions
Click on a question below to show its answer.
Why do I need a passphrase for my SSH key?
If you don't have a passphrase associated with your private key and someone gets a hold of it (e.g., it was on a laptop that is lost or stolen), then they can login to any server with the associated public key.
(The sshkey-gen program does allow you to create a key without a passphrase (i.e., an empty passphrase) because there are a few rare instances when this is appropriate. However, logging in to a server with unrestricted shell access should never be allowed without a passphrase.)
Can I change the passphrase on my private key without generating a new pair?
Yes, use the -p option to ssh-keygen.
If your key already has a passphrase, you will be prompted to enter it before you can change to a new passphrase. Note that since the passphrase is only associated with the private key, if you change the passphrase you do not need to re-upload the associated public key.
How do I associate my uploaded public key(s) with the course(s) I am teaching?
Eventually, this will be automated and tied into a back-end system where course managers can associate users with their courses via a web interface. Until this back-end system is in place, we rely on TA and instructor rosters we receive from Nicki and the faculty teaching the courses. If there are last-minute changes to TA assignments, please have Nicki or the course manager send an e-mail to csstaff and we will update our mapping. The keys will then be (re-)distributed to the appropriate course accounts at the next scheduled push.
Do I need to re-generate and/or re-upload my public key each semester?
No, the public keys are maintained in a database and they will be transferred into the course accounts corresponding to the courses you are teaching. However, until the back-end automation portion of this system is in place, please make sure you e-mail CS Staff at the beginning of the semester to request that your key be associated with your new course.
Can I avoid entering my long passphrase each time I login?
Yes, the tool you seek is called ssh-agent. Setting it up is not too complicated but is beyond the scope of this document.