GnuPG

Configure HSM Environment

Install GPG Dependency Packages

Install Pinentry Package

Install GnuPG Package

Install gnupg-pkcs11-scd and pkcs11-helper

Verify that the HSM is set up, initialized, provisioned, and ready for deployment.

Refer to Luna HSM documentation for detailed steps on creating NTLS connection, initializing the partitions, and assigning various user roles.

Create a partition on the HSM that will be later used by GnuPG. If you are using a Luna Network HSM, register a client for the system and assign the client to the partition to create an NTLS connection. Initialize the Crypto Officer and Crypto User roles for the registered partition.

Run the following command to verify that the partition has been successfully registered and configured:

/usr/safenet/lunaclient/bin/lunacm

You should see the following output:

lunacm (64-bit) v10.7.1-125. Copyright (c) 2024 Thales Group. All rights reserved.
Available HSMs:
Slot Id ->              0 
Label ->                TPA02
Serial Number ->        1280780175916
Model ->                LunaSA 7.8.4
Firmware Version ->     7.8.4
Bootloader Version ->   1.1.5
Configuration ->        Luna User Partition With SO (PW) Key Export With Cloning Mode 
Slot Description ->     Net Token Slot
FM HW Status ->         Non-FM
Current Slot Id: 0

Enable partition policies 22 and 23 to allow activation and auto-activation, in case you are using PED-authenticated HSMs.

Refer to Luna HSM documentation for detailed steps on creating NTLS connection, initializing the partitions, and assigning various user roles.

Ensure that you possess sudo privileges on the client workstation.

Add a user to the hsmusers group using the command:

sudo gpasswd --add [username] hsmusers

Replace username with the actual username you want to include in the hsmusers group.

Confirm that you hold sudo privileges on the client workstation.

Eliminate a user from the hsmusers group using the command:

sudo gpasswd --add [username] hsmusers

Replace username with the specific username you want to exclude from the hsmusers group. To observe the changes, you will need to log in again.

Any user you remove will retain access to the HSM device until the client workstation is rebooted.

Transfer the downloaded .zip file to your client workstation using pscp, scp, or other secure means

This integration has been certified on the RHEL platform.

Extract the .zip file into a directory on your client workstation.

Extract or untar the appropriate client package for your operating system. Do not extract to a new subdirectory; place the files in the client install directory.

tar -xvf cvclient-min.tar

Run the setenv script to create a new configuration file containing information required by the Luna Cloud HSM service.

source ./setenv

To add the configuration to an already installed UC client, use the –addcloudhsm option when running the setenv script.

Run the LunaCM utility and verify the Cloud HSM service is listed.

If your organization requires non-FIPS algorithms for your operations, ensure that the Allow non-FIPS approved algorithms check box is checked. For more information, refer to Supported Mechanisms.

Access Luna HSM

Configure gnupg-pkcs11-scd.conf

Generate Keys and Certificates

Configure GnuPG to Use PKCS#11 Smart Card Daemon

Test GnuPG Integration with Luna HSM

Perform Unattended RPM Signing

Add the following text to the /etc/Chrystoki.conf file:

Misc = {
AppIdMajor=1;
AppIdMinor=1;
}

Run the following command to open the authenticated persistent session for accessing the HSM object:

./salogin -o -s 0 -i 1:1 -p 

In this command, -s specifies the slot ID, and -i specifies the AppId defined in the Chrystoki.conf file.

Create the .gnupg directory in your home folder if it does not already exist.

Create the gpg-agent.conf file inside the .gnupg directory if it does not already exist.

Open the gpg-agent.conf file in a text editor.

Add the following line to specify the Pinentry program to be used:

pinentry-program /usr/local/bin/pinentry

Locate the configuration file in the ~/.gnupg/ directory. If the file does not exist, copy the example file from either /usr/local/etc/gnupg-pkcs11-scd.conf.example or /usr/local/share/doc/gnupg-pkcs11-scd/gnupg-pkcs11-scd.conf.example and rename it as gnupg-pkcs11-scd.conf.

Open ~/.gnupg/gnupg-pkcs11-scd.conf in a text editor.

Add, modify, or uncomment the following lines:

provider-p1-allow-protected-auth
provider-p1-cert-private
provider-p1-private-mask 0

Generate a 32-byte hexadecimal value to be used as the Key ID. You can use either of the following Linux commands:

head -c16 </dev/urandom | xxd -p -u

or

xxd -len 16 -plain /dev/urandom

Use the generated hexadecimal value as the Key ID for your GPG key. GPG uses this Key ID to retrieve the key from the Luna HSM, so ensure the same Key ID is assigned to both the key pair and the certificate.

Open the CMU utility provided with the Luna Client. The CMU utility is located in the /usr/safenet/lunaclient/bin directory. Run the following command to generate RSA 2048-bit key pairs:

