Skip to content

encryption

Recover OpenPGP session keys, and assemble OpenPGP certificates, when the private keys live somewhere this process cannot reach — a KMS, an HSM, a smartcard.

Two packages

gitlab.com/phpboyscout/go/encryption              decryption
gitlab.com/phpboyscout/go/encryption/certificate  assembly and reading

A consumer that only opens messages imports the first and sees exactly that vocabulary — SessionKey, ParsePacket, ParsePKESK, KDFParams. Certificate work is a separate import, because most callers never do it.

Both are standard-library only, and a test asserts it for each of them rather than trusting anyone to remember.

Three modules:

  • go/encryption — the format work. The RFC 6637 key derivation, the RFC 3394 key unwrap, packet framing, certificate assembly and fingerprints. Standard library only.
  • go/encryption-aws-kms — the AWS KMS provider. Two operations, DeriveSharedSecret and Sign, and nothing else.
  • sigillum — the command-line tool: message framing, body decryption and the decrypt and certificate commands.

Should you be here at all?

There is a maintained Go OpenPGP library — go-crypto — and for most jobs it is the right answer. This package exists for one case: the private key is somewhere your process cannot read it.

If you can load the key from a file, use go-crypto. If it lives in a KMS, an HSM or a smartcard, go-crypto currently has no seam for ECDH decryption, and that is the gap this fills.

The full argument, including the part of it that turned out to be wrong, is in why this exists when go-crypto already does OpenPGP. The short decision table is in when to use this.

Why they are separate

Only two operations in this whole path need a private key. Everything else is arithmetic over public data.

Keeping the arithmetic in a module with no cloud SDK means it can be tested against fixed vectors with no credentials, and a consumer who only wants to read a message does not inherit an AWS dependency to do it.

Where to start

  • Tutorials — decrypt your first message, start to finish.
  • How-to guides — decrypt with KMS, assemble a certificate, plug in your own key service.
  • Explanation — why this exists at all, why ECDH rather than RSA, and why assembly and decryption cannot be separated.
  • Reference — the IAM actions the AWS KMS provider needs, and the environment the integration tests read.
  • Go API — lives on pkg.go.dev, which is generated from the source and cannot drift from it.

What this is not

It does not decrypt message bodies. It recovers the session key and stops; opening the encrypted-data packet with that key is a full OpenPGP concern, and a mature implementation already does it well. sigillum wires the two together if you want a working command.

It does not implement X25519 or X448 (public-key algorithms 25 and 26). Those use a different derivation, and this package is for algorithm 18 over the NIST curves a KMS can hold.