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 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, thensq-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
.
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. |
|
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 with
FORTANIX_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.