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

2.0 Operating System (OS) Compatibility Matrix

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

3.0 Installation

The Fortanix sq-dsm library for all platforms can be downloaded and installed from here.

4.0 Configuration

Set the following environment variables:

  • FORTANIX_API_ENDPOINT, your DSM endpoint.

  • FORTANIX_API_KEY, your 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.crt, the public certificate needs to be configured in Fortanix DSM for your app, and the PKCS12 file can be generated with 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 DSM app, for certificate-based authentication (for example, this environment variable is used together with FORTANIX_PKCS12_ID).

  • (Optional) http_proxy and/or no_proxy.

5.0 Usage and Commands

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

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.

  1. 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 <[email protected]>"
    sq-dsm key generate --cipher-suite="rsa3k" --userid="Bob <[email protected]>" --export="bob.sec"
    sq-dsm key generate --userid="Charlie <[email protected]>" --export="charlie.asc"
    
  2. Recover Alice's Transferable Public Key (TPK).

    sq-dsm key extract-cert --dsm-key="alice" > alice.asc
    
  3. 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
    
    Good signature from B4C961DE2204FD02
    Hello, World!
    1 good signature.
    
  4. Encrypt a file to 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
    
    Encrypted using AES with 256-bit key
    Compressed using ZIP
    Good signature from DC4358B3EA20F2C6
    Hello, World!
    1 good signature.
    
  5. 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
    
    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, you can import it into Fortanix DSM with the dsm-import sub-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: Upload or Retrieve Transferable Public Keys to Fortanix DSM

Given a valid Transferable Public Key (TPK), you can import it into Fortanix DSM using the dsm-import sub-command:

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

To retrieve the TPK from Fortanix DSM, run the extract-cert sub-command:

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

5.5 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 <[email protected]>" --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.6 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 <[email protected]>" --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 object 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 <[email protected]>\\n\\nxsBNBGfc3bIBCAC<CERT_DATA>V34h\n+eif0vP+v\\n-----END PGP PUBLIC KEY BLOCK-----\\n\"}",
    "sq_dsm_user_metadata": "{\"testkey1\":\"testvalue1\",\"testkey2\":\"testvalue2\"}",
}

5.7 More Examples

See 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

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 details on Sequoia PGP client changelog, refer to Sequoia PGP - Changelog.

9.0 References

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