Clients: Sequoia-PGP

1.0 Introduction

Fortanix-Data-Security-Manager (DSM) integrates with Sequoia-PGP, a modern implementation of the OpenPGP Message Format. Sequoia has a CLI tool called sq with git-like commands for PGP operations, which are extended by sq-dsm to communicate with Fortanix DSM whenever a sensitive cryptographic operation is needed (more specifically, when signing a hash or decrypting a session key).

This article provides an overview of the Sequoia PGP, including its installation, configuration, and usage.

2.0 Operating System (OS) Compatibility

For information on the Sequoia PGP client OS compatibility matrix, refer to Clients: Compatibility Matrix.

3.0 Installation

Download and install the Fortanix Sequoia PGP library for all platforms from here.

4.0 Configuration

Set the following environment variables:

FORTANIX_API_ENDPOINT: The Fortanix DSM endpoint.
FORTANIX_API_KEY: The Fortanix DSM application’s (app) API key. It overrides FORTANIX_PKCS12_ID.
FORTANIX_PKCS12_ID: A PKCS12 identity file, for certificate-based authentication. Given a PKCS8 pair private.key and public.crtThe public certificate needs to be configured in Fortanix DSM for your app, and the PKCS12 file can be generated using the following command:
```
openssl pkcs12 -export -out identity.pfx -inkey private.key -in public.crt
```
If a password is set for the PKCS12 file, then sq-dsm will ask for it on each key usage (which can happen several times on one PGP operation).
FORTANIX_APP_UUID: The UUID of your Fortanix DSM app, for certificate-based authentication. For example, this environment variable is used together with FORTANIX_PKCS12_ID.
http_proxy and/or no_proxy (Optional).
FORTANIX_CA_FILE: A custom Certificate Authority (CA) certificate for the Sequoia client.
Run the following command to set the FORTANIX_CA_FILE environment variable:
```
export FORTANIX_CA_FILE="<CA-CERT-FILE-PATH>"
```

5.0 Usage and Commands

The binary can be invoked with ./sq-dsm and can be composed with several commands. They can be listed using the following command:

sq-dsm help

More information about a specific command is obtained with sq-dsm help <command>, for instance, sq-dsm help decrypt.

5.1 Example Usage: Signed Encryption of a File

In the following example, Alice holds a PGP key whose secrets are stored in Fortanix DSM, and Bob and Charlie hold regular PGP keys. Alice will sign, encrypt, and decrypt a file.

Perform the following steps:

Run the following commands to generate a Fortanix DSM key for Alice, and local keys for Bob and Charlie:

sq-dsm key generate --dsm-key="alice" --cipher-suite="nistp521" --userid="Alice <alice@example.com>"
sq-dsm key generate --cipher-suite="rsa3k" --userid="Bob <bob@example.com>" --export="bob.sec"
sq-dsm key generate --userid="Charlie <charlie@example.com>" --export="charlie.asc"

Run the following command to recover Alice's Transferable Public Key (TPK):
```
sq-dsm key extract-cert --dsm-key="alice" > alice.asc
```

Run the following commands to create a file, sign it with Alice's key, and verify it:

echo "Hello, World!" > msg.txt

sq-dsm sign --dsm-key="alice" msg.txt > msg.txt.signed

sq-dsm verify --signer-cert=alice.asc msg.txt.signed

Output:

Good signature from B4C961DE2204FD02
Hello, World!
1 good signature.

Run the following command to encrypt a file for Alice, signed by Bob, and decrypt it:

sq-dsm encrypt --recipient-cert=alice.asc --signer-key=bob.sec msg.txt > to_alice.asc
sq-dsm decrypt --dsm-key="alice" --signer-cert=bob.sec to_alice.asc

Output:

Encrypted using AES with 256-bit key
Compressed using ZIP
Good signature from DC4358B3EA20F2C6
Hello, World!
1 good signature.

Run the following commands to encrypt a file to Charlie, signed by both Alice and Bob, and decrypt it:

sq-dsm encrypt --recipient-cert=charlie.asc --signer-dsm-key=alice --signer-key=bob.sec msg.txt > to_charlie.asc
sq-dsm decrypt --recipient-key=charlie.asc --signer-cert=alice.asc --signer-cert=bob.sec to_charlie.asc

Output:

Encrypted using AES with 256-bit key
Compressed using ZIP
Good signature from B4C961DE2204FD02
Good signature from DC4358B3EA20F2C6
Hello, World!
2 good signatures.

5.2 Example Usage: Import an Existing Key

Given a valid PGP key, use dsm-import to import it into Fortanix DSM using the following command:

sq-dsm key dsm-import --dsm-key="Alice" < existing_pgp_private_key.asc

5.3 Example Usage: Generate Key Using a Different Key Structure

By default, the command to generate keys as explained in Section 5.1 - Example Usage: Signed Encryption of a File generates keys using the following structure:

Primary key: Certification
Subkey 1: Signing
Subkey 2: Encryption (transport & rest)

