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.
Terminology
GPG uses various terms for certificates. We use the term GPG key in our GPG documentation, but keep in mind that other parts of the SignPath documentation will use the general term certificate. See Managing Certificates for more information.
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
SignPath configuration
- Create a GPG key
- Create a hash signing project and signing policy in SignPath
Configure GPG for signing
Initialize GPG hash signing using the helper function InitializeSignPathCryptoProviderGpgSigning of Samples/Scenarios/SignPathCryptoProviderHelpers.sh of the Linux samples.
This function sets up GPG using the specified parameters:
- Configures the SignPath Crypto Provider
- Sets GnuPG’s home dir (
GNUPGHOMEenvironment variable) to a temporary directory to isolate GnuPG configuration and key store changes - Configures GPG and
gnupg-pkcs11-scdand fetches the private key reference - Downloads the transferable GPG public key
- Sets the
SIGNPATH_PROJECT_SLUGandSIGNPATH_SIGNING_POLICY_SLUGenvironment variables to avoid ambiguities in the PKCS #11/Cryptoki provider (see Configuration) - Imports the GPG key and exposes its key ID via the
GPG_KEY_IDenvironment variable - Installs a Bash EXIT trap which cleans up the isolated GPG configuration
Use $GPG_KEY_ID to reference the public key
While you can use any key attribute supported by GPG, we recommend using the
GPG_KEY_IDenvironment variable provided by SignPath. This will make your scripts robust in case you select another Signing Policy or the policy is assigned another GPG key. Example:gpg --sign -u "$GPG_KEY_ID" ...
See SignPath Crypto Providers for additional configuration options including logging.
Signing code with GPG
The Linux samples contain complete example scripts (including all preparation steps) to sign and verify files using the following formats and tools:
| Format | Signing invocation | Sample script | Note |
|---|---|---|---|
| GPG detached signature | gpg --sign |
Scenarios/Gpg/GpgSignFile.sh |
|
| RPM (RedHat package) | rpmsign --resign |
Scenarios/RpmPackages/SignRpm.sh |
|
| DEB (Debian package) | dpkg-sig --sign |
Scenarios/DebPackages/SignDeb.sh |
“builder” is used as sign role |
| Maven artifact | mvn install |
Scenarios/Maven/SignMaven.sh |
Requires the Maven GPG plugin |
While executing each signing tool, SignPath is called to perform a hash-based signing operation. Note that OrganizationId and ApiToken must be passed to the SignPath Crypto Provider to authenticate the request.
Error logs
For gnupg-pkcs11-scd, stdout console output must be disabled. Use the log files for troubleshooting.
The InitializeSignPathCryptoProviderGpgSigning helper function uses the following logging directories:
- SignPath Cryptoki logs:
/tmp/SignPathLogs/<timestamp>.log gnupg-pkcs11-scdlogs:/tmp/SignPathLogs/gnupg-pkcs11-scd.log- GPG logs:
/tmp/SignPathLogs/gpg-agent.log
When using the Linux samples, the /tmp/SignPathLogs is container volume mounted to Samples/SignPathLogs.