GPG

The CORE integration with the GPG2 includes two steps: enabling the CORE plugin in the GPG2 Agent infrastructure and importing proxies of the CORE keys into GPGClosedGNU Privacy Guard - PGP cryptography implementation keyrings.

This section describes the steps required to prepare a GPGClosedGNU Privacy Guard - PGP cryptography implementation machine to use the gpg2 commands while the key material is stored in the CORE and crypto-operations are performed by the CORE. The preparation includes:

Note
1. To manage the proxy keys and to troubleshoot the infrastructure, see the corresponding topics in ucl pgp-key.
2. If you need to export a public key in GPGClosedGNU Privacy Guard - PGP cryptography implementation format from CORE, see Export PGP Public Key.

Specification

Prerequisites:

  • CORE (UKC) user performing this command:
    • Has the OS permission to write to the $HOME directory.
    • Has the CORE (UKC) permission to sign crypto material.

Supported crypto:

  • The key material type: RSA.
  • Crypto operations: Signing, Decryption.

Preparation

CORE Client Preparation

Install, configure and activate CORE client on the system that uses GPGClosedGNU Privacy Guard - PGP cryptography implementation.

CORE Client Installation

On the machine that shall use GPGClosedGNU Privacy Guard - PGP cryptography implementation integrated with CORE:

  1. Install the CORE client. See Install Client Software.
  2. Check connectivity to the CORE service and its readiness to handle CORE requests:

    3. curl --insecure -X GET 'https://<EP>[:<port>]/api/v1/info'

    Use the <EP> and, optionally, the <port> values as they are set in the /etc/ekm/client.conf file.

CORE Server Preparation

Using CORE management CLIClosedCommand Line Interface or UI:

  1. As needed, create or update the CORE partition that stores keys and certificates used by the GPGClosedGNU Privacy Guard - PGP cryptography implementation server. See Create Partition.

    2. For example:

    ucl partition create -n test

  2. Pre-activate the client. See Step 1 - Create Client Name and AC.

    3. For example:

    ucl client create -n gpgserver -p test -m ACTIVATION

CORE Client Onboarding

On the machine that shall use GPGClosedGNU Privacy Guard - PGP cryptography implementation integrated with CORE:

  1. Register the machine with the partition. See Step 2 - Register a Machine using AC.

    2. For example:

    ucl register -n gpgserver -p test -c **********

  2. Generate or import the RSA key used for GPGClosedGNU Privacy Guard - PGP cryptography implementation.

    3. For example:

    ucl generate -t RSA -n my-key

  3. Check that the generated or imported key is present in the partition:

    4. ucl list

GPG Infrastructure Preparation

GPGClosedGNU Privacy Guard - PGP cryptography implementation-specific preparations include:

GPG Keyrings

GnuPG (GPG2) keyring infrastructure is located in the $HOME/.gnupg folder. As the minimum it includes the public and private ("secret") keyrings and the trust-db:

private-keys-v1.d
pubring.kbx
pubring.kbx~
trustdb.gpg

If missing, this infrastructure is created by the first GPG2 command that creates or imports the key material.

In particular, if it is missing, it is created by the first ucl pgp-key command.

GPG Agent Infrastructure

GPGClosedGNU Privacy Guard - PGP cryptography implementation Agent allows delegating crypto operations and key management to external devices ("SC" - "security cards"). It is comprised of two parts:

  • $HOME/.gnupg/gpg-agent.conf file that contains non-default GPGClosedGNU Privacy Guard - PGP cryptography implementation Agent settings and the name of the SC-specific plugin procedure.
  • Indication in the selected key's metadata that the key material is located in the specified SC.

The GPGClosedGNU Privacy Guard - PGP cryptography implementation Agent infrastructure is created by the first command that imports an SC-based key into GPGClosedGNU Privacy Guard - PGP cryptography implementation keyring.

In particular, if the $HOME/.gnupg/gpg-agent.conf file is missing, it is created by the first ucl pgp-key command.

CORE Agent Plugin

The first ucl pgp-key command adds the CORE Agent plugin into GPGClosedGNU Privacy Guard - PGP cryptography implementation Agent infrastructure:

  • Setting the SC program in the gpg-agent.conf file:

    • cat .gnupg/gpg-agent.conf

    scdaemon-program /usr/bin/ubpgpdaemon

  • Adding two new files to the $HOME/.gnupg folder:
    • .unbound-key-uid - contains the UID of the key used by the CORE Agent.
    • .unbound-daemon-pipe - for internal use.

Test the GPG Infrastructure

