.. include:: ../global.rst

*******************************************
SSH Explained
*******************************************

What Problem Is SSH Even Solving?
==================================

Imagine you need to control a computer that's in a *different room* — or a
different city. You can't walk over and type on its keyboard, so you need to
send your keystrokes to it over the internet instead.

That's scary for two reasons:

* **Somebody could pretend to be that computer.** You think you're talking
  to your school's server, but really you're talking to a stranger's laptop
  set up to trick you.
* **Somebody could listen in on the wire.** Your username, password, and
  everything you type could be read by anyone sitting between you and the
  computer — like someone reading a postcard as it passes through the mail.

**SSH** (Secure SHell) is the tool that solves both problems. It lets you
"remote control" another computer through a connection that is:

#. **Verified** — you get proof you're talking to the *real* computer, not
   an impostor.
#. **Encrypted** — even if someone captures every single byte you send,
   it looks like random garbage to them.

To pull that off, SSH leans on a clever idea: **keys that come in pairs.**

---

Part 1: The Two Keys
=====================

Forget "keys that open locks" for a second. Think of an SSH key pair as two
halves of a magic rubber stamp:

* Your **private key** stays on your computer, forever, and you never show
  it to anyone. It's kept in a folder like a diary under your mattress.
* Your **public key** is the opposite — you're *supposed* to hand it out.
  You post it on every server you want to log into, the same way you'd tell
  a friend your locker number.

The magic: anything **stamped** with your private key can be checked by
*anyone* holding your public key — but only your private key can make a
valid stamp. There is no way to fake the stamp using the public key alone,
and there's no way to figure out your private key just by looking at the
public one.

.. mermaid::

   flowchart LR
       subgraph you["🧑 Your Laptop"]
           priv["🔒 Private Key\n(secret — never leaves\nyour computer)"]
       end
       subgraph server["🖥️ School Server"]
           pub["🔑 Public Key\n(copied here ahead\nof time — OK if\neveryone sees it)"]
       end
       priv -- "stamps a proof\nonly this key\ncould make" --> check{{"Does the stamp\nmatch the public\nkey on file?"}}
       pub --> check
       check -- "yes ✅" --> login["You're let in —\nno password needed!"]
       check -- "no ❌" --> deny["Connection refused"]

       style priv fill:#ffd6d6,stroke:#c0392b
       style pub fill:#d6f5d6,stroke:#27ae60
       style login fill:#d6f0ff,stroke:#2471a3
       style deny fill:#eeeeee,stroke:#888888

So when you connect, the server doesn't ask "what's your password?" — it
asks "prove you own the private key that matches this public key I already
have." Your laptop does a little math with the private key to make a
one-of-a-kind proof, sends *only the proof* (never the key itself), and the
server checks it against the public key. Nobody watching can steal your
private key from that exchange, because it was never sent anywhere.

.. tip::
   This is why you can SSH into a server *without typing a password* once
   your public key is set up there. The "password" is really "can your
   laptop do this math trick?" — and only the computer with the matching
   private key can.

---

Part 2: What Happens the First Time You Connect
=================================================

Here's a twist: **the server has a key pair too.** It's called the
**host key**, and it proves "I really am the server you meant to talk to,"
the same way your key pair proves who *you* are.

But the very first time you ever connect to a brand-new server, your laptop
has never seen that server's public key before. So it can't yet tell the
difference between the *real* server and an impostor pretending to be it.
This is the one genuinely awkward moment in the whole process, and it's why
your terminal shows a scary-looking message like:

.. code-block:: text

   The authenticity of host 'school-server.edu (10.0.0.5)' can't be established.
   ED25519 key fingerprint is SHA256:aGVsbG8gd29ybGQgdGhpcyBpcyBhIHRlc3Q=
   Are you sure you want to continue connecting (yes/no)?

