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

PROBLEM RESOLUTION
environment variable not found Set FORTANIX_API_ENDPOINT and FORTANIX_API_KEY
Error: could not create primary key

Caused by:
Authentication failed. Neither HTTP Basic header nor client certificate was provided
Make sure 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

Caused by:
Connection refused (os error 111)
Make sure that the proxy is reachable, and check the proxy logs.
Error: could not create primary key

Caused by:
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

Caused by:

Error: Given RSA key policy not allowed by policy

Make sure that the RSA Padding policy allows PKCS1v15, as dictated by RFC4880bis.

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.

 

Comments

Please sign in to leave a comment.

Was this article helpful?
0 out of 0 found this helpful