Getting started

Glad you made it here :)

Let’s get you started on setting up your online identity and profile page.

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.

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):

         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 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, 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:

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 and find one that suits the online account you wish to prove: this could be a Twitter, Mastodon or 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 AND that you have clicked the link inside the confirmation email: your profile page can’t be displayed before this is done.