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

Download

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

Installation

For Linux, install using the package managers:

dpkg -i sq-dsm_0.1_amd64.deb
rpm -i sq-dsm-0.1-0.x86_64.rpm

For windows, copy the executable to a system path.

Uninstallation

For Linux, uninstall using the package managers:

dpkg -r sq-dsm_0.1_amd64.deb
rpm -e sq-dsm-0.1-0.x86_64.rpm

For windows, delete the executable.

Configuration

Set the following environment variables:

  • FORTANIX_API_ENDPOINT, your DSM endpoint.

  • FORTANIX_API_KEY, an API key

  • (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

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 help $ 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.

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.

 

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