Document the process of creating a subkey

[morozov]

[…] a password-less private GPG key in ASCII format, to be used for signing your releases:
please use a dedicated GPG subkey for this purpose.

For non-experienced in GnuPG users like myself, it will be helpful to have more detailed documentation on creating the signing subkey and exporting it to GitHub.

[Ocramius]

if anyone can confirm that this is correct, please give me a thumbs up, or send a patch to include the guide in README.md or in a sub-dir.

Here's how I did it:

1. gpg --edit-key "$YOUR_MASTER_KEY_ID": this opens an interactive prompt
2. type addkey
3. when asked for capabilities, select signing or S. I picked RSA, but that's mostly for compatibility with ancient systems
4. type save

Now there is a subkey under your master key.

Remove password protection from the subkey

If your master key is password-protected (typical, and generally endorsed), we need to un-protect the sub-key.

To do that, as far as I know, the only reliable way is to delete your master key and import only the subkey:

1. gpg --armor --export-secret-keys "$YOUR_MASTER_KEY_ID" > master-key.backup.asc (hold on to this! DO NOT LOSE IT!)
2. gpg --export-secret-subkeys "$NEW_SUBKEY_ID!" > subkey.asc (the exclamation mark is important, otherwise it exports everything)
3. gpg --delete-secret-keys "$YOUR_MASTER_KEY_ID"
4. gpg --import subkey.asc
5. gpg --edit-key "$NEW_SUBKEY_ID!": this opens an interactive prompt
6. passwd (enter current password, then leave empty to remove the password requirements)
7. save

Export the secret subkey

1. gpg --armor --export-secret-subkeys "$NEW_SUBKEY_ID!" > release-subkey.asc (note: exclamation mark important)
2. If you followed the steps above to un-protect your subkey, re-import your master key via gpg --import master-key.backup.asc
3. go to https://github.com/organizations/<your-organization>/settings/secrets or https://github.com/<user>/<repo>/settings/secrets and enter the contents of release-subkey.asc as a new SIGNING_SECRET_KEY secret
4. gpg --armor --export "$YOUR_MASTER_KEY_ID" > public-key.asc
5. go to https://github.com/settings/keys and add your GPG key (or delete/re-add it - this is needed each time a new subkey is created)
6. delete all .asc files created in the process after verifying that all is working as expected

[morozov]

A couple of notes (still testing this):

1. At least in my case (gpg (GnuPG) 2.2.19), gpg --list-keys doesn't display subkey identifiers unless the --keyid-format=LONG switch is used.
2. After a new subkey is created, depending on how signingkey is configured, Git may start using the new signing key instead of using the one it used before (ref). You may need to add the exclamation mark to the key identifier the same as you'd add it to the export command.

[morozov]

After having exported the signing key and created the secret in the repository, is there a way to check that the action will be able to use the secret to sign the release w/o going through the entire release cycle (i.e. create a milestone, associate an issue, resolve and close the milestone)?

[Ocramius]

@morozov there's no "preflight check" feature, but that's an interesting thing that could possibly be added to the action installation.

Worst case scenario, you get a failed CI task and no changes on the repository.

[Ocramius]

2. After a new subkey is created, depending on how signingkey is configured, Git may start using the new signing key instead of using the one it used before (ref). You may need to add the exclamation mark to the key identifier the same as you'd add it to the export command.

Good to know! I don't have any keys installed on my system anymore, and I only import my master key from a secure (detached) storage when creating new subkeys. Otherwise, my only subkeys are on yubikeys, hence I never noticed this behavior, in which gpg switches the default key used for signing 🤔

[Slamdunk]

is there a way to check that the action will be able to use the secret to sign the release w/o going through the entire release cycle (i.e. create a milestone, associate an issue, resolve and close the milestone)?

When we need to test the release process, we leverage the -alphaNNN suffix to the version: yes the repository is still polluted with useless tags and the package with useless versions released, but [1] the final user doesn't get bothered since they are pre-releases ignored by default by composer (and in general by semver compliant package managers) and [2] the test is real.

OT: it's 2020 and GPG is still a PITA even for ninja devops 🤕

[Ocramius]

@Slamdunk I think what you want is #25

[morozov]

The instructions worked for me. Thank you 🙏

[Ocramius]

Ok, so next up is for someone to put this stuff in a .md file and send a patch to the repo :D

Note: I don't think this should be in README.md: that file is already quite large now.

[glensc]

This ("So next up is for someone to put this stuff in a .md file and send a patch to the repo") looks to be done with #77

Issue close time?