keymaterial

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package keymaterial checks key material and opens it for signing: that the private and public halves of an RSA, GPG, Ed25519 or ECDSA key pair belong together, that a client certificate bundle carries its own private key, and how a stored RSA, Ed25519 or ECDSA key is read back to sign or verify format metadata.

Role

platform layer: key-material checks that no module owns. Access's key pair and certificate API checks what it stores with them, and the Alpine, Hex, Nix and npm formats open their signing keys with them. A package inside access would make those formats import access internals, so it sits in the platform. It imports the standard library and the ProtonMail go-crypto OpenPGP package, and no module.

Inputs

  • PEM private keys (PKCS#1, PKCS#8 or SEC 1), optionally encrypted the legacy OpenSSL way, with the passphrase that unlocks them.
  • PEM public keys (PKIX or PKCS#1) and certificates.
  • ASCII-armored OpenPGP keys for GPG key pairs, and for ECDSA key pairs exported from gpg, as 7.x's npm documentation has users make them.
  • A key pair type, as the security API names it: RSA, GPG, Ed25519 or ECDSA.

Outputs

  • CheckPair: nil when the two halves belong to one key of the type.
  • RSAPrivateKey, Ed25519PrivateKey, Ed25519PublicKey, ECDSAPrivateKey and ECDSAPublicKey: the parsed keys a format signs or verifies its metadata with. An ECDSA key is on P-256, P-384 or P-521.
  • ParseBundle: a Bundle with the PEM a certificate upload stores and the subject, issuer, validity and fingerprint of its leaf certificate.
  • ErrInvalid, which every refusal wraps.

Invariants

  • Error texts are observable: the key pair and certificate API returns them in its 400 responses, so they stay byte-identical.
  • The package keeps no state and writes no logs, so it never stores or logs the key material it is given; the stores seal that material at rest (decision 0017).
  • A wrong passphrase on a legacy encrypted PEM key is reported as such even when the decryption happens to pass the padding check, because that encryption has no integrity check.

References

Status

Implemented P4 (key pair and certificate checks) and P9c (the RSA and Ed25519 signing keys of the Alpine, Hex and Nix formats). Moved here in P9d. ECDSA pairs for npm package signatures (#362).

Testing

  • TestUnitCheckRSA: RSA pairs from PKCS#1, PKCS#8, legacy encrypted and certificate halves, and each refusal, from mismatched halves to an unknown pair type.
  • TestUnitCheckRSAWrongPassphraseWithValidPadding: a wrong passphrase that passes the padding check is still reported as a wrong passphrase.
  • TestUnitCheckGPG: armored OpenPGP pairs, with and without a passphrase, and their refusals.
  • TestUnitEd25519KeyMaterial: Ed25519 pairs, the two key parsers and the pairs that are refused.
  • TestUnitECDSAKeyMaterial: ECDSA pairs as PEM and as gpg's armored export, with and without a passphrase, and the pairs that are refused, other curves among them.
  • TestUnitParseBundle: a certificate with its chain and key, the subject, issuer, validity and fingerprint read from the leaf, and the bundles that are refused.

The tests generate their keys and never commit one, since a private key in the repository would also trip secret scanning.

Index

Constants

View Source
const (
	RSA = "RSA"
	GPG = "GPG"
)

Key pair types the security API accepts.

View Source
const ECDSA = "ECDSA"

ECDSA is the signing key type of npm package signatures (decision 0034, "Signatures"). 7.x's Keys Management names it "ECDSA Keys"; the security API's documentation lists only RSA and GPG, so the REST spelling is inferred [I] (#216).

View Source
const Ed25519 = "Ed25519"

Ed25519 is the signing key type used by Nix binary caches.

Variables

View Source
var ErrInvalid = errors.New("keymaterial: invalid key material")

ErrInvalid reports key material that does not parse, does not match, or cannot be unlocked. Its message is safe to show the caller.

Functions

func CheckPair

func CheckPair(pairType, privateKey, publicKey, passphrase string) error

CheckPair verifies that privateKey and publicKey are the two halves of one key of pairType, unlocking privateKey with passphrase when it is encrypted.

func ECDSAPrivateKey

func ECDSAPrivateKey(privateKey, passphrase string) (*ecdsa.PrivateKey, error)

ECDSAPrivateKey opens the private half of an ECDSA key pair, so that a format can sign with it: a PEM key (PKCS#8 or SEC 1, optionally encrypted the legacy OpenSSL way) or an ASCII-armored OpenPGP secret key whose primary key is ECDSA, unlocked with passphrase when it is encrypted. The error wraps ErrInvalid when the key does not parse, the passphrase does not unlock it, it is another kind of key, or its curve is not P-256, P-384 or P-521.

func ECDSAPublicKey

func ECDSAPublicKey(publicKey string) (*ecdsa.PublicKey, error)

ECDSAPublicKey reads the public half of an ECDSA key pair: a PKIX "PUBLIC KEY" PEM, a certificate, or an ASCII-armored OpenPGP public key whose primary key is ECDSA. The error wraps ErrInvalid as ECDSAPrivateKey's does.

func Ed25519PrivateKey

func Ed25519PrivateKey(privateKey, passphrase string) (ed25519.PrivateKey, error)

Ed25519PrivateKey opens the PKCS#8 PEM private key of an Ed25519 key pair, unlocking it with passphrase when it is encrypted the legacy OpenSSL way, so that a format can sign with it. The error wraps ErrInvalid when the key does not parse, the passphrase does not unlock it, or it is another kind of key.

func Ed25519PublicKey

func Ed25519PublicKey(publicKey string) (ed25519.PublicKey, error)

Ed25519PublicKey reads the PKIX "PUBLIC KEY" PEM of an Ed25519 key pair, so that a format can verify an upstream signature with it. The error wraps ErrInvalid when the PEM is missing or of another block type, does not parse, or holds another kind of key.

func RSAPrivateKey

func RSAPrivateKey(privateKey, passphrase string) (*rsa.PrivateKey, error)

RSAPrivateKey opens a validated RSA key pair for format metadata signing. It accepts the same PEM and legacy PEM passphrase forms as CheckPair.

Types

type Bundle

type Bundle struct {
	// Certificates is the PEM of every certificate in the bundle, the leaf
	// first; PrivateKey the PEM of its key.
	Certificates string
	PrivateKey   string
	// IssuedTo and IssuedBy are the leaf's subject and issuer common names,
	// each falling back to the full distinguished name when it has none.
	IssuedTo string
	IssuedBy string
	// IssuedOn and ValidUntil bound the leaf's validity, in UTC.
	IssuedOn   time.Time
	ValidUntil time.Time
	// Fingerprint is the leaf's SHA-256 in colon-separated upper-case hex,
	// as Java's keytool prints it.
	Fingerprint string
}

Bundle is a parsed client certificate bundle.

func ParseBundle

func ParseBundle(data []byte) (Bundle, error)

ParseBundle reads a PEM bundle of a certificate (optionally followed by its chain) and the certificate's private key, and checks the key belongs to the first certificate.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL