===== Getting Started with Authentication via Key-Pairs =====

This documentation assumes you have **NEVER** done anything with keypairs before (or at least that you have no recollection of having done so). If you have done keypair stuff for CS 261, you can likely [[#tell_github_to_join_the_party|skip to the github section below]].
Most of the sections of this document assume you have first followed the preceding sections (so you should strongly consider following them in order).

==== Prerequisites ====
  - If it isn't already installed on your computer, [[https://git-scm.com/downloads/ | install git]]. 
    * To tell if it's installed,
      - Linux or macOS: 
        - use the built-in search feature of your operating system to search for "terminal" and launch it.
        - type ''%%git --version%%'' and press Enter. Keep this terminal around for all the future steps!
      - Windows:
        - Press the windows key on the keyboard and search for "bash". If git bash is found and installed, launch it.
        - type ''%%git --version%%'' and press Enter. Keep this terminal around for all the future steps!

==== Generating a Key Pair ====
  - Open a terminal window (specifically as specified above in the prerequisites).
  - In the terminal Type ''%%ssh-keygen -t ed25519 -b 4096 -C "Generated $(date -I)"%%''
    - when prompted for where to save the key, press Enter to save it in the default location.
    - when prompted for a passphrase, do not enter one, just press enter to leave it blank.
      * the whole reason we're setting this keypair authentication up is to avoid having to enter a password every time we perform actions that communicate with a server, which in some cases may be quite frequently.
    - leave it blank (just press enter) a second time to confirm you meant it.
    - you will see a message like

  Your identification has been saved in ~/.ssh/id_ed25519
  Your public key has been saved in ~/.ssh/id_ed25519.pub
  The key fingerprint is:
  SHA256:dkzGbszeCq4x+N6nDzqwertya0si5CWQ4MQCHMW7Ju0 Generated 2024-10-07
  The key's randomart image is:
  +---[ed25519 4096]----+
  |*o+.             |
  |=+ .     .       |
  |+.  .     +      |
  |.  ....  B       |
  | o... . S B      |
  |o.o+ + o = .     |
  |..= + = o + .    |
  | . Eo+.= +.o     |
  |   .o*=.++o      |
  +----[SHA256]-----+

==== Configure your computer's ssh client ====

Tell your computer you'd like to use this key to connect to JMU CS's student server, "stu".

  - Edit your ssh config (located at ''%%~/.ssh/config%%'') to include the following lines:
    * If you're not sure how to edit your ssh config, try entering the following in your terminal (see prerequisite above for help opening the correct terminal for our purposes on your OS): ''%%code ~/.ssh%%''
      * if you don't have a file named config in this location create one

  Host *
    ServerAliveInterval 30
    ServerAliveCountMax 120
    AddKeysToAgent yes # https://man.openbsd.org/ssh_config#AddKeysToAgent
    # IdentitiesOnly yes # I am thinking maybe I should not propose this for beginners. so it's commented out now.
  Host stu # by specifying the host here as "stu", you can use "stu" as a shorthand for
                   # the full hostname when connecting via ssh to the server at the HostName below
    HostName stu.cs.jmu.edu
    # next setting only necessary if you aren't using a default-named key like id_rsa or id_ed25519
          # IdentityFile ~/.ssh/name-of_non_default_private_key
    User YOUR_EID_BUT_DONT_CAPITALIZE_IT # if you specify a user, you don't have to put the
              # user@ when connecting via ssh

** NOTICE THE PART YOU HAVE TO REPLACE ABOVE, FOR MOST IT'S IN JUST THE LAST LINE WHERE IT SAYS "YOUR_EID" **

==== Tell stu this is all legit ====

  - in your terminal (see [[#prerequisites|prerequisite above for help opening the correct terminal for our purposes on your OS]]), enter ''%%ssh-copy-id stu%%''
    - you may see a message like ''%%The authenticity of host 'stu.cs.jmu.edu (134.126.141.221)' can't be established.
ED25519 key fingerprint is SHA256:RYxaUOHGdifpo+JaJeE6JHWVqiji+in1GI5lvbJluPk.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])?%%'', if you do, enter "yes"
    - you will be prompted for your (JMU EID) password. Enter it. **NOTE: As you type your password, it is possible that nothing will be displayed in the terminal to protect your security.**
    - you should see a message like ''%%Number of key(s) added: 1%%''
    - you should now be able to ssh to stu without entering a password. try it: ''%%ssh stu%%''
      * logout before proceeding to the next step by entering ''%%logout%%''

==== Tell Github to join the party ====

**Note: For those who skipped here because of 261 reasons -  Open a terminal window (specifically as specified [[#prerequisites|above in the prerequisites]]).**

If you want to do things with GitHub, you must first have an account. If you don't have one yet, [[https://github.com/signup|sign up for a GitHub account]].

**Note:** it's possible that your quippy username that's served you well since middle school through that very public social media posting about that awkward thing that happened back in high school might be ok to keep around, but perhaps not as your personal-professional username. So maybe don't [[https://en.wikipedia.org/wiki/Doxing|doxx]] yourself by making your github username relate to all your prior online activity. 😅

  - Go to [[https://github.com/settings/ssh/new|Your GitHub SSH and GPG keys settings > New SSH Key page]].
    * authenticate with GitHub if necessary.
  - Enter a name for the SSH key.
    * I suggest naming it based on the current computer you are using (try to be imaginative here. Imagine that this is but the first of many of ThatBrand™️ LapFlaps®️ that you will own in your long, laudable career). Consider something like, ''%%ThatDellWithThatOSv42%%''.
  - leave the browser there for a sec, and go back to your terminal and show your PUBLIC key to yourself by entering ''%%cat ~/.ssh/id_ed25519.pub%%''
    * copy the output of that command.
  - go back to the browser and paste your PUBLIC key's contents into the "Key" field.
  - click "Add SSH key".
  - test that all is well by entering ''%%ssh -T git@github.com%%''
    * you should see a message like ''%%Hi hcientist! You've successfully authenticated, but GitHub does not provide shell access.%%''