--- title: "Sequoia-PGP" slug: "clients-sequoia-pgp" updated: 2026-04-10T06:59:18Z published: 2026-04-10T07:01:36Z --- > ## Documentation Index > Fetch the complete documentation index at: https://support.fortanix.com/llms.txt > Use this file to discover all available pages before exploring further. # Sequoia-PGP ## 1.0 Introduction **Fortanix-Data-Security-Manager****(DSM)**integrates with****[**Sequoia-PGP**](https://sequoia-pgp.org/)**,**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***[*Compatibility Matrix*](/v1/docs/clients-compatibility-matrix)*.* ## 3.0 Installation Download and install the Fortanix Sequoia PGP library for all platforms from [*here*](https://fortanix.zendesk.com/hc/en-us/articles/4408325101460-Sequoia-PGP). ## 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.crt`The public certificate needs to be configured in Fortanix DSM for your app, and the PKCS12 file can be generated using the following command: ```bash 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: ```bash export FORTANIX_CA_FILE="" ``` ## 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: ```bash 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: 1. Run the following commands to generate a Fortanix DSM key for Alice, and local keys for Bob and Charlie: ```bash sq-dsm key generate --dsm-key="alice" --cipher-suite="nistp521" --userid="Alice " sq-dsm key generate --cipher-suite="rsa3k" --userid="Bob " --export="bob.sec" sq-dsm key generate --userid="Charlie " --export="charlie.asc" ``` 2. Run the following command to recover Alice's Transferable Public Key (TPK): ```bash sq-dsm key extract-cert --dsm-key="alice" > alice.asc ``` 3. Run the following commands to create a file, sign it with Alice's key, and verify it: ```bash 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: ```bash Good signature from B4C961DE2204FD02 Hello, World! 1 good signature. ``` 4. Run the following command to encrypt a file for Alice, signed by Bob, and decrypt it: ```bash 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: ```bash Encrypted using AES with 256-bit key Compressed using ZIP Good signature from DC4358B3EA20F2C6 Hello, World! 1 good signature. ``` 5. Run the following commands to encrypt a file to Charlie, signed by both Alice and Bob, and decrypt it: ```bash 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: ```bash 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: ```bash 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*](/v1/docs/clients-sequoia-pgp#51-example-usage-signed-encryption-of-a-file) generates keys using the following structure: ```bash 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: ```bash 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: ```bash sq-dsm key dsm-import --dsm-key="Alicepubkey" --input alice_public_key.asc ``` Run the following command to retrieve the TPK from Fortanix DSM: ```bash 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: ```bash sq-dsm keyring dsm-import --dsm-exportable --keyring-name "" --input --dsm-group-id ``` 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: ```bash sq-dsm keyring extract --dsm-key-id --dsm-key-id --output ``` - Run the following command to retrieve a private keyring (containing Transferable Secret Keys (TSKs)) from Fortanix DSM: ```bash sq-dsm keyring extract-secret --dsm-key-id --dsm-key-id --output ``` ### 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: ```bash sq-dsm key list-dsm-groups ``` Example Output: ```bash 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>`): ```bash sq-dsm key generate --dsm-key="alice" --cipher-suite="nistp521" --userid="Alice " --dsm-group-id f3645b2b-xxxx-xxxx-xxxx-xxxxxxxxxxxx ``` - Import the key into the specified group (`--dsm-group-id <GROUP UUID>`): ```bash 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>`): ```bash sq-dsm key generate --dsm-key="alice" --cipher-suite="nistp521" --userid="Alice " --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>`): ```bash 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). ![](https://cdn.us.document360.io/c3bd85d2-4ad8-4d85-9f60-f1c168a3aad9/Images/Documentation/DSM_SQ DSM Client(2)(1).png) **Figure 1: Custom metadata details on the Fortanix DSM UI** > [!NOTE] > NOTE > > Run the following command to retrieve the key details: > > ```bash > sq-dsm key info --dsm-key="" > ``` > > Example Output: > > ```bash > : >    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 \\n\\nxsBNBGfc3bIBCACV34h\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: 1. Run the `rotate` command to rotate a PGP key in the Sequoia client: ```bash sq-dsm key rotate --dsm-key-id ``` Where, `DSM-KEY-UUID` refers to the UUID of the **PGP primary key** stored in Fortanix DSM. 2. Enter `y`, `yes`, `Y`, or `YES` at **Continue with rotation? [y/N]:** prompt to continue with the rotation. > [!NOTE] > 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: > > ```bash > 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*](https://github.com/fortanix/sq-dsm/tree/main/sq/tests/dsm)*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: ```bash 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*](https://fortanix.zendesk.com/hc/en-us/articles/32292952263956-Sequoia-PGP-Changelog)*.* ## 9.0 References *For more information about PGP, refer to the blog*[*PGP with secrets in the cloud*](https://fortanix.com/blog/2022/01/pgp-with-secrets-in-the-cloud/)*.* Fortanix Data Security Manager (DSM) is the world’s first cloud service secured with Intel® SGX. With Fortanix DSM, you can securely generate, store, and use cryptographic keys and certificates, as well as other secrets such as passwords, API keys, tokens, or any blob of data. Your business-critical applications and containers can integrate with Fortanix DSM using legacy cryptographic interfaces (PKCS#11, CNG, and JCE) or using the native Fortanix DSM RESTful interface. A security object is any datum stored in DSM (for example a key, a certificate, a password, or other security objects). Each security object is assigned to exactly one group. users and applications assigned to the group have permission to see the security object and to perform operations on it. ## Related - [SDKs for REST API](/clients-sdks-for-rest-api.md) - [Fortanix DSM SaaS Overview](/fortanix-dsm-saas-overview.md) - [Fortanix DSM - Quickstart](/fortanix-data-security-manager-quickstart.md) - [Migrating Private Key from Microsoft AD CS Certificate Authority to Fortanix DSM](/migrating-private-key-from-microsoft-ad-cs-certificate-authority-to-fortanix-data-security-manager.md)