/usr/safenet/lunaclient/bin/cmu generatekeypair -modulusBits=2048 -publicExponent=65537 -labelPublic=GPG-Sign-Pub -labelPrivate=GPG-Sign-Priv -sign=1 -verify=1 -encrypt=1 -decrypt=1 -wrap=1 -unwrap=1 -id=c50f7b86372b441ba77cb6f8598f1e35

When prompted, enter the partition password and select the appropriate RSA Mechanism Type. For example, select PKCS by entering 1 when prompted.

Command-line parameters for the CMU utility may vary depending on the Luna Client version. Refer to the official Luna HSM documentation for details on supported options.

View the objects created on the HSM partition to verify key generation. Run the following command and make a note of the handle values assigned to the public and private keys:

/usr/safenet/lunaclient/bin/cmu list

When prompted, enter the partition password. Example output:

handle=34  label=GPG-Sign-Pub
handle=35  label=GPG-Sign-Priv

Generate a self-signed certificate using the previously created key pair.

Run the following command and provide the required certificate attributes when prompted:

/usr/safenet/lunaclient/bin/cmu selfsigncertificate -label=GPG-Sign -publichandle=34 -privatehandle=35 -startDate=20210925 -endDate=20220925 -serialNumber=0133337A -keyusage=digitalsignature,keyencipherment -id=c50f7b86372b441ba77cb6f8598f1e35
Please enter password for token in slot 0 : ********
Enter Subject 2-letter Country Code (C) : IN
Enter Subject State or Province Name (S) : UPST
Enter Subject Locality Name (L) : NOIDA
Enter Subject Organization Name (O) : THALES
Enter Subject Organization Unit Name (OU) : HSM Integration
Enter Subject Common Name (CN) : GPG-Signing
Enter EMAIL Address (E) :

For Luna Cloud HSM, replace publichandle and privatehandle with publicouid and privateouid, respectively.

During certificate generation, you will be prompted to enter attributes such as Country (C), State (S), Locality (L), Organization (O), Organizational Unit (OU), Common Name (CN), and Email (E).

Ensure that the id value remains the same for both the keys and the certificate. GPG relies on this consistency to reference the correct key objects.

If your organization does not allow self-signed certificates, generate a certificate request and have it signed by a trusted Certificate Authority.

After receiving the CA-signed certificate, import both the CA and signed certificate into the Luna HSM:

./cmu import -inputFile CA-signed-cert.crt -label GPG-Cert -private F

After importing, set the ID attribute to match the existing key pair:

./cmu setattribute -handle 53 -id c50f7b86372b441ba77cb6f8598f1e35

If you require different keys and certificates for encryption or authentication, repeat all key and certificate generation steps using unique id and label values.

Open (or create, if it does not exist) the ~/.gnupg/gpg-agent.conf file and add the following line to specify the smart card daemon program:

scdaemon-program /usr/local/bin/gnupg-pkcs11-scd

Open the ~/.gnupg/gnupg-pkcs11-scd.conf file and ensure the following configuration is present:

providers p1
provider-p1-library /usr/safenet/lunaclient/lib/libCryptoki2_64.so

If the gnupg-pkcs11-scd.conf file does not exist, copy the example configuration file from either /usr/local/etc/gnupg-pkcs11-scd.conf.example or /usr/local/share/doc/gnupg-pkcs11-scd/gnupg-pkcs11-scd.conf.example, and rename it to gnupg-pkcs11-scd.conf in the ~/.gnupg directory.

Ensure that the library path specified under provider-p1-library is correct, especially when using Luna Cloud HSM.

Set the following environment variables to ensure the correct GnuPG version and libraries are used at runtime:

export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
export PATH=/usr/local/bin:$PATH

Run the following command to allow GPG to discover available information from the connected card or HSM partition:

gpg --card-status

Run the following command to connect the GPG agent to the HSM and retrieve key information:

gpg-agent --server gpg-connect-agent

At the gpg-connect-agent prompt, enter the command SCD LEARN. The Pinentry program prompts for the partition password; after successful authentication, the output displays information retrieved from the HSM. Locate the line that begins with S KEY-FRIENDLY and note the 20-byte hash value. This value serves as the keygrip, which will be required in later steps.

Generate the GPG virtual keys using the command gpg --expert --full-generate-key and follow the on-screen prompts to select the key type and purpose, provide your real name (used for RPM signing), enter the associated email address, and specify the key validity period. The keys are not created locally; GPG only generates references to the keys stored in the HSM.

After the virtual keys have been generated, verify them by listing the keys:

gpg --list-keys

Connect the GPG agent to the HSM and retrieve key information by running:

gpg-agent --server gpg-connect-agent

At the gpg-connect-agent prompt, enter SCD LEARN. The Pinentry program prompts for the partition password; however, if a persistent session was previously opened using the salogin utility, the password prompt will not appear. Review the command output to identify the signing, encryption, or authentication certificate, locate the line beginning with S KEY-FRIENDLY, and copy the associated 20-byte SHA-1 hash.

Add the hashes to the ~/.gnupg/gnupg-pkcs11-scd.conf file as follows:

