References

• Associating an email with your GPG key
• Telling Git about your signing key
• How to enable SSH access using a GPG key for authentication
• GPG Keys Management

Creating GPG secret key

Ensure GPG is Installed

1
2

gpg --version
brew install gpg

Generate or Import a GPG Key

1

gpg --full-gen-key

1

gpg --import /path/to/your/private-key.asc

Set the Default GPG Key

1

gpg --list-secret-keys --keyid-format LONG <EMAIL>

1
2
3
4

sec   rsa4096/30F2B65B9246B6CA 2017-08-18 [SC]
      D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA
uid                   [ultimate] Mr. Robot <your_email>
ssb   rsa4096/B7ABC0813E4028C0 2017-08-18 [E]

Find the key you want to use and note its ID. Set it as the default by adding it to your Maven configuration in the settings.xml file or your pom.xml.

1
2
3

<properties>
    <gpg.keyname>YOUR_KEY_ID</gpg.keyname>
</properties>

Alternatively, you can set it globally for GPG by running:

1

gpg --default-key <YOUR_KEY_ID>

To show the associated public key, run this command, replacing with the GPG key ID from the previous step:

1

gpg --armor --export <YOUR_KEY_ID>

Change identity for a GPG key

to list the long form of the GPG keys for which you have both a public and private key. A private key is required for signing commits or tags.

1
2
3
4
5
6

$ gpg --list-secret-keys --keyid-format=long
/Users/hubot/.gnupg/secring.gpg
------------------------------------
sec   4096R/3AA5C34371567BD2 2016-03-10 [expires: 2017-03-10]
uid                          Hubot <hubot@example.com>
ssb   4096R/4BB6D45482678BE3 2016-03-10

In this example, the GPG key ID is 3AA5C34371567BD2:

1

$ gpg --edit-key 3AA5C34371567BD2

to add the user ID details.

1
2
3
4
5

$ gpg> adduid
  Real Name: OCTOCAT
  Email address: "octocat@github.com"
  Comment: GITHUB-KEY
  Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit?

Enter O to confirm your selections.

Enter your key’s passphrase.

To save the changes.

1

$ gpg> save

To print the GPG key in ASCII armor format

1

$ gpg --armor --export 3AA5C34371567BD2

Copy your GPG key, beginning with -----BEGIN PGP PUBLIC KEY BLOCK----- and ending with -----END PGP PUBLIC KEY BLOCK-----.

Telling Git about your signing key

Telling Git about your GPG key

If you have previously configured Git to use a different key format when signing with --gpg-sign, unset this configuration so the default format of openpgp will be used.

1

$ git config --global --unset gpg.format

To set your primary GPG signing key in Git

1

$ git config --global user.signingkey 3AA5C34371567BD2

Telling Git about your SSH key

Configure Git to use SSH to sign commits and tags:

1

$ git config --global gpg.format ssh

To set your SSH signing key in Git

1

$ git config --global user.signingkey ~/.ssh/id_ed25519.pub

or copy the SSH public key to your clipboard.

1
2

$ pbcopy < ~/.ssh/id_ed25519.pub
# Copies the contents of the id_ed25519.pub file to your clipboard

To set your SSH signing key in Git

1

$ git config --global user.signingkey 'ssh-ed25519 AAAAC3(...) user@example.com'

Enable signing in Git

1

git commit -S -m "My signed commit"

To avoid needing -S every time

1

git config --global commit.gpgSign true

Now you can just run

1

git commit -m "My commit"

And it will be signed automatically.

Bitbucket Pipelines Setup

The private-key.gpg.enc file is an openssl-encrypted, GPG key file, that contains the key required for signing all files. The unencrypted key file can exported with gpg:

1

gpg -a --export-secret-key KEYID > private-key.gpg

Before checking it into the bitbucket repository, it was encrypted with openssl:

1

openssl aes-256-cbc -md sha512 -pbkdf2 -iter 100000 -salt -pass pass:$OPENSSL_PWD -p -in private-key.gpg -out private-key.gpg.enc

The password value for the openssl encryption and decryption is stored in the OPENSSL_PWD environment variable configured in Bitbucket and used in the bitbucket-pipelines.yml script.

The settings.xml is configured to access environment variables for the authentication to OSSRH as well the GPG signing:

• OSSRH_USER_TOKEN and OSSRH-PWD_TOKEN: The username and password tokens for your OSSRH account as an alternative to your actual username and password. You can retrieve the token values by logging into OSSRH.
• GPG_KEY: the name of the GPG key file to use for signing e.g. F784FAB8
• GPG_PWD: the password to access the GPG key

Copying a GPG key from one account to another

1. Export Keys from the Source Account

List Keys to find your Key ID:

1

gpg --list-secret-keys

Export Public Key:

1

gpg --armor --export YOUR_KEY_ID > public.asc

Export Private Key: This step will require your GPG passphrase.

1

gpg --armor --export-secret-keys YOUR_KEY_ID > private.asc

Export Trust Data (Optional): This preserves your trust settings for the keys.

1

gpg --export-ownertrust > trust.txt

2. Transfer the Files Since these files contain your private key, use a secure method like scp

3. Import Keys to the Destination Account

Import Keys:

1
2

gpg --import public.asc
gpg --import private.asc

Import Trust Data:

1

gpg --import-ownertrust trust.txt

4. Verify and Set Ultimate Trust If you did not import a trust database, GPG may show “trust undefined.” You should manually set Ultimate Trust for your own key:

a. Run gpg –edit-key YOUR_KEY_ID.
b. Type trust and press Enter.
c. Enter 5 for “ultimate trust” and confirm with y.
d. Type quit to exit.

5. Important Considerations

• Permissions: Ensure the .gnupg directory in the new account has correct permissions (700), often requiring chmod 700 ~/.gnupg.
• Git Configuration: Update your Git config on the new account to use the imported key, or you can copy ~/.gitconfig from the old user to the new user.

1

git config --global user.signingkey your_key_id

• Windows/Git Bash: If transferring to Windows, ensure files are not encoded with BOM (Byte Order Mark) to avoid import errors.
• Alternatively, you can copy the entire ~/.gnupg directory from the old user to the new user, ensuring ownership is updated with chown -R.