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 overridesFORTANIX_PKCS12_ID
.FORTANIX_PKCS12_ID
, a PKCS12 identity file, for certificate-based authentication. Given a PKCS8 pairprivate.key
andpublic.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 withFORTANIX_PKCS12_ID
).(Optional)
http_proxy
and/orno_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.
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"
Recover Alice's Transferable Public Key (TPK).
sq-dsm key extract-cert --dsm-key="alice" > alice.asc
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.
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.
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
andtestkey2=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
andtestkey2=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 | 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 |
---|---|---|
| NA | Set |
| Authentication failed. Neither the HTTP basic header nor the client certificate was provided. | Ensure that the API key is correct ( |
| Connection refused ( | Ensure that the proxy is reachable, and check the proxy logs. |
|
| Use a different Security-object name, for example, use a different value for the |
|
| 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. | 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 (
For example, you can use the following command for encryption:
|
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.