openpgp-sign 8C5CE31F726FE84CBB0891E0E2816F2EF07F0000
openpgp-encr 7990A0D320B59A0DA525CE39D15398743762EFBB
openpgp-auth 8B91705A7B3ED221AAFF5E78B95C89DD4EB0DDCD

The 20-byte hash values will be the same if the same key is used for all functions.

Enable GPG to discover the card or HSM partition details by executing the following command:

gpg --card-status

Generate the GPG virtual keys by executing the following sequence of commands: gpg --card-edit, admin, and generate. When prompted, respond y to replace existing keys, choose not to back up the keys, set the key expiry parameters, and enter the real name, which will serve as the reference for RPM signing going forward.

Sign the file by running the following command. Replace <Your key name> with the real name of the key and somefile with the actual file name:

gpg --sign --default-key <Your key name> somefile

Authenticate by entering the partition password when prompted. If a persistent session was opened using the salogin utility, no password prompt will appear. After signing, a new file named somefile.gpg is created, containing the original content and its digital signature.

Verify the signed file using the following command. The contents of the verified file should match the original file, confirming successful signing and verification.

gpg somefile.gpg

Run the following commands to initialize the terminal for GPG operations:

GPG_TTY=$(tty)
export GPG_TTY

This step is required only for GPG v2.0.x. Skip it if you are using GPG v2.2.x.

Create or update the ~/.rpmmacros file to define how RPM interacts with GPG. The file should include the following configuration:

%_signature gpg
%_gpg_path /root/.gnupg
%_gpg_name GPG-Sign
%__gpg /usr/local/bin/gpg
%__gpg_sign_cmd %{__gpg} gpg --force-v3-sigs --batch --verbose --no-armor --no-secmem-warning -u "%{_gpg_name}" -sbo %{__signature_filename} --digest-algo sha256 %{__plaintext_filename}'

Where:

• _signature must be set to gpg

• _gpg_path specifies the path to the .gnupg directory

• _gpg_name must match the user name (Real Name) of the key

• __gpg defines the full path to the GPG binary

• __gpg_sign_cmd specifies the signing command and enforces SHA-256 as the digest algorithm

Sign an RPM file by running the following command, replacing example.rpm with the actual RPM file name:

rpm --addsign example.rpm

If you need to re-sign an existing RPM, use the following command:

rpm --resign example.rpm

Ensure that the expect package is installed. If not, install it using:

yum install expect

Create an expect script using the following template, updating the key name as needed:

#!/usr/bin/expect --
spawn rpm --define "_gpg_name  GPG-Sign" --resign {*}$argv
expect {
  "Enter pass phrase:" { send "\r" ; exp_continue }
  eof
}

Save the script, make it executable, and use it to sign RPM files by running:

./<scriptname> <your_rpm>

Replace <scriptname> with the name of your script file and <your_rpm> with the actual RPM file name.

The Pinentry program may prompt for the partition password during RPM signing. If a persistent session has been opened using salogin, or if the PIN is already cached, you will not be prompted. Each RPM signing operation involves three internal signing actions, so you may be prompted multiple times if no persistent session exists.

Export the public key associated with the signing key:

gpg --export --armor <your_keyname> > <your_keyfile>

Example:

gpg --export --armor GPG-Sign > gpg.key

Import the exported public key into the local RPM keychain:

rpm --import <your_keyfile>

Example:

rpm --import gpg.key

Verify the signature on the RPM file using the following command:

rpm --checksig <your_rpm>

Example:

rpm --checksig example.rpm

If the signature is valid, you will see an output similar to the following:

example.rpm: rsa sha1 (md5) pgp md5 OK

The RPM verification output may appear generic because SHA1 and MD5 digests are part of the package metadata. To view the exact signing algorithm and related signature details, run the command rpm -q --qf '%{SIGPGP:pgpsig} %{SIGGPG:pgpsig}\n' -p example.rpm. The output will display the algorithm, timestamp, and key ID used for signing, for example: RSA/SHA256, Thursday 30 September 2021 01:50:59 AM IST, Key ID ad05dbb378832d9b (none).

Start the GPG agent daemon to cache the partition password for future signing operations:

gpg-agent --daemon

The gpg-agent process runs in the background and retains the cached partition password for the session. For details on available options and configuration parameters, refer to the official GnuPG gpg-agent documentation.

Create an Expect script to automate RPM signing.

Create a file named rpm-sign.exp and add the following content:

#!/usr/bin/expect --
spawn rpm --define "_gpg_name <your keyname here>" --resign {*}$argv
expect {
  "Enter pass phrase:" { send "\r" ; exp_continue }
  eof
}

Expect automates text-based interactions with terminal applications. To install Expect on RHEL or CentOS systems, use yum install expect expectk.

Use the created script to sign RPM packages automatically:

./rpm-sign.exp <rpm_name>

Replace <rpm_name> with the name of the RPM file you want to sign.