Add getting started

content/getting-started.md

@@ -0,0 +1,166 @@
+# Getting started
+
+Glad you made it here :)
+
+Let's get you started on setting up your online identity and profile page.
+
+[[toc]]
+
+## Creating an account
+
+Well, you can't.
+
+But you don't need to!
+
+Keyoxide is not your typical "web application" requiring you to create an account and log in to perform tasks. That sounds strange but this approach has many advantages! Let's first review some concepts of how Keyoxide does its magic.
+
+If you just want to know what to do, jump to [Generating an OpenPGP key](#generating-an-openpgp-key).
+
+## How websites store and handle data
+
+### Centralized model
+
+Creating an account on a traditional or "centralized" website like Facebook allows them to store your data on their servers and generate a profile page with that data. The problem with this approach is that you don't own your data: Facebook owns your data. And once it's on their servers, it's hard to get rid of it.
+
+Fortunately for you, we can do better.
+
+### Decentralized model
+
+Keyoxide still needs data to show on your profile page but it doesn't want to store that data on its server. Instead, Keyoxide goes looking for your data where you have decided to store it. This has the distinct advantage that you remain in control of that data! Remove it and it's no longer accessible to Keyoxide.
+
+Also, no need to create yet another account on yet another website \o/
+
+## Cryptographic keys
+
+Proofs are created and managed inside cryptographic keys that act as "secure transport vessels", which are stored on special servers that already contain the cryptographic keys of many people. Keyoxide simply goes looking for your key and read the content.
+
+What makes cryptographic keys so useful for us is that they are actually made of two keys: a "private key" that only you have on your device and a "public key" that you can give away to everyone. Only you can add and edit proofs but everyone can read them.
+
+An important note: the guide below follows a few best practices but does make assumptions, for example on how your key is stored online. If you know what you are doing, you are encouraged to go your own route! If you are less familiar with the OpenPGP ecosystem, you might feel safer following this guide.
+
+Enough theory! Let's go decentralized!
+
+## Generating an OpenPGP key
+
+**!!! Working with OpenPGP keys and identity proofs requires you to work with the command line !!!**
+
+You only need to generate an OpenPGP key once. After this step, you will add and remove proofs using always the same key.
+
+Install the **gpg** tool. It comes pre-installed with most Linux distributions.
+
+Generate a new cryptographic key:
+```
+gpg --full-gen-key
+```
+
+Choose **RSA and RSA** by just pressing enter:
+```
+Please select what kind of key you want:
+   (1) RSA and RSA (default)
+   (2) DSA and Elgamal
+   (3) DSA (sign only)
+   (4) RSA (sign only)
+  (14) Existing key from card
+Your selection?
+```
+
+Choose **2048** by just pressing enter:
+```
+RSA keys may be between 1024 and 4096 bits long.
+What keysize do you want? (2048)
+```
+
+Choose **2y** to make your key valid for two years (it's simple to extend this period):
+```Please specify how long the key should be valid.
+         0 = key does not expire
+      <n>  = key expires in n days
+      <n>w = key expires in n weeks
+      <n>m = key expires in n months
+      <n>y = key expires in n years
+Key is valid for? (0) 2y
+```
+
+Confirm this:
+```
+Key expires at Sun 28 Aug 2022 01:23:45 AM CEST
+Is this correct? (y/N) y
+```
+
+Now, enter your name and email address (you can leave the comment empty):
+```
+GnuPG needs to construct a user ID to identify your key.
+
+Real name: Alice Bobsdottir
+Email address: alice@bobsdottir.net
+Comment:
+```
+
+This email needs to be valid! You will receive an email later in this process.
+
+Confirm this:
+```
+You selected this USER-ID:
+    "Alice Bobsdottir <alice@bobsdottir.net>"
+
+Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
+```
+
+The next screen asks you to input a password to secure the key. Please use a long but memorable password and save it using a password manager: if you lose this password, you won't be able to edit the proofs in the future.
+
+Once you confirm your password, the following message appears:
+```
+We need to generate a lot of random bytes. It is a good idea to perform
+some other action (type on the keyboard, move the mouse, utilize the
+disks) during the prime generation; this gives the random number
+generator a better chance to gain enough entropy.
+```
+
+Once this is done, you have generated your OpenPGP key! To find your so-called **fingerprint**, run:
+```
+gpg --fingerprint
+```
+
+One of the first lines consists of 10 blocks of 4 hexadecimal characters: this is your **fingerprint**, the identifier that is globally unique to your key. Write it down somewhere or remember how you can make it appear, you will need it later.
+
+## Uploading your key
+
+Your computer now has a cryptographic keypair: both the private key and the public key. Next, we upload your public key to a special server whose only purpose is to contain the public keys of many people.
+
+### First time
+
+Export the public key to a file named **pubkey.asc** (make sure to replace EMAIL):
+```
+gpg --armor --export EMAIL > pubkey.asc
+```
+
+Go to [keys.openpgp.org/upload](https://keys.openpgp.org/upload) and upload your key using the form.
+
+To prove ownership of the email address you entered in the key, the server will send you an email asking you to confirm by clicking a link. Once this process is done, it does not need to be repeated and uploading becomes a lot simpler by following the instructions below.
+
+### Subsequent times
+
+Simply run:
+```
+`gpg --keyserver hkps://keys.openpgp.org --send-keys FINGERPRINT`
+```
+
+I told you we were going to need that fingerprint! Replace the FINGERPRINT above with yours (remove all spaces!).
+
+## Adding a proof
+
+By the way, you now already have a Keyoxide profile! Go to the [URL generator](/util/profile-url), choose **keys.openpgp.org** as source and enter your fingerprint (once again without spaces) and voilà! There's the URL. Visit it by copy-pasting inside the navigation bar of your browser.
+
+Let's spice up that profile page with a proof. Adding a proof always requires you to do two steps:
+
+- telling your online account on some website about your key
+- telling your key about that account on some website
+
+By performing an action on both your online account and inside your key, Keyoxide can prove for you that you have control over both the online account and the key. Go to the [Guides](/guides) and find one that suits the online account you wish to prove: this could be a [Twitter](/guides/twitter), [Mastodon](/guides/mastodon) or [GitHub](/guides/github) account.
+
+Important note: all proofs stored inside keys start with **proof@metacode.biz=**. Never change this part!
+
+Once you've uploaded your key again as per the guide's instructions, reload your profile page: it should now have your shiny new proof with a green **Verified** label next to it. Congratulations!
+
+## HELP, AN ERROR!
+
+Is Keyoxide giving an error when you try to view your profile in the browser? Make sure that you have uploaded your key once using the [upload form](https://keys.openpgp.org/upload) **AND** that you have clicked the link inside the confirmation email: your profile page can't be displayed before this is done.

routes/main.js

@@ -47,12 +47,21 @@ router.get('/', (req, res) => {
     res.render('index')
 });
 
+router.get('/getting-started', (req, res) => {
+    const env = {};
+
+    let data = fs.readFileSync(`./content/getting-started.md`, "utf8");
+
+    let content = md.render(data, env);
+    res.render(`basic`, { title: `Getting started - Keyoxide`, content: content });
+});
+
 router.get('/faq', (req, res) => {
-    res.render('faq');
+    res.render('faq', { title: `Frequently Asked Questions - Keyoxide` });
 });
 
 router.get('/guides', (req, res) => {
-    res.render('guides');
+    res.render('guides', { title: `Guides - Keyoxide` });
 });
 
 router.get('/guides/:guideId', (req, res) => {

views/template.base.pug

@@ -12,6 +12,7 @@ header
       img(src='/static/img/logo_96.png' alt='Keyoxide logo')
     .spacer
     nav
+      a(href='/getting-started') getting started
       a(href='/') about
       a(href='/guides') guides
       a(href='/faq') faq