Skip to main content

Sign with GPG using Software Trust Manager Smartcard Daemon (SCD)

Prerequisites

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

  1. 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.

  2. To kill all, run the following command:

    gpgconf --kill all
$ rm -rf /run/user/1000/gnupg/

  3. 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

  1. Run:

    cd /User/<user_name>/.gnupg/pubring.gpg

  2. Run:

    rm -rf pubring.kbx

  3. 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>
本节内容如下: