Documentation  ❯  Crypto Providers   ❯   GPG

Overview

GNU Privacy Guard, also known as GPG or GnuPG, is an Open Source implementation of the OpenPGP standard. This section provides information about using GPG with SignPath, as well as some code signing tools that build on GPG.

Using GnuPG with PKCS #11

GnuPG does not directly support the PKCS #11/Cryptoki interface. The gnupg-pkcs11-scd project adds this capability as a daemon for the GnuPG “Smartcard” interface.

Setup

Configuring GnuPG

Configure GnuPG to perform hash signing via SignPath:

• Configure the SignPath Crypto Provider
• Configure gnupg-pkcs11-scd via gnupg-pkcs11-scd.conf
• Configure GnuPG (gpg-agent) to use gnupg-pkcs11-scd

For more details and prerequisites, see the samples/Scenarios/Gpg/GpgShared.ps1 script in the Linux container samples.

Error logs

For gnupg-pkcs11-scd, stdout console output must be disabled. Use the log files for troubleshooting.

For the Linux container samples, the following log file locations are configured:

• SignPath Cryptoki logs: samples/Scenarios/temp/SignPathLogs/*.log
• gnupg-pkcs11 logs: samples/Scenarios/temp/gnupg-pkcs11-scd.log
• GPG logs: samples/Scenarios/temp/gpg-agent.log

Prepare for signing

1. Create a GPG key in SignPath, download the GPG public key file, and copy it into the samples/Scenarios/Gpg/Keys directory.
2. Create a hash signing project and signing policy in SignPath.
3. Execute SCD LEARN to fetch the private key references. For details, see the UseSignPathCryptokiGpgConfiguration function in the GPG scenario of the Linux container samples.
4. Import the key into the GPG key chain with gpg --import . See the ImportGpgKeys function in the GPG scenario of the Linux container samples.

For referencing a specific GPG key in the later signing commands (-GpgKeyId parameter), you can use the GPG key’s fingerprint, key ID, the full user ID, or email address.

CI user ↔ signing policy assignment

We strongly recommend to use an isolated CI user for GPG signing, which is assigned to exactly one signing policy as submitter. Else the SignPath project / signing policy could not be determined unambiguously and GPG signing commands may fail with “signing failed: No secret key” errors.

Background: When performing a GPG signing operation (e.g. gpg --sign -u my-gpg-key@example.com), a GPG public key is selected. Internally (via gnupg-pkcs11), the corresponding SignPath project / signing policy is selected via the GPG key’s public key hash (a “keygrip” in the GnuPG lingo). This means that when two or more signing policies are referencing the same GPG key, the signing policy cannot not be determined unambiguously and gnupg-pkcs11 would just filter out these signing policies, resulting in “missing key” errors.

Signing code with GPG

GPG File Signing

The Linux container samples contain a full example to sign and verify a file with a detached signature (including the mentioned preparation steps) within Scenarios/Gpg/GpgSignFile.ps1.

During gpg --sign, SignPath is called to perform a hash based signing operation. Note that the OrganizationId and the ApiToken still need to be passed to the SignPath Crypto Provider to authenticate the request.

RPM Signing (Linux)

The Linux container samples contain a full example to sign and verify a RPM file within Scenarios/RpmPackages/SignRpm.ps1.

During rpm --addsign, SignPath is called to perform a hash based signing operation. Note that the OrganizationId and the ApiToken still need to be passed to the SignPath Crypto Provider to authenticate the request.

DEB Signing via dpkg-sig (Linux)

The Linux container samples contain a full example to sign and verify a DEB file using dpkg-sig within Scenarios/DebPackages/SignDeb.ps1. Note the passed default “sign role” value of "builder".

During dpkg-sig --sign, SignPath is called to perform a hash based signing operation. Note that OrganizationId and the ApiToken still need to be passed to the SignPath Crypto Provider to authenticate the request.

Maven Artifact Signing (Linux)

The Linux container samples contain a full example to build, sign and verify Maven artifacts using the Apache maven-gpg-plugin within Scenarios/Maven/SignMaven.ps1. The used GPG key is referenced via its email address.

During mvn install, SignPath is called to perform a hash based signing operations. Note that the OrganizationId and the ApiToken still need to be passed to the SignPath Crypto Provider to authenticate the request.