Sign with GPG using GnuPG PKCS11
Sign using GPG command line and other tools like rpmsign, debsign, and git.
General GPG commands
The following GPG commands may be useful to you when signing.
Start gpg-agent
The GPG agent is part of the GPG tool suite and helps users to bridge to the location of their signing keys. When you use DigiCert® Software Trust Manager , the GPG agent connects you to the DigiCert® Software Trust Manager cloud key storage via the SCD.
Command:
gpg --card-status
Output:
gpg --card-status gpg: WARNING: server 'scdaemon' is older than us (development < 2.2.34) gpg: Note: Outdated servers may lack important security fixes. gpg: Note: Use the command "gpgconf --kill all" to restart them. Reader ...........: [none] Application ID ...: D27600000000000000000000 Application type .: Unknown OK DigiCert One Secure Software Manager smart-card server for GnuPG ready
Verify SCD standalone
To verify that the SCD standalone runs without any issues, run:
./ssm-scd-darwin-amd64
Output:
OK DigiCert One Secure Software Manager smart-card server for GnuPG ready
Command to exit:
bye
List public keys
To list public keys in your downloaded keyring:
gpg --list-keys
Command output:
pub rsa3072 2022-05-31 [SC] 917D38F453BC677946186AA1E2EFF40CFD433E18 uid [ unknown] userid1 <jane.doe@example.com> sub rsa2048 2022-05-31 [S] sub rsa2048 2022-05-31 [S] pub nistp256 2022-05-31 [SC] DF0460CF2363E0FA9C502DD83D83032F38E2CEDC uid [ unknown] useridsmctl1 <john.doe@example.com>
List private keys
To list private keys in your downloaded keyring:
gpg --list-secret-keys
Command output:
sec> rsa3072 2022-05-31 [SC] 917D38F453BC677946186AA1E2EFF40CFD433E18 Card serial no. = D27600000000000000000000 uid [ unknown] userid1 <jane.doe@example.com> ssb> rsa2048 2022-05-31 [S] ssb> rsa2048 2022-05-31 [S] sec> nistp256 2022-05-31 [SC] DF0460CF2363E0FA9C502DD83D83032F38E2CEDC Card serial no. = D27600000000000000000000 uid [ unknown] useridsmctl1 john.doe@example.com
Environment variables for SystemD
If you are using a Linux operating system that uses SystemD (Debian, Fedora, CentOS, Red Hat, Ubuntu, OpenSUSE, Arch, and Amazon Linux), GPG is run as a non-root user, this means that your DigiCert® Software Trust Manager user environment variables are not visible in the GPG process, which runs at a system level.
GPG signing is complex, it therefore operates in “offline” mode using a local SQLite database containing all the certificates. In this model, only signing communicates to DigiCert® Software Trust Manager where the private keys are securely stored. Follow the steps below to ensure that your environment variables are accessible.
Show environment variables
To check whether your environment variables are available:
systemctl --user show-environment
注意
If you do not see the Software Trust Manager environment variables in the list, then the GPG setup and future commands will fail.
Import environment variables
To import your user defined environment variables, run:
systemctl --user import-environment
注意
Run the show-environment command again to verify whether the environment variables are found.
To kill all, run the following command:
gpgconf --kill all $ rm -rf /run/user/1000/gnupg/
To reconnect to GPG, run:
gpg --card-status
Types of GPG signing commands
The most recently created subkey will always be used as the default to sign with even if you do not have access to that subkey.
Types of GPG signing
There are three types of signing as shown below:
Embedded (binary) signing
To sign with the most recently created GPG subkey:
gpg --sign <unsigned file name>
Command sample:
gpg --sign UNSIGNED_JAR.jar
To sign with a specific subkey:
gpg -u <subkey fingerprint>! --sign <file path>
Command sample:
gpg -u 8637E05EFAF1854A23AC297CE93BF08473D9C02AC927A158! --sign C:\Users\Name\Documents\UNSIGNED_JAR.jar
Output:
gpg --verify UNSIGNED_JAR.jar.gpg gpg: Signature made Tue May 31 21:32:03 2022 IST gpg: using RSA key 3D989AF5AD0D75F44D27B9398B7EFC21C1776585 gpg: Good signature from "userid1 <jane.doe@digicert.com>" [unknown] gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: 917D 38F4 53BC 6779 4618 6AA1 E2EF F40C FD43 3E18 Subkey fingerprint: 3D98 9AF5 AD0D 75F4 4D27 B939 8B7E FC21 C177 6585
注意
You can identify the subkey fingerprint in Software Trust Manager or using the command below:
gpg --list-keys --with-subkey-fingerprint
Detached (ASCII) signing
To create an ASCII formatted signature:
gpg –-armor –sign <file>
Clearsign
To sign with clearsign:
gpg –clearsign <file>
GPG errors and solutions
The following errors may occur during GPG signing.
Card status error
Error message
gpg: error getting version from 'scdaemon': No SmartCard daemon gpg: OpenPGP card not available: No SmartCard daemon
Solution
Run the following command:
gpgconf --kill all
Pubring.kbx
Error message
Command output shows pubring.kbx instead of pubring.gpg.
Solution
Remove the default pubring.kbx from /User/<user_name>/.gnupg/
so the keys from /User/<user_name>/.gnupg/pubring.gpg
get displayed
Run:
cd /User/<user_name>/.gnupg/pubring.gpg
Run:
rm -rf pubring.kbx
Run:
gpg --list-keys
General error while signing
When attempting to sign with gpg --sign <file path>
you receive the following error:
Error message
gpg: signing failed: General error
Solution
Navigate to DigiCert ONE > DigiCert® Software Trust Manager > Logs > Signature logs > Click on the signing event > View the Error message field.
If the error message is:
User - <user ID> does not have access to the GPG keypair with ID - <GPG keypair ID>
The most recently created subkey will always be used as the default to sign with even if you do not have access to that subkey. To avoid this error, use this command to sign with a different key:
gpg -u <subkey fingerprint>! --sign <file path>
General error while signing
When attempting to sign with gpg --sign <file path>
you receive the following error:
Error message
gpg: signing failed: General error
Solution
Select one of the options below based on your method of GPG signing:
GPG keypair is offline
Error message
Provided gpg keypair <GPG keypair ID> is in OFFLINE state and cannot be used for signing. Please provide keypair in active state to be used for signing.
Solution
The most recently created subkey will always be used as the default to sign with even that subkey is in offline mod. There are three ways to avoid this error:
Switch your GPG key status to online.
Verify that the release that the key is part of, is active.
Use this command to sign with a different key:
gpg -u <subkey fingerprint>! --sign <file path>