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 ¶
- Decision 0044: docs/research/decisions/0044-modular-monolith-migration.md, "Package placement and names", "Names the migration introduces" and, under Rationale, "keymaterial in the platform".
- Target layout: docs/research/architecture-options/5-modular-monolith.md, line 1007, which maps the package to access/core/keymaterial; decision 0044 records the deviation.
- Decision 0017: docs/research/decisions/0017-sealed-columns-and-master-key.md.
- Research 05: docs/research/05-platform-identity-and-security-apis.md, "Legacy Artifactory security API" (the key pair and certificate rows).
- https://docs.jfrog.com/administration/reference/createkeypair and https://docs.jfrog.com/administration/reference/verifykeypair
- https://docs.jfrog.com/administration/docs/security-keys-management (the four signing key types) and https://docs.jfrog.com/artifactory/docs/npm-repositories, "Enable ECDSA Signing in Local Repositories" (decision 0034, "Signatures").
- Plan: docs/implementation/plan.md#p9d-modular-monolith-migration, epic ACC (https://github.com/weaveplatform/artifactweave/issues/940), and #p4-identity-and-authorization.
- https://github.com/weaveplatform/artifactweave/issues/964
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
- Variables
- func CheckPair(pairType, privateKey, publicKey, passphrase string) error
- func ECDSAPrivateKey(privateKey, passphrase string) (*ecdsa.PrivateKey, error)
- func ECDSAPublicKey(publicKey string) (*ecdsa.PublicKey, error)
- func Ed25519PrivateKey(privateKey, passphrase string) (ed25519.PrivateKey, error)
- func Ed25519PublicKey(publicKey string) (ed25519.PublicKey, error)
- func RSAPrivateKey(privateKey, passphrase string) (*rsa.PrivateKey, error)
- type Bundle
Constants ¶
const ( RSA = "RSA" GPG = "GPG" )
Key pair types the security API accepts.
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).
const Ed25519 = "Ed25519"
Ed25519 is the signing key type used by Nix binary caches.
Variables ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.