Skip to main content

GnuPG PKCS11 SCD

GnuPG suite, also known as GnuPG, is a complete collection of cryptographic software tools that includes GnuPG itself along with various other utilities. GnuPG is an implementation of the OpenPGP (Pretty Good Privacy) standard, which enables secure communication and data encryption. The suite includes command-line tools for key management, encryption, decryption, signing, and verification, providing a comprehensive set of cryptographic capabilities. GnuPG suite offers a broader range of command line tools and utilities that can be used on various operating systems, including macOS, Windows, and Linux. GnuPG Suite is widely used by developers, system administrators, and advanced users who prefer the flexibility and power of the command line.

Limitations

GnuPG PKCS11 SCD does not support ECDSA and EdDSA keys, it has third-party dependencies, and requires a x.509 certificate.

Tip

DigiCert​​®​​ Software Trust Manager offers a streamlined alternative to GnuPG PKCS11 SCD, called GPG Smartcard Daemon (SCD). Using GPG SCD is recommended over GnuPG PKCS11 SCD because:

  • Provides a user-friendly and powerful userface and CLI to manage GPG keys.

  • Supports all popular operating systems including nix*, Windows, and MacOS.

  • Supports all popular asymmetric algorithms for digital signatures.

  • Enhanced protection for GPG keys.

  • Compatible with GnuPG 2.x tools.

  • Does not require a x.509 certificate.

Prerequisites

  • Install GPG

  • Install and configure one of the following:

  • GPG master key

Install GnuPG PKCS11 SCD

To install packages (gpg, smartcard, daemon, sqlite3):

sudo apt install -y gpg gnupg-pkcs11-scd sqlite3

Note

If the installation is successful, proceed to the Configure GnuPG PKCS11 SCD section.

If the output of this command is no package found, it means that GPG PKCS11 SCD is not available in the software repositories. Follow the instructions below to compile and build GPG PKCS11 SCD so that it can be used in the GPG setup.

Build and compile GnuPG PKCS11 SCD

To compile and build gnupg-pkcs11-scd:

  1. To install the epel-release package and enable dependencies required to build the smartcard daemon, use the command:

    dnf install -y epel-release
  2. To install the dependencies for building and compiling gnupg-pkcs11-scd, run:

    dnf install -y pkcs11-helper-devel libgpg-error-devel libgcrypt-devel wget lbzip2 gcc
    
    dnf --enablerepo=powertools install libassuan-devel
  3. To download the latest release of gnupg-pkcs11-scd and extract it, run:

    wget https://github.com/alonbl/gnupg-pkcs11-scd/releases/download/gnupg-pkcs11-scd-0.9.2/gnupg-pkcs11-scd-0.9.2.tar.bz2
  4. To go into the directory, and build gnupg-pkcs11-scd, run:

    cd gnupg-pkcs11-scd-0.9.2
    ./configure #This should not return any errors
    make
    make install

Tip

This process should build the smartcard daemon executable and place it in /usr/local/bin.

  • Recommended

    Copy the smartcard daemon executable to /usr/bin to make it immediately available, or add this directory to the PATH environment variable.

  • Alternative

    Keep the smartcard daemon executable in /usr/local/bin and change the path to the smartcard daemon in the gpg agent config.

Configure GnuPG PKCS11 SCD

To configure gnupg-pkcs11-scd:

  1. Open an integrated development environment (IDE) or plain text editor.

  2. Copy the following text into the file:

    verbose
    debug-all
    providers dy
    provider-dy-library <Path to Software Trust Manager PKCS11 library>
  3. Save the file as gnupg-pkcs11-scd.conf.

    Tip

    Specify the absolute path to smpkcs11.so in provider-dy-library, for example:

    provider-dy-library home/DigiCert/DigiCert One Signing Manager Tools/smpkcs11.so

RSA GPG key required

GnuPG SCD requires an RSA key. The KEY-FRIENDLY value of a private key stored in Software Trust Manager is required to create an RSA key. The instructions below will start the smart card daemon to use the interface and identify the KEY-FRIENDLY value.

Generate keypair

You require the View keypair and Generate keypair permission to create a keypair.

You can generate an RSA keypair from Software Trust Manager or SMCTL.

