BERKE1337 Cyber Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Key Management ======

The use of key-pairs in GPG or OpenPGP implementations has been a standard for a very long time. Most days, encryption is done through certificate pairs such as in client-server communication but general purpose key-pairs are still used to do things like sign git commits, encrypt messages, verify the authenticity of messages, or do everything all at once.

1337NET uses a keyserver via Hockeypuck which offers public key infrastructure support through the /.well-known/ directory on 1337.berkeley.edu and internally, a HKP server for which to use the keyserver directly. By synchronizing your device's or application's keyring with our keyserver, you can verify the authenticity or encrypt/decrypt messages originating from the users on the 1337NET servers.

Below is a guide describing how to create your own key-pair with GPG, upload your public key to the keyserver, sign and encrypt files destined for particular users, and synchronize your keyring with the keyserver (among other things).

==== Downloading GPG software ====

Follow the steps to downloading the GnuPG software for your operating system/distribution [[https://www.gnupg.org/download/index.html | here]].

==== Creating your own GPG key-pair ====

Once you have installed GPG on to your device, go ahead and open up a terminal and type 
  gpg --version 
and you should see the version you have installed. If you don't see a version then you may need to double check you installed the correct version of GPG.

Next, we'll want to generate a new key-pair with the following command.
  gpg --full-generate-key
after which you will be prompted to answer a number of questions on your key details.

<code>
gpg (GnuPG) 2.2.40; Copyright (C) 2022 g10 Code GmbH
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

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? 1
</code>

Type the first option.

<code>
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (3072) 4096
</code>

Type the maximum key length 4096.

<code>
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) 0
</code>

Type the first option, unless you do in fact want your key to expire but given this is your master key you may not want this.

<code>
Key does not expire at all
Is this correct? (y/N) y
</code>

Type y to accept that the key does not expire.

<code>
Real name: Oski Bear
Email address: oski.bear@1337.berkeley.edu
Comment: 
You selected this USER-ID:
    "Oski Bear <oski.bear@1337.berkeley.edu>"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
</code>

Type in your real name and email (not Oski Bear plz). If you're planning on uploading your GPG to 1337NET we require you to use the 1337.berkeley.edu domain. For personal use, anything goes. Next, you can leave a comment which is like a description for the key or leave it blank. Finally, type O to verify everything you inputted was correct, or another character to go back and change something.

<code>
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.
</code>

At this point you should be prompted to type in a password you'll use to when using your key to encrypt, sign, and so on.

<code>
directory '/home/kinn/.gnupg/openpgp-revocs.d' created
gpg: revocation certificate stored as '/home/kinn/.gnupg/openpgp-revocs.d/28899D46BDFF81AF02DC19AA4AAE97E1338ADE17.rev'
public and secret key created and signed.

pub   rsa4096 2025-09-19 [SC]
      28899D46BDFF81AF02DC19AA4AAE97E1338ADE17
uid                      Oski Bear <oski.bear@1337.berkeley.edu>
sub   rsa4096 2025-09-19 [E]
</code>

Now you have successfully generated a key-pair. Let's break down this last block of code.
<code>
pub   rsa4096 2025-09-19 [SC]
      28899D46BDFF81AF02DC19AA4AAE97E1338ADE17
</code>
This section describes your __pub__lic key ID. rsa4096 is the encryption algorithm followed by the key length (which we set earlier, if you remember), followed by the date of creation and the abilities of the public key, which is [S]igning and [C]ertifying. 
  uid                      Oski Bear <oski.bear@1337.berkeley.edu>
This describes your user ID for the key.
  sub   rsa4096 2025-09-19 [E]
This describes a sub-key (automatically derived from your master key) used for [E]ncrypting.

We're almost done, let's enhance the security a little more.

=== Improving security and creating a subkey and revocation key ===

Type the command (replace with your email)
  gpg --edit-key oski.bear@1337.berkeley.edu

Type ''setpref SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed''

<code>
gpg (GnuPG) 2.2.40; Copyright (C) 2022 g10 Code GmbH
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Secret key is available.

sec  rsa4096/4AAE97E1338ADE17
     created: 2025-09-19  expires: never       usage: SC  
     trust: ultimate      validity: ultimate
ssb  rsa4096/556E7B3AE3E0BA6B
     created: 2025-09-19  expires: never       usage: E   
[ultimate] (1). Oski Bear <oski.bear@1337.berkeley.edu>

gpg> setpref SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
Set preference list to:
     Cipher: AES256, AES192, AES, CAST5, 3DES
     AEAD: 
     Digest: SHA512, SHA384, SHA256, SHA224, SHA1
     Compression: ZLIB, BZIP2, ZIP, Uncompressed
     Features: MDC, AEAD, Keyserver no-modify
Really update the preferences? (y/N) y

sec  rsa4096/4AAE97E1338ADE17
     created: 2025-09-19  expires: never       usage: SC  
     trust: ultimate      validity: ultimate
ssb  rsa4096/556E7B3AE3E0BA6B
     created: 2025-09-19  expires: never       usage: E   
[ultimate] (1). Oski Bear <oski.bear@1337.berkeley.edu>

gpg> save

</code>

Type y to confirm, type in your password when prompted and finally type "save" and you're done.

Next, we'll be creating a subkey for signing. The reason we're creating a subkey for signing is so that if our master key becomes compromised, we don't need to revoke our entire key chain. Since its a derivative of our master key, the stakes are generally lower so interpret this step as a precaution.

Type the following once again (replaced email with your own email).
<code>
gpg --edit-key oski.bear@1337.berkeley.edu
gpg (GnuPG) 2.2.40; Copyright (C) 2022 g10 Code GmbH
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Secret key is available.

sec  rsa4096/4AAE97E1338ADE17
     created: 2025-09-19  expires: never       usage: SC  
     trust: ultimate      validity: ultimate
ssb  rsa4096/556E7B3AE3E0BA6B
     created: 2025-09-19  expires: never       usage: E   
[ultimate] (1). Oski Bear <oski.bear@1337.berkeley.edu>

gpg> addkey
Please select what kind of key you want:
   (3) DSA (sign only)
   (4) RSA (sign only)
   (5) Elgamal (encrypt only)
   (6) RSA (encrypt only)
  (14) Existing key from card
Your selection? 4
</code>

Type "addkey", then you'll be prompted for which kind of key to add. Type 4 for "RSA (sign only)".

<code>
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (3072) 4096
Requested keysize is 4096 bits
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) 0
Key does not expire at all
Is this correct? (y/N) y
Really create? (y/N) y
</code>