With the introduction of a new flag --key-flags, you can choose from one of the following two structures used for key generation:

--key-flags="C,S,EtEr" will generate the keys using the above-mentioned structure, and this is also the default behavior (if the flag --key-flags is not specified).

--key-flags="CS,EtEr" will generate keys using the following structure:

Primary key: Certification + Signing
Subkey: Encryption (transport & rest)

5.4 Example Usage: Import or Retrieve Transferable Public Keys to Fortanix DSM

Given a valid Transferable Public Key (TPK), run the following command to import it into Fortanix DSM:

sq-dsm key dsm-import --dsm-key="Alicepubkey" --input alice_public_key.asc

Run the following command to retrieve the TPK from Fortanix DSM:

sq-dsm key extract-cert --dsm-key="Alicepubkey" > retrieved_alice_public_key.asc

5.5 Example Usage: Import or Retrieve Keyrings to Fortanix DSM

Given a valid keyring, run the following command to import it into Fortanix DSM:
```
sq-dsm keyring dsm-import --dsm-exportable --keyring-name "<KEYRING-NAME>" --input <KEYRING-FILE> --dsm-group-id <DSM-GROUP-UUID>
```
Here,
- <KEYRING-FILE>: Path to the keyring file to be imported.
- --dsm-exportable (optional): Allows all keys imported from an external keyring to be stored as exportable in Fortanix DSM.
- --dsm-group-id <DSM-GROUP-UUID>(optional): Specifies the target Fortanix DSM group UUID into which the keyring will be imported.
Run the following command to retrieve a public keyring (containing Transferable Public Keys (TPKs)) from Fortanix DSM:
```
sq-dsm keyring extract --dsm-key-id <DSM-KEY-UUID> --dsm-key-id <DSM-KEY-UUID> --output <KEYRING-FILE>
```

Run the following command to retrieve a private keyring (containing Transferable Secret Keys (TSKs)) from Fortanix DSM:
```
sq-dsm keyring extract-secret --dsm-key-id <DSM-KEY-UUID> --dsm-key-id <DSM-KEY-UUID> --output <KEYRING-FILE>
```

5.6 Example Usage: Generate or Import a Key in the Specified Group

When generating or importing a new key using the Sequoia client, the key is always created in the app's default group.

Run the following commands to generate or import a key into a group other than the default:

Retrieve all groups associated with the app:

sq-dsm key list-dsm-groups

Example Output:

UUID                                  Date Created             Name
4080f492-xxxx-xxxx-xxxx-xxxxxxxxxxxx  2024-09-24 09:35:09 UTC  group1
8e86e18e-xxxx-xxxx-xxxx-xxxxxxxxxxxx  2024-08-10 12:06:24 UTC  group2
bea46106-xxxx-xxxx-xxxx-xxxxxxxxxxxx  2023-08-21 09:23:23 UTC  group3
f2a10673-xxxx-xxxx-xxxx-xxxxxxxxxxxx  2023-11-02 08:31:17 UTC  group4
f3645b2b-xxxx-xxxx-xxxx-xxxxxxxxxxxx  2025-01-25 07:53:48 UTC  group5

TOTAL GROUPS: 5

Generate the key in the specified group (--dsm-group-id <GROUP UUID>):

sq-dsm key generate --dsm-key="alice" --cipher-suite="nistp521" --userid="Alice <alice@example.com>" --dsm-group-id f3645b2b-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Import the key into the specified group (--dsm-group-id <GROUP UUID>):

sq-dsm key dsm-import --dsm-key="Alice" --dsm-group-id f3645b2b-xxxx-xxxx-xxxx-xxxxxxxxxxxx < existing_pgp_private_key.asc

5.7 Example Usage: Generate or Import a Key with Custom Metadata

You can provide custom metadata when creating or importing a key in the Sequoia client.

Run the following commands to generate or import a key with custom metadata:

Generate the key with custom metadata (--custom-metadata <key1=value1>):

sq-dsm key generate --dsm-key="alice" --cipher-suite="nistp521" --userid="Alice <alice@example.com>" --custom-metadata testkey1=testvalue1 --custom-metadata testkey2=testvalue2

Here, testkey1=testvalue1 and testkey2=testvalue2 are the custom metadata key-value pairs.

Import the key with custom metadata (--custom-metadata <key1=value1>):
```
sq-dsm key dsm-import --dsm-key="Alice" --custom-metadata testkey1=testvalue1 --custom-metadata testkey2=testvalue2 < existing_pgp_private_key.asc
```
Here, testkey1=testvalue1 and testkey2=testvalue2 are the custom metadata key-value pairs.

The custom metadata key-value pairs will be added to the sq_dsm_user_metadata field in the Custom attributes section of the Security Objects page on the Fortanix DSM user interface (UI).

**Figure 1: Custom metadata details on the Fortanix DSM UI**

NOTE

Run the following command to retrieve the key details:

sq-dsm key info --dsm-key="<DSM KEY NAME>"