.. mermaid::

   sequenceDiagram
       participant You as 🧑 You
       participant Laptop as 💻 Your Laptop
       participant Server as 🖥️ Server

       Laptop->>Server: "Hi! Who are you?"
       Server-->>Laptop: Here's my public host key (fingerprint: aGVs...)
       Laptop->>Laptop: Check known_hosts file... never seen this before!
       Laptop->>You: "I don't recognize this server. Trust it? (yes/no)"
       You->>Laptop: yes
       Laptop->>Laptop: Save fingerprint to known_hosts
       Note over Laptop,Server: From now on, every future connection is<br/>checked against this saved fingerprint automatically.

That one-time "do you trust this?" moment is called **Trust On First Use
(TOFU)**. You (a human) make the judgment call *once*. After that, your
laptop remembers the fingerprint and will silently compare it every single
future connection. If the fingerprint ever suddenly changes, SSH will
refuse to connect and scream a big warning at you — that's the sign someone
might be trying to impersonate the server.

.. note::
   In a school or company setting, you're often given the correct
   fingerprint ahead of time (posted on a trusted webpage, told to you in
   person, etc.) specifically so you can double-check it instead of just
   blindly typing "yes."

---

Part 3: Why Someone Spying on the Wire Learns Nothing
=======================================================

So far we've covered proving *who* you are. But there's a separate,
equally important trick happening in the background: **everything sent
over an SSH connection is encrypted**, including your username and
password, every command you type, and every bit of output you see.

Imagine someone — let's call her Eve — is secretly recording every byte
that travels between your laptop and the server (this is shockingly easy
to do on public Wi-Fi). If SSH is doing its job, all Eve captures is
noise.

Here's how, using a classic trick called a **key exchange** (real SSH uses
math called Diffie-Hellman, but paint mixing works just as well to explain
it):

.. mermaid::

   flowchart TB
       start["Everyone agrees on one\npublic starting color: 🟡 Yellow\n(Eve can see this — it's public)"]

       start --> yousecret["🧑 You pick a\nsecret color: 🔴 Red\n(never shared!)"]
       start --> serversecret["🖥️ Server picks a\nsecret color: 🔵 Blue\n(never shared!)"]

       yousecret --> yourmix["Mix Yellow + Red\n= 🟠 Orange"]
       serversecret --> servermix["Mix Yellow + Blue\n= 🟢 Green"]

       yourmix -- "send 🟠 over\nthe wire" --> serverGets["Server receives 🟠"]
       servermix -- "send 🟢 over\nthe wire" --> youGet["You receive 🟢"]

       serverGets --> serverFinal["Mix received 🟠\nwith own secret 🔵\n= 🟤 Brown"]
       youGet --> yourFinal["Mix received 🟢\nwith own secret 🔴\n= 🟤 Brown"]

       yourFinal --> match["Both sides now share\nthe SAME secret color 🟤\n— without ever sending\nit over the wire!"]
       serverFinal --> match

       eve["🕵️ Eve only ever sees:\nYellow, Orange, Green\n(the public mixes)\n— she can't easily\nun-mix them to find\nRed, Blue, or Brown"]

       style yousecret fill:#ffd6d6,stroke:#c0392b
       style serversecret fill:#d6e8ff,stroke:#2471a3
       style match fill:#e8d6ff,stroke:#8e44ad
       style eve fill:#eeeeee,stroke:#888888,stroke-dasharray: 5 5

Mixing two colors is easy — but *un-mixing* a color back into its two
original ingredients is really hard, especially once it's a specific shade
neither side told the other ahead of time. Real SSH uses giant numbers and
serious math instead of paint, but the idea is identical: both sides can
compute the *same* shared secret independently, while anyone watching the
wire only ever sees the "mixed" values, which aren't enough to reconstruct
the secret.

Once your laptop and the server both land on that shared secret, they use
it to scramble (encrypt) every message from then on. So even though Eve
can still see *that* data is flowing, and roughly *how much*, the actual
content is unreadable static to her — your password, your commands, your
files, all of it.

