Clients: Sequoia PGP

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

Installation

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

Configuration

Set the following environment variables:

• FORTANIX_API_ENDPOINT, your DSM endpoint.

• FORTANIX_API_KEY, your app's 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.

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.

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 <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"
   

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.
   

Example Usage: Importing 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

Example Usage: Generate Key Using a Different Key Structure

By default, the command to generate keys as explained in Section - 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)

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.

Troubleshooting

Changelog

Version 1.3.0

• Key creation can now be controlled using the additional flag --key-flags.

Version 1.2.0

• Refined structure on key generation: Primary: Certification, subkey1: Signing, Subkey2: Encryption (transport and rest)
• Created the following new commands to fetch key details:
  • sq-dsm key list-dsm-keys
  • sq-dsm key info --dsm-key <DSM-KEY-NAME>

Version 1.0.3

• Unlock PKCS12 identity with--pkcs12-passphrase
• Unlock PKCS12 identity withFORTANIX_PKCS12_PASSPHRASE

Version 1.0.1

• Reflect PGP key deactivation date in Fortanix DSM objects.

Version 1.0

• Stable release.

Version 0.3.0-beta

• Support key import (sq-dsm key dsm-import).
• Support auth credentials as options (--api-key, --client-cert, --app-uuid).

Version 0.1.0-beta

• Certificate-based authentication.
• Support custom expiration timestamps (--expires, --expires-in).
• Protect exported PGP keys with a passphrase.
• Allow RSA2048.
• Fix RSA key export issues.

References

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