Identify KEY-FRIENDLY value

To identify the KEY-FRIENDLY value:

  1. To start smart card daemon:

    gnupg-pkcs11-scd --server verbose            
  2. To list the objects on the screen:

    learn
  3. Scroll up to find the KEY-FRIENDLY values.

    Sample:

    KEY-FRIENDLY 3383BA6F3958077801F2C7BDCF39AF5A9C4
  4. To exit the smart card daemon:

    bye            

Generate GPG key

If you do not have a local GPG key, follow the steps below to create one:

  1. Run:

    gpg --expert --full-generate-key
  2. For the key type, select option 13:

    Please select what kind of key you want:
       (1) RSA and RSA
       (2) DSA and Elgamal
       (3) DSA (sign only)
       (4) RSA (sign only)
       (7) DSA (set your own capabilities)
       (8) RSA (set your own capabilities)
       (9) ECC (sign and encrypt) *default*
       (10) ECC (sign only)
       (11) ECC (set your own capabilities)
       (13) Existing key
       (14) Existing key from card
    Your selection? 13
    
  3. Enter your your GPG keypair fingerprint as the keygrip:

    Enter the keygrip:
  4. Select Q to finish:

    Possible actions for a RSA key: Sign Encrypt Authenticate 
    Current allowed actions: Sign Encrypt 
    
       (S) Toggle the sign capability
       (E) Toggle the encrypt capability
       (A) Toggle the authenticate capability
       (Q) Finished
  5. Specify 0 for the key validity so that it does not expire:

    Please specify how long the key should be valid.
    
            0 = key does not expire
          <n>  = key expires in n days
          <n>w = key expires in n weeks
          <n>m = key expires in n months
          <n>y = key expires in n years
    Key is valid for? 0
  6. Specify Y if the key validity is correct:

    Is this correct? (y/N) y
  7. Provide your full name, email address, and comment if necessary to create your user ID (UID):

    GnuPG needs to construct a user ID to identify your key.
    
    Real name: John Doe
    Email address: john.doe@example.com
    Comment: Pass
    
  8. Select O if the information is correct:

    You selected this USER-ID:
        "John Doe (Pass) john.doe@example.com"
    
    Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O

Optional commands

The following issues may need affect signing:

Remove ECDSA and EdDSA keys

GnuPG PKCS11 SCD does not support ECDSA and EdDSA keys. These steps are only required if ECDSA and, or EdDSA keys are present.

To remove ECDSA and EdDSA keys:

  1. To set offline environment variables:

    export SM_PKCS11_OFFLINE_MODE=true
    export SM_PKCS11_DB_DSN=~/smtools-linux-x64/gnupg.db
    
    env | grep SM         
  2. To create a local database with all the certificates from the service, using the keytool command:

    keytool -list -keystore NONE -storepass NONE -storetype PKCS11 -providerclass sun.security.pkcs11.SunPKCS11 -providerarg ./conf/pkcs11properties.cfg         
  3. To verify gnudb.db database created:

    ls -lrt | grep *.db         
  4. To remove non-RSA keys from the database:

    1. To open the database with SQLite3:

      sqlite3 ~/smtools-linux/gnupg.db
    2. To count the objects:

      select COUNT(*) from PKCS11_OBJECT;
    3. To delete any entries that are non-ECC:

      delete from PKCS11_OBJECT where object_id in (select distinct object_id from PKCS11_object where cka_key_type=3);

      Note

      This command removes any keys of cka_key_type=3 (ECC).

    4. To exit SQLite3:

      .quit

Identify keypair ID

To identify the keypair ID:

  1. To start smart card daemon:

    gnupg-pkcs11-scd --server verbose            
  2. To list the objects on the screen:

    learn
  3. Identify the KEYPAIRINFO field.

  4. Identify the hex code after the last /.

    Sample:

    x20Token/62373536306330652D65353130646155383037
  5. To decode the hex code to ASCII and return the keypair ID, use the xxd utility or any hex to ASCII converter.

    Sample command:

    echo "31383836373962372D306437372D343465352D616238332D613234393865306332393334" | xxd -r -p && echo            

    Note

    This keypair ID is required in the next step when you generate a RSA GPG key.

  6. To exit the smart card daemon:

    bye