.. mermaid::

   sequenceDiagram
       participant You as 💻 Your Laptop
       participant Eve as 🕵️ Eve (watching the wire)
       participant Server as 🖥️ Server

       You->>Server: 🟠 (public mix — Eve sees this)
       Server->>You: 🟢 (public mix — Eve sees this)
       Note over You,Server: Both sides quietly compute the same 🟤 secret

       You->>Server: 🔐 f8a3...c91e (your login, encrypted)
       Note right of Eve: Eve sees random-looking\nbytes. No password,\nno username, no clue.
       Server->>You: 🔐 9b2e...44af (response, encrypted)

---

Putting It All Together
========================

Every SSH connection, start to finish, does these things in order:

#. **Key exchange:** your laptop and the server "mix colors" to agree on a
   shared secret, without ever transmitting the secret itself. Every
   message from here on is encrypted with it.
#. **Server proves its identity:** the server signs something with its
   private host key; your laptop checks it against the fingerprint it
   already trusts (or asks you to trust it, the very first time).
#. **You prove your identity:** your laptop signs something with *your*
   private key; the server checks it against the public key you gave it
   earlier. No password ever has to cross the wire.
#. **You're in**, and everything you type or see from now on is scrambled
   before it leaves either computer.

.. list-table:: Quick Recap
   :widths: 30 70
   :header-rows: 1

   * - Term
     - Kid-Friendly Definition
   * - **Private key**
     - Your secret — never leaves your computer, ever.
   * - **Public key**
     - The "locker number" you're fine sharing with servers.
   * - **Host key**
     - The server's *own* key pair, proving it's really that server.
   * - **Fingerprint**
     - A short code that stands in for a public key, easy to
       compare by eye.
   * - **Trust On First Use (TOFU)**
     - The one moment a human has to say "yes, I trust this," the
       very first time.
   * - **Key exchange**
     - The "paint mixing" trick both sides use to agree on a secret
       without ever sending the secret itself.

---

Check Your Understanding
=========================

1. Which key should you *never* share with anyone, not even the server
   you're connecting to?

   A) Your public key
   B) Your private key
   C) The server's host key
   D) The fingerprint

2. What does "Trust On First Use" (TOFU) mean?

   A) SSH automatically trusts every server forever
   B) You must type your password twice the first time
   C) The first time you connect to a new server, a human has to
      confirm the fingerprint looks right
   D) The server always trusts the first laptop that connects

3. Eve is recording all the traffic between your laptop and a server
   during an SSH session. What can she actually read?

   A) Your password, in plain text
   B) Every command you type, unencrypted
   C) Only scrambled, encrypted bytes — no readable content
   D) Nothing at all — she can't even see that data is flowing

4. In the paint-mixing analogy, why can't Eve figure out the final
   shared secret color just by watching the wire?

   A) She never sees any of the mixed colors
   B) She only sees the *mixed* colors, and un-mixing them back into
      the original secret colors is extremely hard
   C) The colors are sent in an unbreakable secret language
   D) Eve isn't smart enough to understand colors

Answer key with explanations
==============================

1. **Answer: B**
   Your private key is what proves *you* are you. If anyone else gets a
   copy of it, they can pretend to be you on every server that has your
   public key.

2. **Answer: C**
   The first connection to a brand-new server can't be automatically
   verified, so a human has to make the call once. After that, the
   fingerprint is remembered and checked automatically.

3. **Answer: C**
   The key exchange sets up an encrypted tunnel before any login
   information is sent, so Eve only ever sees unreadable, scrambled
   bytes — she can tell *that* something is being sent, but not *what*.

4. **Answer: B**
   Mixing is a one-way street: easy to do, extremely hard to undo. Both
   sides land on the same secret by combining a public value with their
   own private secret, but an outside observer never has enough
   information to reverse the process.