Example Output:

<DSM KEY NAME>:
    UUID: 0ce121b1-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    Group ID: f3645b2b-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    Object Type: Rsa
    Created at: 2025-03-21 03:32:02 UTC
    Last used at: NA
    PGP fingerprint: 10BFF49131xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    Custom Metadata: {
    "sq_dsm": "{\"sq_dsm_version\":\"1.8.0\",\"fingerprint\":\"10BFF49131xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\"key_flags\":{\"raw\":[1]},\"certificate\":\"-----BEGIN PGP PUBLIC KEY BLOCK-----\\nComment: 10BF F491 3103 FA5F DD26  1406 6A2B FCE2 5542 3469\\nComment: Alice <alice@openpgp.example>\\n\\nxsBNBGfc3bIBCAC<CERT_DATA>V34h\n+eif0vP+v\\n-----END PGP PUBLIC KEY BLOCK-----\\n\"}",
    "sq_dsm_user_metadata": "{\"testkey1\":\"testvalue1\",\"testkey2\":\"testvalue2\"}",
}

5.8 Example Usage: Rotate a PGP Key

Perform the following steps to rotate a PGP key:

Run the rotate command to rotate a PGP key in the Sequoia client:
```
sq-dsm key rotate --dsm-key-id <DSM-KEY-UUID>
```
Where, DSM-KEY-UUID refers to the UUID of the PGP primary key stored in Fortanix DSM.

Enter y, yes, Y, or YES at Continue with rotation? [y/N]: prompt to continue with the rotation.

NOTE
If you enter any value other than y, yes, Y, or YES, or press any other key, the key rotation operation will be aborted.
Example:
You are about to rotate the PGP key
This operation will:
• Deactivate and unlink old subkeys
• Generate and link new subkeys
• Update the PGP certificate with subkey bindings
This action is irreversible.

Continue with rotation? [y/N]: N

Aborted.

5.9 More Examples

Refer to the test runs on the Fortanix GitHub repository for more example usages, such as exporting secrets and importing them into a local gpg keyring.

6.0 Supported Algorithms

Crypto	Algorithm	Parameters	Use
Symmetric	Preferred Algorithms: AES128 / AES256		Data Encryption
Hash	Preferred Algorithms: SHA256 / SHA512		OpenPGP Data Hashing
Asymmetric Encryption	RSA	Supported Key Sizes: rsa2k[2048] rsa3k[3072] rsa4k[4096] rsa8k[8192]	OpenPGP Session Key Encryption
Key Agreement	ECDH, X25519	Supported Curves: nistp256 nistp384 nistp521 Curve25519	OpenPGP Session Key Agreement
Key Derivation Function (KDF)	Iterated and Salted S2K (String-to-Key)		OpenPGP Session Key Derivation
Signature	ECDSA, EdDSA	Supported Curves: nistp256 nistp384 nistp521 Edwards25519	OpenPGP Data Signing
	ECDSA, EdDSA	Supported Curves: nistp256 nistp384 nistp521 Edwards25519
	RSA	Supported Key Sizes: rsa2k[2048] rsa3k[3072] rsa4k[4096] rsa8k[8192]

7.0 Troubleshooting

ERROR	REASON	RESOLUTION
`environment variable not found`	NA	Set `FORTANIX_API_ENDPOINT` and `FORTANIX_API_KEY`
`Error: could not create primary key`	Authentication failed. Neither the HTTP basic header nor the client certificate was provided.	Ensure that the API key is correct (`env \| grep FORTANIX`). If you are using an http proxy, also make sure that the `http_proxy` is set, and the DSM API endpoint is not in the `no_proxy` list (`env \| grep proxy`).
`Error: could not create primary key`	Connection refused (`os error 111`).	Ensure that the proxy is reachable, and check the proxy logs.
`Error: could not create primary key`	`sobject` already exists.	Use a different Security-object name. For example, use a different value for the `--dsm-key` option.
`Error: dsm client could not create sobject`	`Error: Given RSA key policy not allowed by policy`	Ensure that the RSA Padding policy allows PKCS1v15, as dictated by RFC4880bis.
The user is experiencing random errors during decryption with GnuPG, RNP, and similar tools. For example, `gpg: handle plaintext failed: Unexpected error` or `gpg: packet(13) too large`, and so on.	There may be compatibility issues when using GnuPG, RNP, and similar tools to handle messages encrypted with the Fortanix Sequoia PGP client.	Fortanix DSM suggests opting for one of the following padding methods instead of using the default padding (`pad`) for encryption: `zip` `zlib` `bzip2` `none` For example, you can use the following command for encryption: `sq-dsm encrypt --recipient-cert=alice.asc --signer-key=bob.sec --compression zip msg.txt > to_alice.asc`

8.0 Changelog

For information on the Sequoia PGP client changelog, refer to Sequoia PGP - Changelog.

9.0 References

For more information about PGP, refer to the blog PGP with secrets in the cloud.