On the GPGClosedGNU Privacy Guard - PGP cryptography implementation server:

  1. List the RSA keys in the connected partition:

    2. ucl list -t RSA

    Partition 0 pgp: 2 objects found
    Private RSA key : UID=974553e132e913dc Name="rsa-key"
    Private RSA key : UID=c35238fc1a23e6c7 Name="my-key"

  2. Create a proxy of "my-key".

    3. ucl pgp-key -n my-key > /dev/null

  3. List the GPG2 secret keyring.
    Make sure the "my-key" appears in the list and its metadata specifies "Card serial no = **********":
    For example:

    4. gpg2 --list-secret-keys

    /home/ec2-user/.gnupg/pubring.kbx
    ---------------------------------
    sec> rsa2048 2020-01-25 [SCEA]
    89161090660E4AC61126A0C749C15D46C1E2616D
    Card serial no. = 3131 3034F20C
    uid [ unknown] my-key

    It is important to see the following:

    • The ">" character in sec> indicates that the secret key is outside the file system.
    • Card serial no. = indicates that the key is stored on the "Secure Card".
    • "my-key" in the last line is the name of the key.

      • For the additional details, see Examine Secret Keyring.

Manage UB-PGP Proxy Keys

The UB-PGPClosedPretty Good Privacy - PKI implementation proxy keys integrate with the rest of the GPGClosedGNU Privacy Guard - PGP cryptography implementation keys and are managed by GPGP2 tools. This section highlights items specific to the UB-PGPClosedPretty Good Privacy - PKI implementation proxies.

Create and Import UB-PGP Proxy

Use the command:

ucl pgp-key < -n <key-name> | -u <CORE uid>>

Examine Secret Keyring

Assuming that we already imported two keys ("pgp1" and "rsa1") into the GPGClosedGNU Privacy Guard - PGP cryptography implementation infrastructure, the secret keyring should show (at least) two entries.

gpg2 --list-secret-keys

gpg: WARNING: unsafe permissions on homedir '/home/ec2-user/.gnupg'
/home/ec2-user/.gnupg/pubring.kbx
---------------------------------
sec> rsa2048 2020-01-25 [SCEA]
89161090660E4AC61126A0C749C15D46C1E2616D
Card serial no. = 3131 3034F20C
uid [ unknown] pgp1

sec> rsa4096 2020-01-26 [SCEA]
A112BD1ECFFE999DC65F3CD480645EAFFC0843C5
Card serial no. = 3131 3034F20C
uid [ unknown] rsa1

GPG2 uses the following fields to describe the key:

Delete Proxy Key

To delete the proxy key, you must delete it from both key-rings:

gpp2 --delete-secret-key <key-name>
gpg2 --delete-key <key-name>

Mandatory Explicit and Implicit Parameters

To use CORE proxy key in GPG2 commands:

  1. Use the ucl pgp-key command to specify the key to be used by the command.
  2. Use the same key in the GPG2 command.
  3. Provide the command with the mandatory CORE Agent parameters.

Set the UB-PGP Proxy Key

Note
In the UKC 2.0.2001 release, the UKC plugin ubpgpdaemon uses the last key referred by the ucl key-pgp <UKC key> command.

This restriction creates no problems if your GPGClosedGNU Privacy Guard - PGP cryptography implementation keyring has only one CORE proxy key. However, if you are using many proxy keys, always precede its use by the command:

ucl key-pgp <required CORE key>

Note
GPGClosedGNU Privacy Guard - PGP cryptography implementation ring infrastructure ignores multiple insertions of the same proxy key, and responds as follows:
gpg: key 49C15D46C1E2616D: "<name of the CORE key>" not changed
But, if you examine <GPGClosedGNU Privacy Guard - PGP cryptography implementation Folder>/.unbound-key-uid, the content changed to the CORE UID of the <name of the CORE key>.

The common indication that the key referred by the gpg2 --sign command and the UID forwarded to the CORE mismatch, is the signature validation error. This happens because the public key that is used for the validation and the signing key mismatch.

GPG2 Parameters

To use key RSA key <key-name> stored in CORE in the GPGClosedGNU Privacy Guard - PGP cryptography implementation applications:

Use the following GPG2 Parameters:

  • Use --pinentry-mode loopback --batch
  • Specify the key-name in CORE using the -u <key-name in CORE> option.
  • If the CORE default USER has a password, specify it using the --passphrase <USER's password> option.
  • To use the command by any user of the partition, specify their credentials

    • --passphrase '{"username":"<name>", "password":"<user password>"}'

Examples

Encryption

  • Run the following command to encrypt a file:

    • gpg2 --pinentry-mode loopback --batch --output [encrypted_file.gpg] --encrypt --recipient [Real.name] [file_to_encrypt] -u <key-name>

  • Run the following command to decrypt the file:

    • gpg2 --pinentry-mode loopback --batch --output [decrypted_file.txt] --decrypt [encrypted_file.gpg] -u <key-name>

Signing

To sign an RPMClosedFile format for software package distributed by RPM Package Manager file using GPGClosedGNU Privacy Guard - PGP cryptography implementation without encrypting it, use the --detach-sign option:

gpg2 --pinentry-mode loopback --batch --detach-sign --output <rpm file>.sig <rpm file> -u <key name>

This option creates the signature file for the specified rpm file.

To check the signature use, use the --verify option with both signature and rpm files:

gpg2 --verify <rpm file>.sig <rpm file>

Note
The .sig file must precede the .rpm file