Working with GPG

With Code Sign Manager, your organization can sign files, packages, and git commits with GPG, and encrypt with GPG, while the private keys stay under central control:

• Secure key storage. GPG keys are stored in the Trust Protection Foundation Secret Store or on a connected HSM. The private keys never leave the Trust Protection Foundation server.
• Keys synced to signing workstations. The Code Sign Client syncs each user's keys to their workstation and presents them to GPG as a smart card. Developers keep using the standard gpg and git commands.
• Keys for each developer. With a per-user GPG Environment, each developer gets their own key pair, issued the first time they sync.
• Public keys published for verification. Share public keys by exporting them, through the GPG public key server, or by uploading them to GitLab automatically, so that GitLab shows signed commits as Verified.

Who does what

Role	Responsibilities
GitLab administrator (optional)	Creates the GitLab personal access token for automatic key uploads.
Code Signing Administrator	Creates the GPG Environment Template, and optionally the Git Signing Connector that connects to GitLab.
Project Owner	Creates the Project and the GPG Environment, and adds the Key Users who can use the keys.
Key User	Installs the Code Sign Client, syncs keys, and signs.

Setting up GPG signing

Follow these steps in order. Steps 1 and 2 are needed only if you want public keys uploaded to GitLab automatically.

1. Prepare GitLab (GitLab administrator, optional). Create a personal access token for Code Sign Manager to use. See Preparing GitLab for GPG key provisioning.

2. Create a Git Signing Connector (Code Signing Administrator, optional). The connector stores the GitLab address and token. See Create a Git Signing Connector.

3. Create a GPG Environment Template (Code Signing Administrator). Choose the template type:

   • A single key template provides one shared key, for example for signing release packages.
   • A per-user template gives each Key User their own key. Use it for git commit signing. To upload keys to GitLab, select the connector in the template's Git Connector list, and set E-mail to an address that matches each user's GitLab account.

   See Create Environment Templates.

4. Create the Project and GPG Environment (Project Owner). Create a Project, or open an existing one, and add a GPG Environment based on the template. Add the Key Users who can use the keys. If the template's Flow requires approval, the Environment can be used after it's approved. See Creating Code Sign Manager Projects and GPG Environment.

5. Install the client (Key User or an IT administrator). Install the Code Sign Client on each signing workstation. See Install Code Sign Clients on signing workstations.

6. Sync keys (Key User). Configure GPG and run gpgconfig sync. For a per-user Environment, the first sync issues the user's keys. If the template uses a Git Signing Connector, the public signing key is then uploaded to the user's GitLab account. See Configuring GPG clients with per user Environments or Configuring GPG clients with single key Environments.

7. Sign (Key User). See Signing and encrypting with GPG and Signing git commits with GPG.

8. Share public keys. Make sure the people and systems that verify signatures have the public keys. See Sharing public keys.

If you use automatic GitLab uploads, you can check each key's upload status on the Environment's Instances tab. See Managing GitLab key uploads.

Sharing public keys

Anyone who verifies a signature needs the matching public key. Choose a method based on who needs it:

Method	Use it when
Exporting and importing a public key	You want to give the key to specific people, or publish it on a web page.
GPG public key server	GPG clients should find keys automatically by email address.
Publishing GPG keys to GitLab automatically	GitLab should show signed commits as Verified. GitLab only checks keys in each user's GitLab account. It doesn't look up keys on the public key server.