Skip to main content

How can I rotate the server GPG keys?

Docker installation​

It is quite simple with docker to rotate your passbolt server GPG keys:

docker compose -f docker-compose-ce.yaml exec -ti passbolt rm /etc/passbolt/gpg/serverkey.asc && docker compose -f docker-compose-ce.yaml exec -ti passbolt rm /etc/passbolt/gpg/serverkey_private.asc

Destroy then recreate passbolt container and new GPG server keys will be generated:

docker compose -f docker-compose-ce.yaml up -d --force-recreate

Since the containers are now running, we need to add a new environment variable to specifically specify to the API the new fingerprint, which means you need to copy the new serverKey fingerprint:

docker compose -f docker-compose-ce.yaml exec -ti passbolt su -s /bin/bash -c “gpg --list-key” www-data
Pro tip

Search for Passbolt default user <[email protected]> with the creation date matching the day you perform the rotation. The fingerprint should be a line above e.g.,: “E52977D63A9A447D1AFB3C289DE0BA9CCA0DD42A”.

In the docker-compose-ce.yaml environment section, add the following environment variable to the passbolt service with the new fingerprint:

(..)
    environment:
      (...)
 ->   PASSBOLT_GPG_SERVER_KEY_FINGERPRINT: "ADD IT HERE"
important

After navigating with your web browser to the passbolt interface you should see a pop-up telling you that the serverKey changed. This is expected and all of your users will see this warning. It needs to be accepted to go further.

Server key has changed
fig. Server key has changed
Warning!

If you are using E2EE metadata, after the rotation, if you add new users, you will need to manually share the metadataKey with them every time in Manage Users & Groups once they perform the user registration. We don’t want that, navigate to Organisation Settings > Metadata Key, scroll down and use the “Rotate key” button to avoid that.

Other installations​

Create a temporary GPG home folder:

mkdir /tmp/gpg-temp

Generate new GPG keys:

gpg --homedir /tmp/gpg-temp --batch --no-tty --gen-key <<EOF
  Key-Type: RSA
  Key-Length: 3072
  Key-Usage: sign,cert
  Subkey-Type: RSA
  Subkey-Length: 3072
  Subkey-Usage: encrypt
  Name-Real: Passbolt default user
  Name-Email: [email protected]
  Expire-Date: -0
  %no-protection
  %commit
EOF

Replace the current GPG server keys with the new ones:

gpg --homedir /tmp/gpg-temp --armor --export [email protected] | sudo tee /etc/passbolt/gpg/serverkey.asc > /dev/null
gpg --homedir /tmp/gpg-temp --armor --export-secret-key [email protected] | sudo tee /etc/passbolt/gpg/serverkey_private.asc > /dev/null

Ensure new GPG keys owner and group are correct. Replace www-data with nginx if you are using RPM-based Linux distribution:

sudo chown www-data:www-data /etc/passbolt/gpg/serverkey_private.asc
sudo chown www-data:www-data /etc/passbolt/gpg/serverkey.asc

Get new GPG keys fingerprint from public key:

sudo gpg --show-keys /etc/passbolt/gpg/serverkey.asc | grep -Ev "^(pub|sub|uid|$)" | tr -d ' '

Ensure the fingerprint from private key is the same:

sudo gpg --show-keys /etc/passbolt/gpg/serverkey_private.asc | grep -Ev "^(pub|sub|uid|$|sec|ssb)" | tr -d ' '

Open /etc/passbolt/passbolt.php configuration file and replace old fingerprint with the new one in the passbolt section:

'passbolt' => [
      // GPG Configuration.
      // The keyring must to be owned and accessible by the webserver user.
      // Example: www-data user on Debian
      'gpg' => [
          // Main server key.
          'serverKey' => [
              // Server private key fingerprint.
              'fingerprint' => 'XXXXXXXXXXXXXXXXXXXXXXXXXXXX',
              'public' => CONFIG . DS . 'gpg' . DS . 'serverkey.asc',
              'private' => CONFIG . DS . 'gpg' . DS . 'serverkey_private.asc',
          ],
      ],

Launch a healthcheck command to get passbolt GNUPGHOME folder (usually /var/lib/passbolt/.gnupg but can be different if you installed passbolt from source):

sudo -H -u www-data bash -c "/usr/share/php/passbolt/bin/cake passbolt healthcheck --gpg" | grep GNUPGHOME

Delete the current GNUPGHOME folder, it will be automatically recreated:

sudo rm -rf /var/lib/passbolt/.gnupg

You can now delete the temporary GPG home folder:

rm -rf /tmp/gpg-temp
important

After navigating with your web browser to the passbolt interface you should see a pop-up telling you that the serverKey changed. This is expected and all of your users will see this warning. It needs to be accepted to go further.

Server key has changed
fig. Server key has changed
Warning!

If you are using E2EE metadata, after the rotation, if you add new users, you will need to manually share the metadataKey with them every time in Manage Users & Groups once they perform the user registration. We don’t want that, navigate to Organisation Settings > Metadata Key, scroll down and use the “Rotate key” button to avoid that.