Clients: Sequoia PGP

Last Updated: March 16, 2023 07:49

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.

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"

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.

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

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