Set the key length to 4096, same considerations for key expiry although this time its more acceptable to set an expiry date. After that, punch in your password once again and you should see the new subkey appear in your key list.

<code>
ssb  rsa4096/9FB69C21D624C5D2
     created: 2025-09-19  expires: never       usage: S
</code>

And there it is! The last step is creating a revocation key in the case that your signing subkey becomes compromised, it's a way of telling people not to trust that key anymore.

  gpg --output \<oski.bear@1337.berkeley.edu\>.gpg-revocation-certificate --gen-revoke oski.bear@1337.berkeley.edu

Put the file in a safe place, and with that we can move on to actually using the keys.

Much of this section was written following [[https://alexcabal.com/creating-the-perfect-gpg-keypair | this guide]].
==== Exporting and uploading your public key ====

Now that you have your public key, let's learn how to export it to a file and upload it to our keyserver. We'll finish this section by trying to pull our newly uploaded key from the 1337.berkeley.edu/.well-known./ directory on the site.

First, export your public key with the following command, replace the email with your email.

  gpg --armor --export oski.bear@1337.berkeley.edu > mykey.asc

Note, the --armor tag prefixes and suffixes the actual key with "BEGIN PGP PUBLIC KEY BLOCK" and "END PGP PUBLIC KEY BLOCK" messages. Now, you should have a file in your directory called "mykey.asc", feel free to open it up in a text editor to see the armor.

Once you have this file, **you will have to be on the VPN network for the next steps** (see [[guides:internal:labcommittee | how to get on the VPN here]]). At the time of writing this, the keys.1337.berkeley.edu subdomain is not public, there are still some uncertainties which need to be addressed with the keyserver security model. Alternatively, you can give your public key to a committee member with VPN access and they can upload the public key for you. If that is you, then follow the steps below.

In order to upload the key, we will be passing it through "curl" instead of the GPG command/using HKP protocol. This is an added layer of security which requires users uploading their keys to provide a valid 1337NET user account before interacting with the /add endpoint on Hockeypuck.

Type the following command in the terminal, substituting for your own username. (Note the "-k" flag will bypass any certificate errors we may have.)

<code>
curl -k -u [USERNAME] \
  --data-urlencode "keytext@mykey.asc" \
  https://keys.1337.berkeley.edu/pks/add
</code>

You will be prompted for your password, and after you do, your public key will be uploaded to the keyserver.

For key retrieval, paste the following curl command to your terminal.

  curl "https://1337.berkeley.edu/.well-known/openpgpkey/1337.berkeley.edu/[USERNAME]"
  
Alternatively, you can fetch keys with a hash of the user's username you want to retrieve. This is typically for machines and requires a few more steps, this method using `gpg` also requires the public key wanted for retrieval to already be in your keyring. Consider using a WKD hashing script on the username section of the email ID if you're trying to retrieve someone else's public key. We'll use our example user's hash as a demo. Run the following.

  >gpg --with-wkd-hash -k oski.bear@1337.berkeley.edu
  pub   rsa4096 2025-09-19 [SC]
      28899D46BDFF81AF02DC19AA4AAE97E1338ADE17
  uid                      [ultimate] Oski Bear <oski.bear@1337.berkeley.edu>
                           **ikyno7hk5i3tdj71446s6id9hhw5dp85**@1337berkeley.edu
  sub   rsa4096 2025-09-19 [E]
  
The advanced hash will appear a line below your name, see the above code block between the asterisks (**).

You can then paste this hash into this slightly modified curl command.

  curl "https://1337.berkeley.edu/.well-known/openpgpkey/1337.berkeley.edu/hu/ikyno7hk5i3tdj71446s6id9hhw5dp85"
  
You should be presented with that username's public key! Pretty neat, right? Because the /.well-known/ directory is a standardized and predictable URL, many clients which are GPG key-aware can be easily configured to use the keyserver to synchronize their keyrings and easily sign, encrypt, and verify messages between users. Even if you're outside of the organizations, individuals can go to the /.well-known/ directory and send encrypted messages to you or verify messages coming from you.
==== Signing, authenticating, encrypting and decrypting a file ====

The following steps involve actually using the public key infrastructure we've setup and integrated with. In summary, you will be using __your own__ private key to sign a file, something only you can do with your keypair, and then using __someone else's__ public key to encrypt the file, creating something only the recipient can decrypt. We'll be doing the two steps separately and then we'll be doing them at the same time.

First prepare a file to be sent. In this example, we'll use a text file "message.txt". You can create one of these however you like.

=== Signing and verifying a file ===

To generate a signed file with the signature embedded in the file, run the following command. In most cases, this is the most straightforward way to sign a file.

  gpg --armor --sign message.txt
  
You can also generate a signed file with a detached signature file with the following command.

  gpg --armor --detach-sign message.txt
  
Additionally, you can generate a file with the signature in plaintext with the following command.

  gpg --clearsign message.txt
  
Then, you can verify an embedded signature on the file with the following command.

  gpg --verify message.txt.asc
  
Or alternatively, if you generated the signed file with a detached signature, run the following command.

  gpg --verify message.txt.sig message.txt

=== Encrypting and decrypting a file ===

If you want to create a file that only Kinn can decrypt, first you will need his public key. Grab the key from the /.well-known/ directory with the command:

  curl "https://1337.berkeley.edu/.well-known/openpgpkey/1337.berkeley.edu/kinn" >> kinn_pubkey.gpg

Then, import the key file to your keyring and verify it's been imported.

<code>
gpg --import kinn_pubkey.gpg
gpg --list-keys
pub   rsa4096 2025-09-19 [SC]
      946D55F24263239FF342785389C3028DCEDD05F9
uid           [ unknown] Nicholas Perematko <kinn@1337.berkeley.edu>
sub   rsa4096 2025-09-19 [E]
</code>

To encrypt a file without signing it, run the command. Note you can use the email or the key fingerprint.

  gpg --encrypt --recipient kinn@1337.berkeley.edu message.txt

You can also encrypt and file and sign it at the same time, this way has the most integrity and should be the way you send messages.

  gpg --encrypt --sign --recipient kinn@1337.berkeley.edu message.txt

Now you have a file which you can securely sent to a destined recipient, and the recipient must have the corresponding private key in order to decrypt the message, and it's recommended they also pull your public key from the /.well-known/ directory to verify your signature on the message.

To decrypt a file, use the following command.

  gpg --decrypt message.txt.gpg

Or if you have a detached signature follow up with the command below.

  gpg --decrypt --verify message.txt.gpg message.txt.sig

Now you should have the raw verified file, and your message has been sent securely.

In summary, using GPG keys is a great way to send encrypted communications over potentially unsecure mediums. Generally, we'll try to use secure mediums such as our XMPP server or email server (which may or may not be up by the time of this writing) so the worry is lessened, but if you need to send messages over a different email server outside of our control, over text message, or even over Discord, any of which you don't control the server or you can't say for certain your messages are end to end encrypted, using GPG keypairs offers another way to send messages securely.

There are a few more things you can do with keys, namely employing web of trust which involves setting a trust level on a key with gpg and then signing other people's public keys to inherit said trust, but for now this should be enough to get you started. I encourage readers to go online and look at a few more applications of public keys that people have employed on their services.

==== Changing your Email ====

If you want to change your profile's information in the situation that you have inputted the wrong email, then this is the steps that you do. 

1. First you would edit the key with: 
  gpg --edit-key <ID> 
2. Then you would add the user with the new information that you desire using the command:
  <gpg> adduid
3. After adding a new uuid, save the new info using:
  <gpg> save
4. Use the command in the first step again to return to <gpg>, and choose the uuid that you desire to remove using the command:
  <gpg> uuid (the number that the uuid is located) 
You can see that you have chosen the correct one if it has a * next to it
<code>
$ gpg --edit-key oski.bear@1337.berkeley.edu
gpg (GnuPG) 2.4.7-unknown; Copyright (C) 2024 g10 Code GmbH
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Secret key is available.

sec  rsa4096/4AAE97E1338ADE17
     created: 2025-09-19  expires: never       usage: SC  
     trust: ultimate      validity: ultimate
ssb  rsa4096/556E7B3AE3E0BA6B
     created: 2025-09-19  expires: never       usage: E   
[ultimate] (1). Oski Bear <oski.bear@1337.berkeley.edu>
[ultimate] (2). Oski Bear <oski@1337.berkeley.edu>

<gpg> uid 2

sec  rsa4096/4AAE97E1338ADE17
     created: 2025-09-19  expires: never       usage: SC  
     trust: ultimate      validity: ultimate
ssb  rsa4096/556E7B3AE3E0BA6B
     created: 2025-09-19  expires: never       usage: E   
[ultimate] (1). Oski Bear <oski.bear@1337.berkeley.edu>
[ultimate] (2)*. Oski Bear <oski@1337.berkeley.edu>
</code>

Then you would simply run this command to delete the selected user:
  <gpg> deluid

<code>
<gpg> deluid 
Really remove this user ID? (y/N) y

sec  rsa4096/4AAE97E1338ADE17
     created: 2025-09-19  expires: never       usage: SC  
     trust: ultimate      validity: ultimate
ssb  rsa4096/556E7B3AE3E0BA6B
     created: 2025-09-19  expires: never       usage: E   
[ultimate] (1). Oski Bear <oski.bear@1337.berkeley.edu>

</code>