Configuration fields¶

Every exported configuration struct in the module, field by field. There is no config file and no environment-variable reading anywhere in this module: each struct is populated by the calling program.

verify.KeyResolverConfig — where trust comes from¶

Passed to verify.BuildKeyResolver together with zero or more armoured embedded keys.

What BuildKeyResolver returns for each combination¶

KeySource alone does not determine the result. What you get also depends on whether you supplied embedded keys and an email:

The two bold rows are the trap. "both" is a request, not a guarantee: with only one anchor configured it degrades to that single anchor silently, and the resulting resolver behaves exactly like a single-source one. Setting RequireExternalCrosscheck: true does not rescue it, because that flag is only read when a CompositeResolver is actually constructed.

To confirm the cross-check is really running, check the resolver's name before you rely on it. A composite reports composite[embedded,wkd:openpgpkey.<domain>]; a degraded one reports just embedded or wkd:openpgpkey.<domain>.

resolver, err := verify.BuildKeyResolver(cfg, embeddedKey)
if err != nil {
    return err
}
if !strings.HasPrefix(resolver.Name(), "composite[") {
    return fmt.Errorf("expected a cross-checked resolver, got %q", resolver.Name())
}

Embedded keys are parsed and strength-checked inside BuildKeyResolver, so a weak or malformed embedded key surfaces there as an error rather than later.

verify.WKDResolverConfig — a single WKD anchor¶

Passed to verify.NewWKDResolver when you compose resolvers by hand.

Email must contain an @ that is neither the first nor the last character. The domain is lower-cased and then validated: it must be non-empty, contain no / or \, contain no .., have no leading or trailing dot, and consist only of letters, digits, - and .. Anything else is rejected before a request is made, so a hostile address cannot reshape the request target.

The local part is not lower-cased for the ?l= query parameter — it is passed through url.QueryEscape as given — but it is lower-cased before hashing into the hu/ filename, as the WKD specification requires.

verify.CompositeResolver — cross-checking several anchors¶

A struct with exported fields rather than a constructor, so build it directly.

Fingerprint agreement between the children that succeeded is checked regardless of RequireAll, and a disagreement always aborts with ErrKeyResolverMismatch. Agreement is exact and total — the fingerprint sets must be identical. There is no quorum or m-of-n mode.

With one successful child there is nothing to compare, so no cross-check runs. That is how a fail-open composite behaves during a WKD outage.

openpgpkey.Options — writing a WKD tree¶

Passed to openpgpkey.WriteWKDTree.

The domain argument is validated with the same rules as WKDResolverConfig.Email's domain, which is what keeps a pathological value from escaping outDir/.well-known/openpgpkey.

openpgpkey.Entry — one address and its keys¶

WriteWKDTree needs at least one Entry. Several entries sharing an Email merge into one published file, so passing the same address twice is equivalent to passing one entry holding all the keys.

minisign.Options — comments and timestamp¶

Passed to minisign.Sign and minisign.SignDigest.

Both comments are rejected if they contain a carriage return or newline (ErrInvalidComment) or exceed their length limit (ErrCommentTooLong). The limits are in Limits, defaults and tunables.

Function arguments worth spelling out¶

A few arguments are not obvious from their names.

openpgpkey.ArmoredPublicKey(signer, name, email, creationTime) bakes creationTime into both the key packet and its self-signature. Two calls with the same signer and a different creationTime produce different fingerprints, so keep it stable: a rotation is a new key, not a new timestamp on the old one.

openpgpkey.DetachSign(signer, publicKey, data, sigCreationTime) takes the armoured public key you previously minted, and rebuilds the OpenPGP entity from it so the fingerprint in the signature matches what verifiers expect. The signer's RSA public half is compared against the one inside publicKey, and a mismatch is refused. sigCreationTime is the signature's own creation-time subpacket, independent of the key's; it is truncated to whole seconds because that is all an OpenPGP v4 signature packet stores.

minisign.SignDigest(signer, digest, opts) requires digest to be exactly BLAKE2b-512 output (64 bytes). Any other length is refused rather than signed.

Related¶

• Errors — the sentinel each failure above maps to.
• Configure trust — applying these fields.
• The trust model — why the cross-check exists.