Tor Browser Signing Key
=======================

Preparations:
-------------

1) Go offline (ideally use Tails)
2) Mount your encrypted offline storage device
3) If not already done prepare the gpg.conf used for that device
   (See: https://help.riseup.net/en/security/message-security/openpgp/best-practices
   for help)
4) `export GNUPGHOME=/path/to/offline/storage/.gnupg`

Key Creation Incantations and Instructions
------------------------------------------

1) `gpg --gen-key --expert`
2) Choose "(8) RSA (set your own capabilities)a"
3) Choose "(S) Toggle the sign capability"
4) Choose "(E) Toggle the encrypt capability"
5) Choose "(Q) Finished"
6) Choose 4096 bit
7) Type "5y"
8) Choose "Tor Browser Developers" as real name
9) Choose "torbrowser@torproject.org" as email address
10) Choose "signing key" as comment
11) Choose a strong passphrase to protect your keys
12) `gpg --edit-key YOURMASTERKEYID`
13) At the gpg> prompt enter: addkey
14) Choose "(4) RSA (sign only)"
15) Repeat step 6, 7 (with "2y" for subkeys), 13 and 14 as often as needed
16) At the gpg> prompt enter: save
16) Check whether the keys look good, e.g. with
   `hkt export-pubkeys --keyring /path/to/pubring.gpg YOURMASTERKEYID | hokey lint`
17) `gpg --export-secret-subkeys SUBKEYID_N! > subkeys_n`
18) `gpg --export YOURMASTERKEYID > pubkeys`
19) Repeat 17) as needed
20) Send subkeys_n and pubkeys to recipients
21) `gpg --output revoke.asc --gen-revoke YOURMASTERKEYID`

Publish updated key in Tor's Keyring
------------------------------------

Update the key in Tor's WKD keyring after the long-term key's expiration date
is extended or a new subkey is created. Open a new Issue under TPA > team and
attach the updated key.

https://gitlab.torproject.org/tpo/tpa/team/-/issues

For example: https://gitlab.torproject.org/tpo/tpa/team/-/issues/40039

MAR Signing Key
===============

Preparations
------------

1) Go offline (ideally use Tails)
2) Mount your encrypted offline storage device
3) `cd /path/to/offline/storage`
4) make sure you have libnss3-tools installed (for certutil)
   (or use the one we built ourselves which is included in mar-tools)

Key Creation Incantations and Instructions
------------------------------------------

1) `mkdir nssdb`
2) `certutil -d nssdb -N`
3) Choose a strong passphrase to protect the key
4) `certutil -d nssdb -S -x -g 4096 -Z SHA384 -n marsigner -s "CN=Tor Browser MAR signing key" -t,,`
5) If there should be additional keys in the database repeat step 4. Note, you
   need a different CN and ideally a different nickname ("marsigner" in the
   example above).
6) `certutil -d nssdb -L -r -n marsigner -o marsigner.der`
7) If you want to export more than one certificate repeat step 6 adjusting the
   certificate nickname and the name of the output file


Mac Signing Key
===============

Based on:
https://stackoverflow.com/questions/9245149/jenkins-on-os-x-xcodebuild-gives-code-sign-error


cd Library/Keychains
security create-keychain tbb-signing-alpha.keychain
security default-keychain -s tbb-signing-alpha.keychain
security unlock-keychain
certtool r CertificateSigningRequest.certSigningRequest
# RSA, 2048, RSA with SHA384, "Thisisachallengestring"
# Common Name       (e.g, www.apple.com) : Tor Browser Signing Key
# Country           (e.g, US) :
# Organization      (e.g, Apple, Inc.) : The Tor Project, Inc.
# Organization Unit (e.g, Apple Software Engineering) : Applications Engineering
# State/Province    (e.g, California) : Washington
# Email Address     (e.g, username@apple.com) : torbrowser@torproject.org

# Submit to Apple, download certificate.

security add-certificates ~/developerID_application.cer
security find-identity


APK Signing Key
===============

These instructions are for a Nitrokey, as described in
https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues/26536

Software needed:
----------------

1) Android SDK build tools

 - Latest (at time of writing):
   - https://developer.android.com/studio?hl=i#downloads
   - https://dl.google.com/android/repository/commandlinetools-linux-6609375_latest.zip
   - 89f308315e041c93a37a79e0627c47f21d5c5edbe5e80ea8dc0aac8a649e0e92

Installation
------------

1) Requirements

- for the signing: sudo apt-get install nitrokey-app opensc-pkcs11 opensc openjdk-8-jdk
  - https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues/26536#note_2651175

`nitrokey-app` should automatically detect the nitrokey if it is connected
Debian Stretch provides version 0.6.3-1.

  $ nitrokey-app

Expect: "Application started successfully."


Key Generation
--------------

1) Generate 4096-bit RSA key pair

  $ openssl genrsa -out secretkey.pem -aes128 -rand /dev/urandom 4096

2) Create CSR

  $ openssl req -new -key secretkey.pem -out request.pem -subj "/CN=Tor Browser/O=The Tor Project/L=Seattle/ST=WA/C=US"

3) Generate certificate (Google Play requires minimum expiratation date of 22 October 2033
  # If you plan to publish your apps on Google Play, the key you use to sign
  # your app must have a validity period ending after 22 October 2033. Google
  # Play enforces this requirement to ensure that users can seamlessly
  # upgrade apps when new versions are available.
  # https://developer.android.com/studio/publish/app-signing#considerations

  $ openssl x509 -req -days 5475 -in request.pem -signkey secretkey.pem -out certificate.pem -extfile openssl.cnf -extensions usr_cert

4) Export secret key and certificate in PKCS12

  $ openssl pkcs12 -export -out secret_and_certificate.p12 -in certificate.pem -inkey secretkey.pem -aes128

5) Extract RSA public key

  $ openssl rsa -in secretkey.pem -pubout -out publickey.pem

Install private signing key on Nitrokey
---------------------------------------

- pkcs15-init --delete-objects privkey,pubkey,chain                 \
              --id 3 --store-private-key secret_and_certificate.p12 \
              --format pkcs12 --auth-id 3 --verify-pin
