100 KiB
Code map
Navigation index for agents and new contributors: concept → file → entry points → invariants. Start here instead of grepping the tree. If you had to grep for something that belongs in this map, add the row in the same change (see AGENTS.md).
- High level purpose and samples: README.md
- Known defects and verified fixes, with IDs referenced from code comments: FINDINGS.md
- Larger planned work: ROADMAP.md
- Generated API reference (
make docs, gomarkdoc, do not edit): api
Module layout
github.com/effective-security/xpki, Go 1.27. Library packages plus two CLIs.
| Path | Purpose |
|---|---|
cryptoprov/ |
Provider abstraction, loader registry, token config, key URIs, PEM |
crypto11/ |
PKCS#11 provider (manufacturer SoftHSM), cgo, fork of Thales crypto11 |
cryptoprov/awskmscrypto/ |
AWS KMS provider (AWSKMS) |
cryptoprov/gcpkmscrypto/ |
GCP KMS provider (GCPKMS) |
cryptoprov/inmemcrypto/ |
In-memory provider (inmem), exportable keys |
cryptoprov/testprov/ |
Test provider, non-exportable keys, not self-registered |
csr/ |
CSR types, key requests, CSR create/parse, SAN and CRL-DP encoding |
authority/ |
CA: config, profiles, issuers, Sign, OCSP, root bootstrap |
certutil/ |
PEM/cert/key helpers, chain bundler, hashes, OCSP request |
jwt/ |
JWT sign/verify, claims, JWKS key sets |
jwt/dpop/ |
DPoP proofs (RFC 9449) |
jwt/accesstoken/ |
Opaque encrypted pat. tokens over jwt + dataprotection |
jwt/oauth2client/ |
OAuth2/OIDC client registry and token-request builder |
dataprotection/ |
AES-GCM Provider with HKDF key derivation |
armor/, oid/, x/print/, metricskey/, internal/version/ |
Helpers (see below) |
internal/testenv/ |
Test-only gate for external fixtures (XPKI_INTEGRATION) |
testca/ |
Test-only CA and certificate generator |
cmd/hsm-tool/, cmd/xpki-tool/ |
CLIs (kong) |
Dependency direction (non-test): cryptoprov ← crypto11, awskmscrypto,
gcpkmscrypto, inmemcrypto, testprov, csr, authority, jwt, cmd/*.
certutil is a leaf used by almost everything. csr ← authority, jwt,
cmd/hsm-tool. jwt ← dpop, accesstoken. oid ← authority, csr,
x/print. metricskey ← authority, KMS providers. armor has no in-repo
consumers. Nothing in the library imports cmd/.
Concept index
| Concept | File(s) | Entry points |
|---|---|---|
| Provider interfaces | cryptoprov/provider.go |
Provider, KeyGenerator, KeyManager, KeyInfo, TokenInfo |
| Provider registry / loading | cryptoprov/loader.go |
Register, LoadProvider, Load, Registered |
| Multi-provider registry | cryptoprov/provider.go, crypto_concurrency_test.go |
Crypto, New, Add, ByManufacturer, Default, ErrNilProvider, ErrDuplicateProvider |
Token config file (JSON/YAML, file: PIN) |
cryptoprov/config.go, crypto11/config.go |
LoadTokenConfig, TokenConfig |
| PKCS#11 key URI | cryptoprov/uri.go |
ParseTokenURI, ParsePrivateKeyURI, PrivateKeyURI |
| Load key from PEM or URI | cryptoprov/utils.go, cryptoprov/signer.go |
Crypto.LoadPrivateKey, NewSignerFromPEM, NewSignerFromFromFile, LoadTLSKeyPair |
| AES-GCM helpers | cryptoprov/gcm.go |
GcmEncrypt, GcmDecrypt |
| PKCS#11 init / token select / login | crypto11/config.go |
Init, selectToken, ConfigureFromFile, LoadTokenConfig, WithMaxSessions, DefaultMaxSessions |
| PKCS#11 module sharing / finalize | crypto11/module.go, crypto11/crypto11.go |
openModule, module.release, PKCS11Lib.Close |
| PKCS#11 session pool | crypto11/sessions.go |
withSession, sessionPool, sessionUnusable, NewSession |
| PKCS#11 key generation / lookup | crypto11/keys.go, rsa.go, ecdsa.go |
GenerateRSAKey, GenerateECDSAKey, FindKeyPair*, GetKey, ExportKey |
| PKCS#11 signing / decryption | crypto11/rsa.go, crypto11/ecdsa.go |
PKCS11PrivateKeyRSA.Sign/Decrypt, PKCS11PrivateKeyECDSA.Sign |
| PKCS#11 token / key enumeration | crypto11/provider.go, crypto11/util.go |
EnumTokens, EnumKeys, KeyInfo, DestroyKeyPairOnSlot |
| AWS KMS | cryptoprov/awskmscrypto/awskmsprov.go, signer.go |
Init, KmsLoader, KmsClientFactory, KmsClient, NewSigner, Signer.SigningAlgorithms, Provider.EnumKeys |
| GCP KMS | cryptoprov/gcpkmscrypto/gcpkmsprov.go, signer.go |
Init, KmsLoader, KmsClientFactory (takes the endpoint), KmsClient, KeyLabelAndID, NewSigner, Signer.Algorithm, Signer.SignatureAlgorithm, Crc32c, Provider.Close, ErrClosed |
| In-memory keys | cryptoprov/inmemcrypto/provider.go, concurrency_test.go |
NewProvider, Loader, ProviderName, Provider.GetKey, GenerateRSAKey, GenerateECDSAKey, ExportKey |
| Test-provider key registry | cryptoprov/testprov/provider.go, concurrency_test.go |
Init, Loader, Provider.GetKey, GenerateRSAKey, GenerateECDSAKey, ExportKey |
| CSR request types | csr/csr.go |
CertificateRequest, SignRequest, X509Subject, X509Name, X509Extension, AllowedFields |
| CSR create / sign / parse | csr/csrprov.go, csr/csr.go |
NewProvider, GenerateKeyAndRequest, CreateRequestAndExportKey, SignRequest, Parse, ParsePEM |
| Key request (algo/size/purpose) | csr/keyreq.go |
KeyRequest, NewKeyRequest, KeyPurpose, SigAlgo |
| Subject merge, SAN classification | csr/csr.go |
PopulateName, SetSAN, FindAttr |
| CRL distribution point extension | csr/csr.go |
EncodeCDP, EncodeCDPFull, DecodeCDP, DecodeCDPFull, GeneralName |
| JSON/YAML OID and Duration | csr/types.go |
OID, Duration, ParseObjectIdentifier |
| CA config and profiles | authority/config.go |
Config, IssuerConfig, AIAConfig, CertProfile, LoadConfig, Validate, Usages |
| CA issuer registry | authority/authority.go |
NewAuthority, GetIssuerBy{Label,Profile,KeyID,KeyHash,NameHash} |
| Issuer construction / signing | authority/issuer.go |
NewIssuer, NewIssuerWithBundles, CreateIssuer, Issuer.Sign, SignProof, VerifyProof |
| OCSP signing, delegated responder | authority/ocsp.go |
SignOCSP, OCSPSignRequest, CreateDelegatedOCSPSigner, OCSPReasonStringToCode |
| OCSP responder renewal / locking | authority/ocsp.go (delegatedResponder), authority/issuer.go (Issuer) |
caResponder, delegated, renewal (ocspRenewal), renewLock, renewWaitHook, validateDelegatedOCSPProfile, signWithProfile |
| Certificate policies, SKI | authority/extensions.go |
addPolicies, CTPoisonOID, SCTListOID |
| Root bootstrap / cert files | authority/root.go, authority/util.go |
NewRoot, Issuer.GenCert |
| PEM parse / encode | certutil/pem.go |
ParseFromPEM, ParseChainFromPEM, Load*FromPEM, EncodeToPEM*, ParsePrivateKeyPEM*, EncodePrivateKeyToPEM |
| Chain bundling / verification | certutil/bundler.go, certutil/bundle.go |
NewBundler*, LoadBundler, Bundler.Bundle/BundleContext, VerifyBundleFromPEM, LoadAndVerifyBundleFromPEM, Bundle, BundleStatus |
| Hashes, thumbprints, IDs | certutil/hash.go, certutil/cert_id.go |
Digest, SHA1*, SHA256*, NewHash, GetThumbprintStr, GetSubjectID, GetIssuerID |
| Key info (type, size, hash, JWK) | certutil/keyinfo.go |
NewKeyInfo, KeyInfo |
| OCSP request, extensions | certutil/ocsp.go, certutil/extensions.go |
CreateOCSPRequest, FindExtension, IsOCSPSigner, HasOCSPNoCheck |
| Randomness | certutil/random.go |
Random, RandomString, RandReader |
| JWT provider (sign + verify) | jwt/jwt.go |
ProviderConfig, LoadProvider, NewProvider, NewProviderFromCryptoSigner, NewProviderWithSymmetricKey, WithHeaders |
| JWT signing internals | jwt/sign.go |
NewSignerInfo, VerifySignature |
| JWT parsing (third-party tokens) | jwt/parser.go |
ParserConfig, LoadParserConfig, NewParser, TokenParser, Keyfunc |
| Claims | jwt/claims.go |
Claims, MapClaims, NumericDate, Audience, CreateClaims, SetClaimsExpiration, TimeNowFn |
| JWKS key sets | jwt/jwks.go |
KeySet, AlgorithmKeySet, StaticKeySet, RemoteKeySet, NewRemoteKeySet, WithHTTPClient, WithRefreshCooldown |
| DPoP proof create / verify | jwt/dpop/signer.go, jwt/dpop/verify.go |
NewSigner, ForRequest, VerifyRequestClaims, VerifyClaims, VerifyClaimsContext, AccessTokenHash, GetTokenInfo |
DPoP replay cache (jti) |
jwt/dpop/replay.go |
ReplayCache, NewMemoryReplayCache, ErrReplay, ErrReplayCacheFull |
DPoP htu request URI / normalization |
jwt/dpop/htu.go |
VerifyConfig.ExternalURL, requestURI, normalizeHTU |
| DPoP keys | jwt/dpop/keys.go |
GenerateKey, LoadKey, SaveKey, Thumbprint |
| Opaque access tokens | jwt/accesstoken/accesstoken.go |
New, Provider, WithTokenExpiry, WithAllowNoExpiry, TokenPrefix |
| OAuth2 client registry | jwt/oauth2client/*.go |
LoadProvider, NewProvider, RegisterClient, ClientFor*, Client.CreateTokenRequest[WithContext] |
| Data protection | dataprotection/dp.go, symmetric.go |
Provider, NewSymmetric, ProtectObject, UnprotectObject |
| Human-readable printing | x/print/certutil.go |
Certificate(s), CertificateRequest, CertificateList, OCSPResponse, CertAndKey, JSON |
| OID / usage names | oid/oidinfo.go |
KeyUsage*, ExtKeyUsage*, DisplayName, KeyUsages, ExtKeyUsages, Strings |
| ASCII armor decoding | armor/armor.go |
Decode, Block |
| Metrics descriptors | metricskey/metricskey.go |
PerfCryptoOperation, PerfCAOperation, PerfCASignRequest, Metrics |
| Build version | internal/version/*.go |
Current, Info, PopulateFromBuild |
| Integration fixture gating (tests) | internal/testenv/testenv.go |
RequireTCP, RequireFile, IntegrationRequired, IntegrationEnv, Required |
| SoftHSM fixture setup | scripts/config-softhsm.sh, scripts/config-softhsm_test.sh |
make hsmconfig, make test-scripts, setup --help |
| Test CA fixtures | testca/entity.go, configuration.go, mkcert.go, testca.go, utils.go |
NewEntity, options, MakeSelfCert*, MakeValidCertsChainTSA, ToPEM |
| Concurrent test CA names / serials | testca/configuration.go, entity.go, concurrency_test.go |
NewEntity, Entity.Issue, Entity.IncrementSN, NextSerialNumber |
| CLI: HSM/KMS key management | cmd/hsm-tool/cli/hsm.go, csr.go, cli.go |
Cli, HsmListCmd… , CsrCreateCmd… |
| CLI: PKI inspection | cmd/xpki-tool/cli/certs.go, crl.go, ocsp.go, csr.go |
CertInfoCmd, CertValidateCmd, CRL*Cmd, OCSP*Cmd, OCSPValidation, CRLValidation |
Package cryptoprov
Provider-agnostic key abstraction: Provider (generate/lookup/export keys +
Manufacturer/Model), KeyManager (enumerate tokens and keys, key info,
destroy), the Crypto registry keyed by manufacturer and model, the process-global
loader registry, token config loading, PKCS#11 URI parsing, PEM/DER key
parsing, TLS key-pair loading and AES-GCM helpers.
Files
| File | Role |
|---|---|
provider.go |
Interfaces, KeyInfo/TokenInfo, Crypto (New, Add, ByManufacturer), ErrNilProvider, ErrDuplicateProvider |
loader.go |
loaders map + lockLoaders; Register, Unregister, Registered, LoadProvider, Load (closes loaded providers on error) |
config.go |
TokenConfig interface, JSON/YAML struct, LoadTokenConfig with file: PIN resolution (absolute, cwd, config dir) |
uri.go |
RFC 7512 parser (parsePKCS11URI), ParseTokenURI, ParsePrivateKeyURI, pin-value redaction |
utils.go |
Crypto.LoadPrivateKey (PEM or pkcs11: URI), ParsePrivateKeyPEM*, ParsePrivateKeyDER, LoadTLSKeyPair, TLSKeyPair |
signer.go |
NewSignerFromFromFile, NewSignerFromPEM |
gcm.go |
GcmEncrypt/GcmDecrypt (nonce prefixed) |
Invariants
- Providers self-register in
init():crypto11→SoftHSM,awskmscrypto→AWSKMS,gcpkmscrypto→GCPKMS,inmemcrypto→inmem.testprovdoes not. Blank-import the provider packages beforeLoad. - Config location
""or"inmem"maps to manufacturerinmem;.jsonsuffix selects JSON, otherwise YAML. JSON keys:Manufacturer, Model, Path, TokenSerial, TokenLabel, Pin, Attributes; YAML keys are snake_case. Providerdoes not embedKeyManagerorClose; type-assert when needed.- Key URI (RFC 7512,
uri.go):pkcs11:then path attributesmanufacturer,model,serial,token,id,typeseparated by;, then?and the query attributesmodule-name,module-path(overridesmodule-name, must be absolute),pin-valueandpin-source(file:URIs only, content trimmed) separated by&. Values are percent-decoded with+kept literal, attribute names are case-sensitive, unknown and vendor attributes and empty segments (a trailing or doubled separator) are ignored, and the URI is trimmed of surrounding whitespace. The four query attributes are also accepted in the path (the form this package accepted before), but not in both places. A duplicate attribute,pin-sourcetogether withpin-value(RFC 7512 §2.4, by presence, even when one is empty), a relativemodule-path, a bad percent escape or a malformed segment is a wrappedErrInvalidURI;ParsePrivateKeyURIrequirestype=private,serialandid(ErrInvalidPrivateKeyURI;idmay be binary). Manufacturer and model are always trimmed of spaces and NULs. Error messages quote the URI with everypin-valueredacted per component (a path value ends at;, a query value at&, and a quoted segment is redacted whole); an unreadablepin-sourcefile keeps its*fs.PathErrorin the chain (uriErrorunwraps to bothErrInvalidURIand the cause) (XPKI-027, fixed). Cryptois safe for concurrent use (XPKI-016):Addis serialized by a mutex and publishes a new copy of theproviderKey{manufacturer, model}map through anatomic.Pointer;ByManufacturerdoes not lock. The default provider's key is memoized inNewand checked first. The zero value works (no default).- Duplicates: re-adding the same instance, including the default, is a
no-op when its dynamic value is comparable (pointers; every provider in
this module). Instances are compared with
reflect, never panicking; a non-comparable value (a struct holding a map/slice/func) can not be matched, so re-adding it isErrDuplicateProvider. A different instance with a registered or the default key returns wrappedErrDuplicateProvider, soLoadfails when two configs share manufacturer and model.New(nil, …), a nil entry inNew's list andAdd(nil)return wrappedErrNilProvider; typed nils (nil pointer, map, func, …) count as nil (XPKI-026). Sentinels are wrapped witherrors.Wrap(f), so stdlib and cockroachdberrors.Isboth match. Loaddoes not add the default provider to the map (ByManufacturerchecks the default first), so a non-comparable default loads (XPKI-113). It closes the providers it already loaded (those withClose() error) when it returns an error.file:PIN content has trailing\r/\nstripped; other whitespace is part of the PIN.ParsePrivateKeyDERaccepts PKCS#8 (RSA, ECDSA, Ed25519), PKCS#1 and SEC1; the parse error from each attempt is preserved (errors.Join) underfailed to parse key.TLSKeyPair/LoadTLSKeyPairsetCertificate.Leafand return an error when the private key's public half does notEqualthe leaf's public key.- Errors are
cockroachdb/errors; sentinelsErrInvalidURI,ErrInvalidPrivateKeyURI.
Test layout
Only Test_LoadConfig, Test_Load, Test_P11 and Test_LoadSigner_P11
need SoftHSM at /tmp/xpki/softhsm_unittest.json (make hsmconfig); they
call requireSoftHSM (testenv.RequireFile, XPKI-100), and
loadP11Provider closes the library at cleanup. Everything else is
fixture-free with inmemcrypto/testprov. crypto_test.go covers the
Crypto nil/duplicate contract, and registers a throwaway loader
(cryptoprov-test-closer, unregistered at cleanup) for LoadProvider and
Load close-on-error tests; no test unregisters a built-in loader.
TestLoad_KMSProviders loads the self-registered AWS (lazy client) and GCP
(stubbed KmsClientFactory, restored at cleanup) loaders without KMS
(XPKI-099). crypto_concurrency_test.go has the Add/lookup race test and
BenchmarkByManufacturer/BenchmarkByManufacturerWithAdd. testdata/
holds inmem_testprov.{json,yaml}, inmem_pin.txt, test-{cert,key}.pem.
Package crypto11
PKCS#11 wrapper over github.com/miekg/pkcs11 exposing HSM-resident RSA and
ECDSA keys as crypto.Signer/crypto.Decrypter, with a per-slot session pool,
key generation/lookup/destroy, token enumeration and HSM randomness. Requires a
C toolchain (cgo) and dlopens the module named in the config.
Files
| File | Role |
|---|---|
doc.go |
Package comment |
crypto11.go |
Sentinel errors (errClosed after Close), PKCS11Lib, PKCS11Object, PKCS11PrivateKey, Close() error |
config.go |
TokenConfig, Init (module ref, selectToken by every configured serial/label, login session, unwind on error), Option/WithMaxSessions, ConfigureFromFile, LoadTokenConfig |
module.go |
Process-wide module registry matched by loader handle, else moduleID: openModule, module.release (last ref finalizes and unloads) |
module_dl_unix.go, module_dl_other.go |
loadedHandle (cgo dlopen/dlclose, -ldl on Linux); 0 on non-unix |
sessions.go |
sessionPool (bounded per slot), withSession, NewSession, lifecycle guard (acquirePool/enter/exit), sessionOps test seam |
provider.go |
cryptoprov glue: init() registration, LoadProvider, EnumTokens, EnumKeys, KeyInfo |
keys.go |
KeyPurpose, findKey, ListKeys, FindKeyPair*, ConvertToPublic, GetKey, ExportKey, GenerateRSAKey, GenerateECDSAKey, IdentifyKey |
rsa.go |
PKCS11PrivateKeyRSA: generate, Sign (PKCS#1 v1.5, PSS), Decrypt (PKCS#1 v1.5, OAEP), Validate |
ecdsa.go |
PKCS11PrivateKeyECDSA: curve table (P-224/256/384/521), generate, Sign (DER r,s) |
common.go |
Attribute/class/type name maps, CK_ULONG codec (ulongSize, checked bytesToUlong, keyTypeAndClass, deprecated BytesToUlong, UlongToBytes), ECDSA signature DER helpers, label/ID generation on the held session |
util.go |
CurrentSlotID, TokensInfo, DestroyKeyPairOnSlot, getPublicKeyPEM (on a given session) |
rand.go |
GenRandom |
Invariants
- Module ownership (XPKI-001/007): every
PKCS11Libon one library file shares one*pkcs11.Ctxfrom themodulesregistry (modulesMu). On unix a module is identified by the dynamic loader handle (loadedHandleinmodule_dl_unix.go,dlopen(RTLD_NOLOAD)afterpkcs11.New), so a bare name found on the search path, a path, a symlink and a hardlink to one loaded library share it; a duplicate load only drops its extra loader reference. Elsewhere (module_dl_other.go)moduleIDmatches paths byos.SameFileand bare names by name. The first reference runsC_Initialize; the lastCloserunsC_Finalizeand thenDestroy. IfC_InitializereturnedCKR_CRYPTOKI_ALREADY_INITIALIZED(initialized outside this package), the module is shared but never finalized here.Initreleases its reference and sessions on every error after the load. - Each
PKCS11Libowns a login session (Session, opened and logged in byInitthrough thesessionOps.loginseam) that keeps the token logged in while pooled sessions come and go; it is closed byCloseand not counted in the pool limit. NoC_Logout. - Re-login and handle refresh (XPKI-110):
withSessionrecovers two failures, each at most once per call (the callback runs at most three times). An idle pooled session whose handle is stale (staleSessionErrors:CKR_SESSION_HANDLE_INVALID,CKR_SESSION_CLOSED, as after a token was removed and reinserted) is discarded together with every other idle session of the slot (purgeIdle) and the callback runs on a new session. A logged-out login slot (the callback failed with aloginSensitiveError:CKR_USER_NOT_LOGGED_IN,CKR_OBJECT_HANDLE_INVALID,CKR_KEY_HANDLE_INVALIDorerrKeyNotFound, whileC_GetSessionInforeports a public session, since private objects are invisible without a login; or the login generation advanced during the callback because another caller re-logged in) triggersrelogin(a no-op when the generation advanced) and one retry. Only the slotInitselected is logged in again (isLoginSlot); aCKR_USER_NOT_LOGGED_INfrom a still logged-in token (CKA_ALWAYS_AUTHENTICATEkeys) or from another slot is returned as is. Device errors only discard the session, so the re-login is lazy.reloginis serialized byloginMuand guarded by theloginGengeneration, so concurrent failures cost oneC_Login: it opens a new session onSlot.id, logs in withConfig.Pin()(no other PIN storage), replacesSessionand then closes the old one (the slot never has zero sessions, which logs a SoftHSM token out).CKR_USER_ALREADY_LOGGED_INis success. A PIN failure (stickyLoginErrors) is kept inloginErrand returned by every later operation without touching the token, so a changed PIN cannot lock it; a newInitis needed. Other login failures are retried by the next operation. A logout invalidates private object handles for good (PKCS#11 §5.7.2), soPKCS11PrivateKeyRSA/PKCS11PrivateKeyECDSAcarry an unexportedobjectRef(class, an owned copy of the CKA_ID, current handle; the id is read once by the constructors, or passed when the key was found by id or generated) andwithKey, used by RSA/ECDSASign, RSADecryptandIdentifyKey, looks the object up again by CKA_ID onCKR_OBJECT_HANDLE_INVALIDorCKR_KEY_HANDLE_INVALID(the code C_Sign/C_Decrypt use,staleKeyHandleErrors) and runs the callback once more (so up to six runs per call with thewithSessionretries). The exportedPKCS11Objectkeeps its two public fields, so positional literals still compile;Identify(*PKCS11Object)uses the handle as given. A key without CKA_ID gets noobjectRefand keeps its handle, and a lookup matching several objects iserrAmbiguousObject, never a guess.PKCS11Object.Handlekeeps the original value and may be stale after a logout. Key generation: onceC_GenerateKeyPairsucceeded, a failure to read the public key or CKA_ID destroys the pair (discardGeneratedPair, best effort) and is returned wrapped bynoRetry, whichwithSessionreturns unwrapped without running the callback again, so a retry never generates a second pair or duplicates a caller-supplied id; a failure ofC_GenerateKeyPairitself (nothing committed) is retried like any other.EnumKeyson the login slot checks the session state first and re-logs in when it is public, since a logged-out token silently lists no private keys.Sessionis replaced by a re-login: callers must not cache or close it. Callbacks passed towithSessionmust be safe to run again after such a failure (which leaves no PKCS#11 operation active). - Session pools (XPKI-002/003/005): one
sessionPoolper slot, created on first use underPKCS11Lib.mu. At mostmaxSessionslive sessions per slot (defaultDefaultMaxSessions= 1024,WithMaxSessions); a borrower waits (sync.Cond, no FIFO) for a returned session. Returns never block. A session whose callback failed withsessionUnusablecodes (CKR_SESSION_HANDLE_INVALID,CKR_SESSION_CLOSED,CKR_OPERATION_ACTIVE, device/token removed or error) or panicked is closed, not reused; it keeps its capacity untilCloseSessionreturns (a failed close releases it).Initrejects a nilOption.withSessioncallbacks must not borrow again (key-label/ID randomness uses the held session). Sign/Decrypt use the slot recorded on the key object (PKCS11Object.Slot), so keys found on other slots work. Close() errorruns once (closeOnce); every call, concurrent or later, waits for it and returns the same result. New and queued operations geterrClosed; it waits for borrowed sessions (in-flight operations) to return, closes all sessions of thisPKCS11Lib(joining close errors, including sessions returned duringClose), releases the module and setsCtxto nil. Every method that touchesCtxgoes throughwithSessionorenter/exit, includingExportKey(lookup and token info in one pooled operation, never a nested guarded call),EnumTokens(true)and the public caller-session methods (ListKeys,FindKeys,FindKeyPairOnSession,Generate{RSA,ECDSA}KeyPairOnSession), which wrap unexported versions used inside pooled operations.EnumKeyskeeps its own read-only session, so write-protected tokens list. Direct use of the exportedCtxand caller sessions fromNewSessionare untracked; close them beforeClose, and do not callClosefrom inside an operation.- Token selection (XPKI-006,
selectToken): a token must match every nonempty configured field (serial AND label when both are set); empty fields are ignored, never matched against empty token fields.InitreturnserrNoTokenSelectorbefore loading the module when both are empty, anderrTokenNotFoundwhen nothing matches; among several matches the first slot wins.Pinmay befile:<path>(trailing line endings stripped, other whitespace kept). - CK_ULONG attributes (XPKI-011): values are exactly
ulongSizebytes (C.sizeof_ulong: 8 on LP64 unix, 4 on Windows/32-bit) in host byte order, decoded withencoding/binary.NativeEndian, nounsafe. Internal readers (EnumKeys,KeyInfo,FindKeyPair/FindKeyPairOnSession) usebytesToUlongand returnerrMalformedUlongfor any other length. The deprecated exportedBytesToUlongreturnsCK_UNAVAILABLE_INFORMATION(^uint(0)) instead of panicking. - RSA: exponent 65537; PSS accepts
PSSSaltLengthAuto(largest salt that fits, ascrypto/rsa),PSSSaltLengthEqualsHashor an explicit length; PKCS#1 v1.5 and OAEP support SHA-1/224/256/384/512 (SoftHSM2 only does SHA-1 OAEP), any other hash is rejected witherrUnsupportedRSAOptions.Decryptaccepts nil,*rsa.PKCS1v15DecryptOptions(SessionKeyLen 0 only) or*rsa.OAEPOptions. OAEP/PSS parameters usepkcs11.NewOAEPParams/NewPSSParams. - Public key export needs a separate
CKO_PUBLIC_KEYobject with the same ID/label. EnumKeys/ListKeys/FindKeysdrainC_FindObjectsin batches of 100 (findAllObjects), so large tokens are not truncated.DestroyKeyPairOnSlotreturnserrKeyNotFoundwhen neither the private nor the public object exists;ConvertToPublicalso accepts the wrapper returned byGenerateRSAKey/GenerateECDSAKey.- Panics:
mustMarshalat init, RSASign(nil opts)(same as stdlib). Everything else returns wrapped errors.
Test layout
TestMain loads /tmp/xpki/softhsm_unittest.json only when the file exists
and closes p11lib (checking the error) before os.Exit. SoftHSM tests call
requireP11, which uses testenv.RequireFile (missing config skips, or fails
with XPKI_INTEGRATION=required) and fails when a present config did not load.
Fixture-free: sessions_test.go (pool bounds, disposal, panic, open errors,
Close waiting/wakeups, concurrent pool creation vs Close) and
relogin_test.go (retry bounds, one re-login under concurrency, sticky PIN
errors, stale idle sessions, handle refresh, Close during a re-login)
through the sessionOps seam (open/close/login/state/find, with
fakeSessions counters, gates and logout()), config/DSA tests;
relogin_softhsm_test.go covers a real logout, EnumKeys after a logout,
concurrent operations costing one login, a sticky wrong PIN, and
C_CloseAllSessions in a re-executed child (runChild), since it
invalidates the shared p11lib; close_test.go (errClosed from the
caller-session methods, concurrent Close sharing its result, errors from
sessions returned during Close, moduleID matching, and ExportKey with a
Close injected through the exportKeyAdmitted hook; symlinked module sharing
on SoftHSM). TestLifecycle_BareNameAlias re-executes a child with
LD_LIBRARY_PATH/DYLD_LIBRARY_PATH so a bare name and a path share a module. lifecycle_test.go covers shared-module
refs, closing with live and active sessions (SoftHSM handle probes via
GetSessionInfo), Init failure unwinding, and re-executes the test binary
(XPKI_CRYPTO11_CHILD) to prove C_Finalize ran (a fresh C_Initialize
succeeds) after failed Inits and the last Close, and that an externally
initialized module is not finalized. sessions_bench_test.go holds the
session/lifecycle benchmarks (BenchmarkSession_Saturation with
-benchtime=1x). No testdata/. Keys generated by tests persist in the
token unless the test destroys them.
Packages cryptoprov/awskmscrypto, gcpkmscrypto, inmemcrypto, testprov
| Package | Manufacturer | Key material | ExportKey returns |
Config Attributes |
|---|---|---|---|---|
awskmscrypto |
AWSKMS |
KMS RSA 2048/3072/4096, P-256/384/521 sign keys | pkcs11: URI (serial = ARN) |
Endpoint=<url>,Region=<r> (both optional) |
gcpkmscrypto |
GCPKMS |
Cloud KMS HSM-level RSA 2048/3072/4096, P-256/384 signing keys | pkcs11: URI (id = K/cryptoKeyVersions/N, serial = 1) |
Keyring=projects/P/locations/L/keyRings/R (required), Endpoint=host:port (optional) |
inmemcrypto |
inmem |
In-process RSA/ECDSA | PKCS#1 / SEC1 PEM bytes | none |
testprov |
testprov |
In-process RSA/ECDSA, implements crypto.Decrypter |
pkcs11: URI with token=<label> |
none |
Invariants: KMS providers call the SDKs with context.Background() (ROADMAP);
KmsClientFactory package vars are the test seams (the GCP one takes the
Endpoint attribute, applied with option.WithEndpoint, XPKI-021); GCP
Close must be called to release gRPC.
AWS credentials, the default region and retries come from the SDK default
chain (config.LoadDefaultConfig), which reads AWS_ACCESS_KEY_ID,
AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN before the shared config;
Init no longer copies them into a static provider (XPKI-034: it was
redundant, and static environment credentials are not refreshable either
way). The Region attribute overrides the SDK region; Endpoint sets
BaseEndpoint. AWS keys are signing keys only: GenerateRSAKey rejects
purpose 2 and a key size other than 2048/3072/4096 before any RPC, and
GetKey returns an error for a key whose usage is not SIGN_VERIFY or
that is PendingDeletion (XPKI-031; a Disabled key gets a signer, since
it can be enabled again); a label becomes the key description and,
sanitized to [a-zA-Z0-9:/_-] with aws/ stripped, its alias (an alias
failure is logged, not returned). A created key whose public key can not
be fetched or parsed is scheduled for deletion (discardKey, best effort,
logged) before the error is returned. NewSigner needs the algorithms
KMS reports for the key; with none, every Sign fails. AWS Signer.Sign (XPKI-025) requires non-nil opts:
the hash selects the KMS algorithm (RSASSA_PKCS1_V1_5_*, RSASSA_PSS_*
with *rsa.PSSOptions, ECDSA_*), which must be in the SigningAlgorithms
KMS reported for the key (an ECDSA key has only its curve's), the digest
must have the hash length, PSS options are rejected for an ECDSA key and
the PSS salt must be PSSSaltLengthEqualsHash or the hash size (KMS signs
with the hash-length salt; local-kms uses a maximal salt); all checked
before any RPC, and a nil or empty response is an empty response error.
AWS EnumKeys (XPKI-032, XPKI-033) lists SIGN_VERIFY keys that are not
PendingDeletion whose label (the description, also KeyInfo.Label)
starts with prefix, in ListKeys order: KMS lists ids only, so every key
of the account is described (pages of 1000, DescribeKey at most 8 at a
time, the unexported describeConcurrency), which needs kms:DescribeKey
on every key. A key the caller may not describe (AccessDeniedException)
is left out and logged at WARNING; any other ListKeys or DescribeKey
failure cancels the calls in flight and is returned wrapped (errors.As
finds the smithy.APIError), and a truncated page without a marker is
also an error; there is no partial result.
GCP key identity (XPKI-020): a key ID is K or K/cryptoKeyVersions/N;
GetKey, KeyInfo and DestroyKeyPairOnSlot use the named version. A bare
K is resolved at each call from ListCryptoKeyVersions: GetKey signs
with the newest ENABLED version (none is an error); KeyInfo describes
the newest ENABLED, else the newest not DESTROYED, else the key alone
without version fields (includePublic is then an error, XPKI-117);
DestroyKeyPairOnSlot schedules every ENABLED or DISABLED version,
newest first, stopping at the first error (none is an error, XPKI-116), and
an explicit version is destroyed with one RPC. Signers from GenerateRSAKey,
GenerateECDSAKey and GetKey carry K/cryptoKeyVersions/N as their key ID
and resolve their version resource name once in NewSigner, so
ExportKey's URI pins the version; ExportKey makes no RPC and copies the
id as given (serial is always 1). EnumKeys does not list versions
(CurrentVersionID only from a primary version). GCP keys are signing keys
only (XPKI-019): GenerateRSAKey rejects purpose 2 before any RPC and treats
every other purpose as signing, like the other providers (XPKI-118); the
algorithm is PKCS#1 v1.5 SHA-256 (2048/3072) or SHA-512 (4096), P-256/SHA-256,
P-384/SHA-384. Signer.SignatureAlgorithm() implements
csr.SignatureAlgorithmer from the KMS algorithm (x509SignatureAlgorithms:
PKCS#1 → SHAnWithRSA, PSS → SHAnWithRSAPSS, EC → ECDSAWithSHA256/384,
others Unknown), so csr.DefaultSigAlgo signs CSRs and certificates with
the hash and padding the key version accepts (SHA-256 for 3072-bit and
4096-SHA256 keys, PSS for PSS keys; XPKI-114); sigalgo_test.go signs CSRs
for every algorithm on the fake gRPC KMS. GetKey
rejects a version that is not ENABLED or whose algorithm is not in
signSchemes (PKCS#1/PSS RSA and P-256/P-384 digest signing; secp256k1 is
excluded because crypto/x509 cannot parse its key, XPKI-119). Init
requires the Keyring attribute (XPKI-120). KeyLabelAndID
(XPKI-022) lower-cases the name, maps characters outside [a-z0-9_-] to -,
cuts the label to 63 and the id to 54 characters plus - and 8 crypto/rand
characters; genKey retries a new id up to 3 times on ALREADY_EXISTS. Key
generation (XPKI-024) polls GetCryptoKeyVersion (state, not error text) at
most 60 times, 1 s apart, stops at once on an RPC error or a state other than
PENDING_GENERATION, and the wait between polls ends on Close (ErrClosed)
or context cancellation; the interval, attempt count and wait are unexported
fields set by export_test.go.
GCP lifecycle (XPKI-018): every client-using Provider method and
Signer.Sign registers with enter/exit (not nested); Close (once, via
sync.Once) rejects new calls with wrapped ErrClosed, ends the wait for key
generation, waits for in-flight ones, then closes the client and returns its
error; concurrent/later Close wait and return nil. The KmsClient field is
never cleared; calling its methods directly bypasses the guard. GCP
Signer.Sign (XPKI-025, XPKI-019) requires non-nil opts whose hash is the
key algorithm's, a digest of that hash's length, and *rsa.PSSOptions (salt
PSSSaltLengthEqualsHash or the hash size; PSSSaltLengthAuto is rejected
because KMS cannot produce a maximal salt, XPKI-124) exactly for PSS algorithms,
checked before any RPC; (XPKI-023) it accepts a response only with
VerifiedDigestCrc32C and a present, matching SignatureCrc32C. Nil KMS
responses are empty response errors; missing optional metadata
(VersionTemplate, CreateTime) is omitted from KeyInfo (no
protection/algo Meta, nil CreationTime), the selected version supplies
CurrentVersionID, state and, when set, algo/protection, and GCP key
labels are sorted by name. inmemcrypto.NewProvider() is
used at runtime by authority/ocsp.go for delegated responder keys. Both
inmemcrypto and testprov registries use an RWMutex for map publication
and lookup (XPKI-017, Fixed by IM1 and TP1). Key generation, signing,
decryption, and export serialization/formatting run outside the map lock.
Lookups retain signer identity. inmemcrypto exports caller-owned PKCS#1
(RSA) or SEC1 (ECDSA) PEM bytes with an empty URI; testprov exports a
PKCS#11 URI with nil key bytes. Token configuration passed to Loader must
remain unchanged during use. Metrics: metricskey.PerfCryptoOperation.
Tests: AWS awskmsprov_test.go (Test_KmsProvider) needs local-kms on
:14556 (make start-local-kms, dummy AWS_* env) and is gated with
testenv.RequireTCP (XPKI-100); it verifies every signature locally and
lists the keys of its run by a unique prefix. The other AWS tests use
fake_test.go's fakeKMS, an in-memory KmsClient with real local key
pairs (one cached per spec), KMS-shaped errors (types.*Exception,
smithy.GenericAPIError), paging, call counts, per-method overrides and
DescribeKey latency/failure hooks with peak-concurrency tracking;
export_test.go has NewTestProvider and SetDescribeConcurrency.
signer_test.go covers local option rejection without RPC and signature
verification per algorithm; generate_test.go purpose/size rejection,
aliases, GetKey usage and empty responses; enum_test.go prefix
contents, paging, failures at every position with no partial result and
kept error identity, and bounded concurrency; enum_bench_test.go
BenchmarkEnumKeys (calls, listed keys and peak concurrency per listing);
init_test.go the SDK credential chain, region/endpoint attributes and
Init errors (it swaps the global factory and the environment, so it is not
parallel). GCP tests need no fixture and no
testify mock. gcpkmscrypto/kmsserver_test.go is an in-process gRPC KMS
(fakeKMSServer: keys and versions with real local keys, id/label/state/digest
checks, paged version listing, injectable pending polls and creation errors)
reached through the real SDK client (grpcProvider, export_test.go
NewKmsClient); gcpkmsprov_test.go loads it through KmsLoader and the
Endpoint attribute end to end. fake_test.go has fakeKMS (func-field
client that records calls; unexpected calls return an error; its listing
methods return nil) and newProvider, built on NewTestProvider, so tests
need not swap the global factory and can run in parallel. versions_test.go
covers version selection, rotation, pinned/legacy URIs, disabled/missing
versions, paging, KeyInfo and destruction; signer_test.go option/padding
rejection without RPC, request digests, response integrity and local
verification of every algorithm; generate_test.go label/id rules, purpose
rejection, ALREADY_EXISTS retries, poll/wait counts, exhaustion, permanent
states and cancellation by Close/context; gen_bench_test.go the wait and
Close-latency benchmarks; endpoint_test.go Init-to-factory endpoint wiring
and the SDK path against the local server; coverage_test.go real SDK
pagination (listingKMSServer) and failure propagation; lifecycle_test.go
overlaps blocked signs with concurrent Close; metadata_test.go missing
metadata and nil responses.
inmemcrypto, testprov are pure.
inmemcrypto/concurrency_test.go and testprov/concurrency_test.go overlap
generation with lookup/export on one provider and check generated key
identity, missing-key behavior, and signatures. The former also verifies
PKCS#1/SEC1 parsing, signing with exported keys, and independent PEM buffers;
the latter verifies URI-only export and RSA decryption. Each package's
BenchmarkGetKey measures serial hits/misses with key generation outside
the timed loop.
Package csr
Request types shared by the CA and tooling, key generation through a
cryptoprov.Provider, PEM CSR creation and parsing into an x509.Certificate
template, subject merging, SAN classification, CRL-DP encoding, JSON/YAML
OID/Duration.
Files
| File | Role |
|---|---|
csr.go |
CertificateRequest, SignRequest, X509Subject/Name/Extension, AllowedFields, Parse/ParsePEM (verifies CSR signature), PopulateName, Encode/DecodeCDP*, GeneralName |
san.go |
SAN, ParseSAN, ApplySAN, deprecated SetSAN; DNS and IDNA validation |
csrprov.go |
Provider over one cryptoprov.Provider: GenerateKeyAndRequest, CreateRequestAndExportKey, SignRequest, DefaultSigAlgo, SignatureAlgorithmer |
keyreq.go |
KeyRequest (RSA 2048–4096, ECDSA 256/384/521, KeyPurpose), Generate, SigAlgo, NewKeyRequest |
types.go |
OID, Duration (JSON number = seconds, string = Go duration; YAML string only), BasicConstraints, policy qualifier constants |
Invariants
- SAN handling (XPKI-059):
ParseSANtrims each name, classifies it (contains://→ URI,net.ParseIP→ IP kept in 4-byte form for IPv4,mail.ParseAddress→ email, else DNS), validates and dedupes (first occurrence wins; DNS and email case-insensitively, IP by value, URI byString()). URIs and emails must serialize to ASCII. DNS: a non-ASCII name becomes A-labels (x/net/idnawithStrictDomainName(false), so underscores and*pass; this lowercases it), an ASCII name keeps its case; at most 253 characters, labels of 1–63[A-Za-z0-9_-]not starting or ending with a hyphen, a wildcard only as the whole first label of a name with two or more labels, no trailing dot;localhostis valid. Every invalid name is reported, joined asinvalid SAN "x": reason.ApplySAN(t, nil)keeps the template (CSR names survive);ApplySAN(t, []string{})clears; a non-nil list replaces the four name lists (nil when empty) and removes every raw SAN extension from a clone ofExtraExtensions, order kept; on error the template is unchanged.SetSANis deprecated: same nil/empty semantics, invalid names are skipped with an error log;ApplySAN(nil, …)is an error andSetSAN(nil, …)a no-op.SAN.Validateapplies the rules and deduplication to already classified names in place (unchanged on error); an email must be a bare addressmail.ParseAddressaccepts, since a CSR can carry any IA5 string there. A URI given as a string must contain://(urn:values are rejected as DNS names).Provider.SignRequestfails on an invalid SAN, andauthority.Issuer.Signvalidates bothSignRequest.SAN(ApplySAN) and the names copied from the CSR (SAN.Validate, errorCSR: invalid SAN ...) instead of issuing them. Parsekeeps every CSR extension except BasicConstraints inExtraExtensions;authority.Issuer.Signdecides what to keep (XPKI-049, fixed: deny-by-default for CSR extensions).KeyRequest.provis unexported;GenerateKeyAndRequestinjects the provider for requests decoded from JSON/YAML.X509NameYAML/JSON keys are lowercase (c,st,l,o,ou,email); uppercase keys are silently ignored by the YAML decoder.SigAlgo/DefaultSigAlgo: RSA 2048 and 3072 bits → SHA-256 (XPKI-114: NIST SP 800-57 rates RSA-3072 at 128 bits and GCP KMS signs 3072-bit keys only with SHA-256), 4096 and above → SHA-512; ECDSA by curve. They never return SHA-1: RSA below 2048 and unknown ECDSA curves fall back to SHA-256 (key size validation rejects them anyway).DefaultSigAlgofirst honours a signer implementingSignatureAlgorithmer(gcpkmscrypto.Signer) when it returns a known algorithm.ParseObjectIdentifierrequires the whole string to be dotted decimals (^\d+(\.\d+)*$).SignerandKeyRequestGeninterfaces are unused.
Tests: only csrprov_test.go (TestGenerateKeyAndRequest,
TestCreateRequestAndExportKey) needs SoftHSM, gated by
testenv.RequireFile in loadProvider (XPKI-100); TestCSR and every other
test use inmemcrypto. san_test.go and sigalgo_test.go table the SAN
rules and the hash defaults (including stub signers advertising an
algorithm). No testdata/.
csr/parsing_coverage_test.go covers signed CSR BasicConstraints, tampered
signatures, GeneralName ASN.1 variants, invalid provider requests, and YAML
conversion errors with generated keys.
Package authority
In-process CA. Config → Authority → Issuer → Sign.
Files
| File | Role |
|---|---|
authority.go |
Authority registry (by label, profile, SKID, key hash, name hash), NewAuthority |
config.go |
Config, CAConfig, IssuerConfig, AIAConfig, CertProfile, CAConstraint, LoadConfig, Validate, role/extension allow-lists, Usages |
issuer.go |
Issuer construction, Sign pipeline, fillTemplate, serial generation (20 random bytes, top bit cleared), SignProof/VerifyProof |
ocsp.go |
SignOCSP, CreateDelegatedOCSPSigner, OCSPResponder, delegated responder issuance/renewal (delegatedResponder), reason/status maps |
extensions.go |
Certificate Policies ASN.1, SKI, CT OIDs, effective OCSP-signing EKU (ekuHasOCSPSigning, isOCSPSigningTemplate) |
root.go |
NewRoot: key + CSR + self-signed root |
util.go |
Issuer.GenCert: key, CSR, sign, write files (existing files renamed .bak) |
README.md |
Configuration and signing flow diagrams, per-extension source table (profile / SignRequest / CSR), validity envelope |
Config
See README for a sample. Key rules: profile name = SignRequest.Profile
(default if empty); issuer_label: "*" profiles are wildcard. A populated
issuer allowed_profiles restricts the issuer to the listed profiles, named and
wildcard alike; empty keeps named profiles and no wildcard ones; a populated
list must include the issuer's delegated_ocsp_profile (issuerHasProfile,
XPKI-057). expiry/backdate are csr.Duration; usages names come
from oid.KeyUsage/oid.ExtKeyUsage; allowed_extensions empty allows every
SignRequest extension but no CSR extension (IsAllowedExtention vs.
allowsCSRExtension, XPKI-049); allowed_fields nil means copy the subject and
all SAN fields from the CSR (never its extensions); extensions values accept
hex:, base64: or bare, and Validate rejects repeated OIDs and OIDs that
collide with policies/ocsp_no_check (XPKI-050). IssuerConfig.Type is the
type key in YAML and JSON (XPKI-058). AIA crl_expiry, ocsp_expiry, crl_renewal are
time.Duration with defaults applied through the Get* accessors.
Field ownership in Issuer.Sign
- Profile: key usages, CA constraints, SKI, AIA/OCSP/CRL URLs (
${ISSUER_ID}or:ISSUER_ID→ issuer SKID), policies, OCSP no-check,extensions, expiry and backdate (NotBefore = now rounded to a minute minus backdate, default 5m; NotAfter = NotBefore + expiry, capped at the issuer NotAfter;validityWindow). SignRequest(trusted RA):Subjectmerge,SAN(non-nil replaces CSR SANs),Extensions(subject toallowed_extensions, empty = all, and may include profile-owned OIDs such as a critical EKU; withomit_disabled_extensionsdisallowed ones are dropped, otherwise rejected),NotBefore/NotAfter(bounded: NotBefore ≥ now − backdate, NotAfter > NotBefore, lifetime ≤ expiry; rejected otherwise, XPKI-054),Profile.- CSR (untrusted): subject/SANs per
allowed_fields, public key, and only extensions listed inallowed_extensions(empty = none; disallowed ones followomit_disabled_extensions).csrDeniedExtensions(SKI, KU, SAN, BasicConstraints, AKI, EKU, OCSP no-check) are always dropped; an AIA or CRL DP is dropped when the issuer generates one (XPKI-049). - One extension per OID (XPKI-050). Raw extensions are kept in the order
profile
extensions>SignRequest> CSR (first per OID wins); a repeated profile OID failsSign. Profilepolicies/ocsp_no_checkthen replace any raw copy (setExtension). For KU, EKU, basic constraints, SKI/AKI, SAN, AIA and CRL DP, a kept raw profile orSignRequestextension overrides the template-built value inx509.CreateCertificate; the CSR cannot supply these, except an AIA/CRL DP the issuer does not generate.
Invariants
Issuer.lockguardscfg.Profilesonly;Issuer.Profilesreturns a copy.Authoritykeeps its issuer and profile maps in an immutableregistrysnapshot (atomic.Pointer);AddIssuerandAddProfilecopy-on-write undermu, and a rejectedAddIssuer(duplicate label, profile served by another issuer, nil profile) publishes nothing. Lookups are lock-free;ProfilesandIssuers(sorted by label) return copies. A registered*CertProfileis shared with every reader and must not be modified; register aCopyinstead (XPKI-055). OCSP responders (XPKI-051/052/053):caResponderis immutable afterCreateIssuer; the delegated responder is anatomic.Pointersnapshot issued underrenewLock. Lock order isrenewLock→lock(Sign→Profile); never acquirerenewLockwhile holdinglock. Renewal starts when the responder expires withinocsp_expiry. ASignOCSPcaller with a still-valid responder never waits: within the retry window (renewal.retryAt, an atomic snapshot) it takes no lock, otherwise it usesTryLock. On renewal failureSignOCSPuses a still-valid cached responder (retry afterocspRenewRetryInterval, 1 minute) and otherwise returns an error, never the CA key; callers that queued during a failed attempt share its error.CreateDelegatedOCSPSignerblocks onrenewLockand returns the last error while renewal is overdue.CreateIssuer, and each issuance on the exact profile snapshot it signs with (signWithProfile), rejects a missing or CA delegated profile, one whose effective EKU lacks OCSP signing (a raw profile EKU extension is decoded and overridesusages), or one whose expiry does not exceedocsp_expiry+effectiveBackdate+delegatedValidityMargin(1m) (validateDelegatedOCSPProfile). After a failed attempt the cached responder's validity and the retry interval are measured from when the attempt ended, not when it started.fillTemplatedetects a responder from the effective EKU too (isOCSPSigningTemplate), so raw-EKU responders get no OCSP/CRL URLs.renewWaitHookis a test-only seam. Delegated responses capNextUpdateat the responder'sNotAfter.- Profiles must be
Validate()d before use (compiles regexes;LoadConfigdoes). Copy()methods are shallow for*CertProfile.- Metrics:
metricskey.PerfCAOperation,PerfCASignRequest.
Tests: authority_test.go (suite) generates a 3-level chain with testca
into /tmp/xpki/certs/* referenced by testdata/ca-config.dev.yaml, and
loads the local-kms provider (loading does not connect). Only
TestNewRoot generates a key in local-kms and is gated by requireKMS
(internal/testenv); TestShakenRoot/TestIssuerSign use inmemcrypto,
so the rest of the package runs without fixtures (XPKI-100). SoftHSM is not
used.
testdata/invalid_*.json drive validation errors; testdata/csrprofiles/*.yaml
are used by cmd/hsm-tool tests (lowercase names keys, see csr invariants).
ocsp_coverage_test.go verifies direct responses and cached delegated responders
with fresh testca certificates. ocsp_responder_test.go covers fresh
delegated creation (with a deadline), renewal, renewal failure with and without
a valid cache (a failing or gated countingSigner), the retry interval,
waiters sharing a failure, a CA expiring within ocsp_expiry, profile
validation, NextUpdate capping, and synchronized concurrent cold
start/renewal; issuer_test.go
TestNewIssuerDelegatedOCSP builds one from files. ocsp_bench_test.go has
BenchmarkSignOCSP (warm sign/lookup), BenchmarkDelegatedOCSPRetryWindow
and BenchmarkDelegatedOCSPCreate. issuer_coverage_test.go exercises proof signatures, extension
policies, and internal template validation. issuer_policy_test.go covers the
AU1 issuance policy with hostile signed CSRs (profile-owned OIDs, SAN bypass,
allow-list/omit matrix, issuer-generated CRL DP), extension precedence, and
validityWindow against a fixed clock. config_test.go has the
allowed_profiles named/wildcard × nil/empty/populated matrix.
Package certutil
Certificate, PEM, key and chain helpers plus a CFSSL-derived bundler.
Files
| File | Role |
|---|---|
pem.go |
Parse/encode certificates, public and private keys (PKCS#8 → PKCS#1 → SEC1; RSA/ECDSA/Ed25519 parse, RSA/ECDSA encode; legacy Proc-Type: 4,ENCRYPTED decrypt) |
pkcs8.go |
decryptPKCS8: ENCRYPTED PRIVATE KEY with PBES2 + PBKDF2 (HMAC-SHA1/224/256/384/512) + AES-128/192/256-CBC, used by GetKeyDERFromPEM |
bundler.go |
Bundler, options (WithKeyUsages, WithBundleFlavor, WithAIA, WithHTTPClient, WithSystemRoots), Chain, Bundle/BundleContext, ChainFromPEM[Context], AIA fetch, expiry checks, IntermediateStash |
bundle.go |
Bundle/BundleStatus, VerifyBundleFromPEM, LoadAndVerifyBundleFromPEM, BuildBundle, FindIssuer, SortBundlesByExpiration |
hash.go |
Hash name maps, Digest, SHA1*, SHA256*, HashToHex/Base64URL, ParseHexDigestWithPrefix |
cert_id.go |
GetThumbprintStr (SHA-1 of DER), GetSubjectKeyID, GetAuthorityKeyID, GetSubjectID, GetIssuerID |
keyinfo.go |
KeyInfo, NewKeyInfo (RSA/ECDSA from signer, decrypter or JWK) |
name.go |
NameToString (OpenSSL-style DN) |
ocsp.go |
CreateOCSPRequest (nil certificate/issuer or unavailable hash is an error; the issuer must carry crt's issuer name and its key must verify crt's signature, SHA-1 allowed, XPKI-121) |
extensions.go |
FindExtension*, IsOCSPSigner, HasOCSPNoCheck |
random.go |
RandReader, Random, RandomString (panic on RNG failure) |
Invariants
- Chain building:
certs[0]is the leaf;Forceonly checks each cert is signed by the next;Optimalrunsx509.VerifyagainstRootPoolandIntermediatePool, fetches AIA intermediates on unknown authority whenWithAIA(true), ranks chains shortest-then-longest-expiring, and strips the root unless the leaf has OCSP servers and the chain is ≤ 2. "Expiring" is less than 720h left. - Trust roots (XPKI-041): the flavor defaults to
Optimalwith trust roots (explicit roots orWithSystemRoots(true)) andForcewithout them; the lastWithBundleFlavorwins.NewBundlerrejectsOptimalwithout trust roots and unknown flavors. System roots are trusted only throughWithSystemRoots, which adds explicit roots tox509.SystemCertPool().VerifyOptions().Rootsis never nil, and anOptimalBundlewith a nilRootPoolfails, so no path verifies against ambient system trust. - AIA fetch (XPKI-037, XPKI-039): each request uses
NewRequestWithContextwith theBundleContextcontext and a deadline of the clientTimeout, or 3s when it is zero. Only a 200 response of at most 1 MiB is parsed, and the body is never logged. Each URL is requested at most once perBundlecall, including failures; the next call retries. A done context stops the traversal and the returned error matchesctx.Err(). - Concurrency (XPKI-035): a
Bundleris safe for concurrentBundle,ChainFromPEMandVerifyOptionscalls.mu(RWMutex) guardsRootPool,IntermediatePoolandKnownIssuersonce in use. Each call reads asnapshotand verifies without the lock.verifyChainadds intermediates it verified to a private clone and publishes them once withlearn, which copies the map and installs the clone, or merges into a copy of the current pool when another call published first. A pool or map once read is never modified, soVerifyOptionsreturns a snapshot. The exported fields are set-up state: set them before first use, then read the pools throughVerifyOptions. Learning costs one pool clone per newly learned intermediate (O(pool)); warm calls take only the read lock. Concurrent misses on one issuer each fetch its URL, at most once per call, with no cross-call coalescing. Only RSA/ECDSA leaf keys accepted. - Input (XPKI-036, XPKI-042):
Bundle/BundleContextof a nil or empty list returns an error matchingErrNoCertificates, and a nil entry is an error.BuildBundlerejects a nilChainorCert(the latter wrapsErrNoCertificates), treats a nilStatusas empty, and accepts a rootlessForcechain (emptyRootCert/RootCertPEM). SortBundlesByExpiration(XPKI-038) returns a new slice, stably sorted byExpiresdescending with nil bundles last; the input slice is not reordered and the bundles are shared.ExpiresInHourstruncates toward zero (XPKI-045).- Encrypted keys (XPKI-043):
GetKeyDERFromPEMdecrypts legacy RFC 1423 PEM and PKCS#8 PBES2 with PBKDF2 (HMAC-SHA1 default, SHA-224/256/384/512, at most 10,000,000 iterations,keyLengthmust match) and AES-CBC. PBES1, PKCS#12 PBE, scrypt, DES/3DES and other ciphers returnunsupported PKCS#8 encryption: …. A nil password fails withencrypted private key; a wrong password (bad padding, or plaintext that is not one RFC 5958PrivateKeyInfostructure, XPKI-115) matchesx509.IncorrectPasswordError; the key inside is parsed afterwards byParsePrivateKeyDER. - Process-global:
IntermediateStash(fetched intermediates written0644),RandReader.HTTPClientis deprecated and never read (XPKI-044); useWithHTTPClient. Default AIA client timeout 3s. ParseChainFromPEMreturns the parsed prefix and an error on trailing garbage.
Tests: testdata/ holds a Mozilla root bundle, 229 intermediates, test server
chain and hash fixtures; testdata/pkcs8/ holds OpenSSL-generated
plain and encrypted (password xpki-test) RSA/EC/Ed25519 PKCS#8 keys,
including unsupported des3/scrypt/PKCS#12 samples. pkcs8_test.go also
builds PBES2 structures in Go for the PRF × AES matrix, malformed
parameters and DER plaintexts that are not a PrivateKeyInfo. TestKeyInfoKMS is the only fixture test: it is gated with
testenv.RequireTCP on local-kms :14556; TestKeyInfoOpaqueKeys covers
opaque signers without KMS. bundle_input_test.go covers the nil/empty
input contracts of Bundle, BuildBundle, SortBundlesByExpiration and
CreateOCSPRequest.
bundler_coverage_test.go uses fresh testca chains, temporary files and local
HTTP servers for AIA fetching, caching, validation, and expiry behavior; it
restores IntermediateStash and runs serially. bundler_aia_test.go uses a
per-path counting AIA server for response limits, stalls, cancellation,
per-traversal request counts (BenchmarkBundlerAIAFailingURL) and log
content; export_test.go exposes the body limit and learn (Learn).
bundler_concurrency_test.go shares one Bundler across goroutines released
together (warm hits plus two AIA chains, run with -race), covers learn
merging with a stale snapshot and nil set-up fields, and holds
BenchmarkBundle (warm serial/parallel and learning cost at pool sizes
0/100/1000). Its tests leave IntermediateStash empty and run in parallel. bundler_roots_test.go
covers flavor/root resolution and re-runs itself in a subprocess with
SSL_CERT_FILE/SSL_CERT_DIR set to a generated root to test system trust
(skipped on darwin/windows). bundler_ranking_test.go tests
internal chain selection. pem_coverage_test.go covers malformed encodings
and file errors without adding private-key fixtures.
Package jwt
Self-contained JWS/JWT: HS256/384/512, RS256/384/512, ES256/384/512.
Files
| File | Role |
|---|---|
token.go |
Token, VerifyConfig, ValidClaims, DecodeSegment/EncodeSegment |
jwt.go |
Interfaces, ProviderConfig, LoadProvider, NewProvider, MustNewProvider, NewProviderFromCryptoSigner, NewProviderWithSymmetricKey, WithHeaders, provider.Sign/ParseToken |
sign.go |
SignerInfo, alg selection from key, HMAC signer (constant-time verify), VerifySignature |
parser.go |
TokenParser (Parse, ParseWithClaims, ParseUnverified), ParserConfig, NewParser (JWKS-backed) |
claims.go |
Claims, MapClaims getters/validation, NumericDate, Audience, CreateClaims, TimeNowFn, DefaultTimeSkew |
jwks.go |
KeySet, AlgorithmKeySet, StaticKeySet, RemoteKeySet (lazy fetch, inflight coalescing, refresh cooldown), RemoteKeySetOptions, ErrKeyNotFound, ErrAmbiguousKey |
Invariants
- Alg from key: RSA ≥4096 → RS512, ≥3072 → RS384, else RS256; P-521 → ES512,
P-384 → ES384, else ES256. HS256 key ring: seeds are SHA-256'd,
kidheader set;NewProvidererrors ifkidis not inkeys. - Default expiry 60m,
DefaultNotBefore−2m,DefaultTimeSkew5m oniat/nbfonly.ExpectedAudiencemeans all listed values present. Issuer/subject compared case-insensitively. - Every provider's
ParseTokenaccepts only tokens whosealgis its own signing algorithm (ValidMethods, XPKI-112): the HS256 key ring rejects HS384/HS512 tokens signed with a ring key, and an RS256 provider rejects RS384/RS512 tokens signed with its private key.provider.ParseTokenrequireskidfor HS tokens, except forNewProviderWithSymmetricKey(XPKI-066): it signs without akidunlessWithHeaderssets a nonempty string one, and verifies with its single key only tokens with nokidor thatkid(allowNoKid); any otherkid, including an empty or non-string one, isunexpected kid.parser.ParseTokenrefuses HS.alg: noneis rejected. Numerickidheaders are stringified. - The protected header is
typ,algand theWithHeadersentries (kidfor the key ring,jwkfor asymmetric keys); no headerjtiis generated (XPKI-073). A token identifier is the payloadjticlaim, set by the caller (CreateClaimstakes it);Signnever adds one, so identical claims sign to identical HS/RS tokens. Signwritesexp,iatandnbfas NumericDate whatever their Go type (time.Time,*time.Time,NumericDate, RFC 3339 or numeric strings, numbers) withMapClaims.NormalizeTimeClaimson a copy of the claims (accesstoken.Signuses the same method); a valueMapClaims.Timecannot parse, or a zero time, is aSignerror that leaves the map unchanged.MapClaims.Timereads NumericDate,time.Time,*time.Time,NumericDate/*NumericDate, numeric strings, RFC 3339 strings (whatjson.Marshalwrites for atime.Time) and the legacy2006-01-02T15:04:05.000-0700layout, so a string time claim is validated rather than skipped (XPKI-109). Auint64aboveMaxInt64, a float outside int64, or a numeric string orjson.Numberoutside int64 is nil (DEBUG log), never a wrapped negative time, soNormalizeTimeClaimsrejects it too. The unexportedtimeClaimdistinguishes an absent claim from a present one that is not a time;VerifyExpiresAt/VerifyIssuedAt/VerifyNotBefore, and soValid, reject the latter (invalid exp claim: ...) instead of skipping the check (XPKI-125).- Headers (XPKI-104): every constructor creates
headersbefore applying options, andvalidateHeadersruns after them. Analgheader other than the signing algorithm is a constructor error. With HS keys (NewProviderkey ring,NewProviderWithSymmetricKey) akidheader must be the signing key's ID. Asymmetric providers accept anykid, andtyp,jwkand other headers stay overridable (dpop setstyp).NewProviderWithSymmetricKeyrejects an empty key and copies it. - Key selection (XPKI-071/072,
selectKey): a key is eligible when its JWKuseis empty orsigand, when the alg is known, its type/curve and JWKalgfit it (RS* → RSA, ES256/384/512 → P-256/384/521; other algs have no eligible key). AkidselectsKeySetentries with thatKeyID, elseStaticKeySet.PublicKeysby RFC 7638 SHA-256 thumbprint (base64url); an emptykidconsiders all entries of both lists. Exactly one eligible key must remain, otherwiseErrKeyNotFound/ErrAmbiguousKey(wrapped).PublicKeysaccepts only*rsa.PublicKey/*ecdsa.PublicKey; anything else fails every lookup.parser.ParseTokenpasses the token alg throughAlgorithmKeySet.GetKeyForAlgorithm; plainGetKeychecks onlyuse. RemoteKeySet(XPKI-070) refetches when no cached key fits the lookup, at most once perWithRefreshCooldown(default 10s, measured from the end of the previous fetch, successful or not; 0 disables). Inside the cooldown a miss fails from the cache, or with the last fetch error when nothing is cached. Each fetch is bounded byWithFetchTimeout(default 10s, applied as a context deadline even with an injectedWithHTTPClient) andWithMaxResponseSize(default 1 MiB, larger bodies rejected); response bodies are never echoed in errors. The shared fetch runs on the set's lifetime context, so cancelling one waiter does not cancel it.refreshpublishes cache/lastFetch, bumps thefetchescounter and clearsinflightbefore waking waiters. A lookup whose cache snapshot predates a completed fetch (keysFromCachereturns the counter) shares that fetch's result instead of starting another, so coalescing holds with cooldown 0. The read limit ismaxResponseSize+1except atmath.MaxInt64.NewParseruses the defaults.ParseWithClaimsverifies the signature before validating claims.MapClaims.Int/Int64/UInt64return 0 (DEBUG log) on overflow, negative-to-unsigned, or parse failure.NumericDateandMapClaims.Timeaccept fractional seconds and truncate to whole seconds with exact arithmetic (parseNumericDate), so a fractionalexpis still validated.MustNewProviderpanics;TimeNowFnis a mutable global used by tests.- go-jose v4 is used only for
JSONWebKey/JSONWebKeySettypes.
Tests: testdata/jwtprov*, oidc_parser* (Google/Cognito JWKS snapshots),
embedded real ID tokens; Test_SignPrivateKMS needs local-kms on :14555
(kmsConfig, localKMSAddr) and is gated by testenv.RequireTCP; every
other jwt test is fixture-free. parser_coverage_test.go covers
configuration files, malformed tokens, real symmetric/asymmetric signing, the
standalone symmetric provider (round trip, wrong key, tampering, kid policy,
header options), key-ID types, and claim conversions.
TestProviderHeaderValidation (jwt_test.go) covers the header checks of the
config and crypto-signer constructors. sign_policy_test.go covers the
header without jti, the algorithm pin of every constructor (hand-signed
HS384/HS512 and RS384/RS512 tokens with the provider's own key) and time
claim normalization; TestValid_RFC3339TimeClaims (claims_test.go) covers
string time claims in Valid.
jwks_test.go has table tests for key selection, parser round trips with
kid-less tokens and PublicKeys, and RemoteKeySet behavior against a
local httptest JWKS server (jwksServer: mutable body/status and a request
gate for stalled fetches). jwks_internal_test.go drives the cooldown with
the unexported RemoteKeySet.now clock and calls keysFromRemote with a stale
snapshot count. jwks_bench_test.go
(BenchmarkRemoteKeySet) reports fetches/op for known, repeated-unknown
and parallel unique-unknown kids.
Packages jwt/dpop, jwt/accesstoken, jwt/oauth2client, dataprotection
- dpop:
dpop.goconstants (HTTPHeader,DefaultExpiration10m,CnfThumbprint,ClaimAccessTokenHash) andAccessTokenHash(ath = base64url SHA-256),keys.goP-256 JWK generate/load/save (<folder>/<thumbprint>.jwk, 0600),signer.goproof signer (typ: dpop+jwt,jwkheader, 22-character jti, htu keepsRawPath),verify.gorules in order: compact proofs decode the protected header first with go-jose's case-sensitivejsonfork (so a privatejwkor HMACalgis a DPoP error, not a go-jose parse error, andTYPis nottyp); JSON JWS is parsed so more than one signature istoken contains multiple headers; thentyp, publicjwk, alg in the asymmetric allow-list (RS*, PS*, ES*, EdDSA); the signature is verified by go-jose with the embedded JWK before any claim is read (go-jose rejects a key type/curve that does not fit the alg), and claims are decoded case-sensitively likeGetTokenInfo; thenjti/htm/htu/iatpresent,htuequal afterhtu.gonormalization,iatwithin 10m, exp/nbf, optional iss/sub/aud/nonce,athwhenVerifyConfig.AccessTokenis set (which requiresExpectedThumbprint:athalone is computable by a token thief), proof thumbprint equal toExpectedThumbprint(constant time), and lastReplayCache.Add, so only a fully valid proof consumes its jti.ReplayCacheis opt-in (nil = no replay detection). The key is base64url SHA-256 of thumbprint + jti (fixed 43 bytes), retained throughiat + DefaultExpirationorexpif earlier, inclusive.replay.goMemoryReplayCache: one mutex, map plus expiry min-heap, evicts entries whose expiry is before now on everyAdd, fails closed withErrReplayCacheFullat capacity (default 100000), clockTimeNowFn.htu.go:VerifyRequestClaimsbuilds the request URI fromExternalURL(trustedscheme://host[:port], validated per call), else URL scheme/host, thenreq.Host, with https for an empty scheme; query and fragment dropped.normalizeHTUlowercases scheme and host, drops the default port, decodes unreserved escapes, uppercases other escapes, keeps path case and dot segments (a router may dispatch/admin/../xelsewhere);htmmust equal the request method exactly, since HTTP methods are case-sensitive (RFC 9110 §9.1, XPKI-108). Binding to the access token:ExpectedThumbprint, or compareResult.Thumbprintwith thecnf.jktclaim. - accesstoken:
pat.<base64url(AES-GCM(json claims))>; non-pat.tokens delegate to the innerjwt.Provider.Signcopies the claims (the caller map is never modified), keeps callerexp/iat/nbfnormalized to NumericDate (rejecting unparsable ones), and withoutexpaddsexp= now +TokenExpiry()plusiat/nbfwhen absent, usingjwt.TimeNowFn.TokenExpiry()=WithTokenExpiryif non-zero (negative → 0), else the inner provider's, else 0; a non-positive value makesSignfail.ParseTokenrequiresexpunlessWithAllowNoExpiry(legacy migration; an unparsableexpis always rejected, and an RFC 3339 one from an oldtime.Timeis parsed and checked) (XPKI-078, 109). A nildpis allowed:PublicKeyreturns nil andpat.Sign/ParseTokenreturn an error (XPKI-079).SetRevocationis forwarded to the inner provider. Tests that pinjwt.TimeNowFn(setClock) must not callt.Parallel. - oauth2client:
config.goConfig/ClientConfig(env://values viax/configloader),client.goClient,CreateTokenRequest[WithContext],provider.goregistry lookups by provider id, email, domain (ClientForEmailreturns nil unless the value islocal@domain). AClientowns a deep copy of itsClientConfig(clone):Config()returns a copy,SetClientSecret/SetPubKeyare the only mutations, under the client's RWMutex, andCreateTokenRequestWithContextsnapshots the id, secret and URL under it;PublicKey()returns the key parsed fromPubKey(JwksURLandPubKeyare configuration for a caller's verifier, this package verifies nothing) (XPKI-080). TheProviderregistry is an immutableregistrysnapshot in anatomic.Pointer, replaced under a writer mutex byRegisterClient, so a registration is published to the three indexes at once and a rejected one changes nothing;overrideremoves the previous client of that provider id from every index before publishing (XPKI-081). Lookups are lock-free (one atomic load);Config()costs one deep copy (an allocation for the struct and one per non-nil slice andIDPParam).provider_bench_test.gohas the lookup, enumeration, token-request andConfig()benchmarks. - dataprotection:
Providerinterface;NewSymmetric(secret)= HKDF-SHA256 → AES-256-GCM, blobnonce(12) || ciphertext || tag(16)(SymmetricNonceSize,SymmetricTagSize,SymmetricOverhead), no associated data and no key id, so rotation is the caller's: record which secret protected a blob, keep the old provider to read, re-protect on read. The secret is key material, not a passphrase (SymmetricMinSecretSize= 32 bytes recommended, not enforced); one secret protects at mostSymmetricMaxMessagesPerKey(2^32) messages (NIST SP 800-38D §8.3 random-IV bound) of less than 2^36−32 bytes each.doc.gostates the limits,symmetric_limits_test.gochecks the constants against the AEAD andexample_test.gogenerates the secret withcrypto/rand(XPKI-083, fixed). The KDF and blob format are unchanged.
Tests are pure except keys_test.go writing under os.TempDir().
dpop/verify_policy_test.go covers replay (sequential, 32 simultaneous
duplicates, store error, retention), ath/cnf.jkt binding, server-style
requests for htu, and a real-signature matrix for every allowed alg;
htu_internal_test.go tables the normalizer; example_test.go compiles the
doc.go sample; verify_bench_test.go has BenchmarkVerifyClaims,
BenchmarkVerifyClaimsReplayCache and BenchmarkMemoryReplayCache. Only
the non-parallel TestMemoryReplayCache_Expiry replaces dpop.TimeNowFn.
oauth2client/request_coverage_test.go checks token-request authentication,
context cancellation, preservation of caller-owned form values, and registry
conflicts/overrides; it makes no network requests.
Helper packages
- armor:
Decodeonly. The CRC24 checksum line is optional (RFC 9580 §6.1): the last non-empty line before-----ENDis the checksum line when it starts with=(unless the payload decodes only with that line, which is then base64 padding on its own line); a well-formed one setsBlock.HasCRCandBlock.CRC,Block.CRCValid()compares it withCRC24(Bytes), and a missing, malformed or wrong checksum never rejects a block (XPKI-047, fixed). Framing or base64 damage still returns nil and the decoder moves to the next block; it never panics.testdata/holds GPG keys including anocrcvariant and the corrupted variants, each classified inTest_ArmorDecode_Corrupted. - oid: exported maps are process-global;
KeyUsagesreturns canonical names in RFC 5280 bit order, each bit once. - x/print: writes to an
io.Writer, ignores write errors, local time; a zeroNextUpdateprintsExpires: not set;JSONswallows marshal errors by design. Tests incertutil_test.goloadtestdata/*.pemand append synthetic*x509.Certificatevalues to cover SAN, AIA, CRL, and extension formatting. - metricskey: descriptors only; registered by consumers.
- internal/version:
buildis set by the linker (make buildpasses-X ...internal/version.build=$(GIT_VERSION)); otherwisebuildVersionreads the module version fromdebug.ReadBuildInfo, elsedevel-<revision>[-dirty], elsedevel(XPKI-097).PopulateFromBuildstrips a leadingv. - internal/testenv: test-only; imports
testing.RequireTCPdials with a 1s timeout and skips or fails (XPKI_INTEGRATION=required) only when the fixture is unreachable;RequireFiledoes the same for a missing fixture file and always fails on other stat errors (XPKI-100). - testca: everything panics on failure (test-only). Defaults RSA-2048,
NotBefore = epoch, NotAfter = +10y, subject
[TEST].Chain()includes leaf and root.ToPKCS8is stdlib PKCS#8 as aPRIVATE KEYPEM block (RSA, ECDSA, Ed25519);PFX/ToPFXencode PKCS#12 with go-pkcs12Modern2023(PBES2 AES-256-CBC, PBKDF2-HMAC-SHA-256, HMAC-SHA-256 MAC) and accept any BMP-string password, including an empty one (a non-BMP character panics, since PKCS#12 stores the password as UCS-2); noopensslis needed (XPKI-063, fixed).utils_test.godecodes both outputs. Default common-name allocation uses an atomic counter; a per-entity mutex protectsIncrementSN's return-and-increment ofNextSN(XPKI-062, fixed). Key generation and signing run outside that mutex.Issuecopies the caller's options before adding its issuer, which retains precedence over suppliedIssueroptions (XPKI-107, fixed). Concurrent calls require immutable package defaults, entity fields and option data, plus a signer that supports concurrent use. DirectNextSNaccess requires no issuance orIncrementSNcalls in flight; do not copy anEntityafter first use.concurrency_test.gouses synchronized workers to verify unique default names, complete serial sequences from zero and configured starting values, signed certificates from a shared issuer, and option-slice preservation.
CLIs
- hsm-tool (
cmd/hsm-tool):--cfgprovider config (orinmem/plain),--cryptoextra providers,--plain-key,-D,-l. Commands:hsm list,hsm info <id>,hsm generate,hsm remove <id>,csr create,csr gen-cert,csr sign <csr>.hsm list/info/removeselect a token by--serialor--tokenlabel (tokenFilter);infoandremovefail withtoken not foundwhen a filter matches nothing. Output is JSON on stdout (print.CertAndKey);--output PREFIXwrites.pem/.csr/.key(.keyis 0600). Providers are blank-imported incli/cli.goand loaded lazily byCryptoProv(), whose error (empty or bad--cfg) fails the command with exit status 1 (XPKI-084). - xpki-tool (
cmd/xpki-tool):--timeoutseconds for HTTP. Commands:csr-info,cert info,cert validate(--ca,--root,--revocation,--with-aia),crl info,crl fetch(needs--outputor--print; errors when no selected certificate has a CRL distribution point),ocsp info(--issuerPEM verifies the response signature),ocsp fetch(error when the certificate has no OCSP URL; every endpoint is tried and each failure is printed as<url> : ERROR: ...; one valid response is a success, and when all fail it returnsno valid OCSP response from N endpoint(s)listing each<url>: <reason>, XPKI-102). HTTP helpers take the CLI context; output paths usefilepath.Join. - Exit codes: kong parse error → 80;
Runerror → 1; panic → 2.-as a file name reads stdin. - Tests:
cmd/hsm-tool/cliuses testify mocks for providers, pluscsr_test.go(TestCsrSuite) which needs local-kms on:14555(the:14556provider is loaded lazily and never called) andauthority/testdataand is gated bytestenv.RequireTCP(XPKI-100);hsm_cli_test.goTestParsebuilds a fresh kong parser and destination per case, since a reused parser keeps flags from earlierParsecalls (XPKI-101).cmd/xpki-tool/cliusesx/print/testdata,cli/testdata/ocsp1.resand local HTTP servers, no network. - Both READMEs are generated from
--helpoutput; regenerate them when flags change.
Test layout summary
| Fixture | Provided by | Needed by |
|---|---|---|
/tmp/xpki/softhsm_unittest.json, token xpki_unittest, PIN ~/softhsm2/xpki_pin_unittest.txt |
make hsmconfig (scripts/config-softhsm.sh) |
crypto11, cryptoprov (four gated tests), csr (csrprov_test.go, gated) |
local-kms on :14555 and :14556 |
make start-local-kms (docker-compose.yml) |
awskmscrypto (Test_KmsProvider only, gated), authority (TestNewRoot only), jwt (Test_SignPrivateKMS only), certutil (TestKeyInfoKMS only, gated), cmd/hsm-tool/cli (TestCsrSuite, gated) |
AWS_ACCESS_KEY_ID etc. dummy values |
Makefile exports |
AWS SDK |
/tmp/xpki/certs/* |
authority_test.go via testca |
authority/testdata/ca-config.dev.yaml |
internal/testenv.RequireTCP gates a fixture-dependent test: an unreachable
fixture skips it unless XPKI_INTEGRATION=required, which the Makefile
exports (so make test/covtest and CI fail); a reachable fixture always
runs it. internal/testenv.RequireFile does the same for a fixture file
(crypto11, cryptoprov and csr gate on the SoftHSM config). Every
fixture-dependent test in authority, crypto11, jwt, cryptoprov,
certutil, csr and cmd/hsm-tool/cli is gated this way; no test fails
hard when a fixture is missing unless XPKI_INTEGRATION=required
(XPKI-100, fixed).
cmd/xpki-tool/cli/coverage_test.go uses generated certificates and local HTTP
servers to cover certificate filters, trust validation, concurrent revocation
checks, CRL/OCSP fetch and inspection, and input/transport errors. Its OCSP
responder answers per certificate serial, so TestOCSPFetchEndpointPolicy
asserts that ocsp fetch fails when every endpoint fails and succeeds when
one answers (XPKI-102); cmd/xpki-tool/main_test.go checks the exit status
- It also asserts that a nil certificate or issuer returns the
CreateOCSPRequesterror withocsp.Unknownand no HTTP request (XPKI-103). Fixtures uset.TempDir(). Incmd/xpki-tool/cli/suite_test.go,testSuite.SetupSuiteallocates a unique directory on the suite's parent test; Go removes it after all suite subtests finish. Overlapping CLI test processes cannot overwrite or remove one another's fixtures (XPKI-105, fixed); give each process separate coverage and log output paths.
SoftHSM setup scripts
scripts/config-softhsm.shvalidates flags and tools and propagates command failures.softhsm2-utilis required;pkcs11-toolis required only for--list-slots/--list-object.--moduleoverrides discovery; Linux probes standard library directories, and macOS usesbrew --prefix softhsm.- New configs use the selected
--tokens-dir;--cfg-dirselects the exportedSOFTHSM2_CONFfor all child tools. Existingsofthsm2.conffiles are kept;--forceresets token storage and this config file, preserving other files in the config directory. Token labels are matched literally, not as regexps. - Explicit
--pintakes precedence over--pin-file. PIN files have trailing CR/LF stripped; other whitespace is preserved.--generate-pinusesopenssl rand -hex 16only if no nonempty PIN is available, and requires--pin-fileor--out-cfgso the PIN is retained. PIN files and output JSON are mode 0600, including pre-existing files; neither PINs nor JSON contents are printed. JSON strings are escaped. scripts/config-softhsm_test.shruns isolated temporary-directory/stub-tool regression checks viamake test-scripts.make hsmconfigruns them before creating the standard integration fixture, so the CI Prepare step executes them. The shell tests need Bash and ordinary Unix utilities, with no HSM, OpenSC, Homebrew, Python, or network dependency.make hsmconfigbuildsbin/hsm-toolbefore changing the fixture, usessofthsm2-utilfor token deletion/initialization, then runshsm listwith the generated JSON and the sameSOFTHSM2_CONFas the setup script. This verifies provider loading, PIN login and token/key enumeration through our CLI; it requires Go/cgo but no OpenSC. The CLI manages keys, not token initialization or deletion. The script's OpenSC listing flags remain opt-in.
Build and CI
make toolsinstalls golangci-lint v2, cov-report, govulncheck and gomarkdoc at the versions pinned by theGOLANGCI_LINT_VERSION,COV_REPORT_VERSION,GOVULNCHECK_VERSIONandGOMARKDOC_VERSIONvariables inMakefile(overridable on the command line), intobin/(GOBIN), which.project/gomod-project.mkputs onPATH. Update a pin deliberately: bump it, runmake tools lint covtest docs, and commit any.golangci.yamlchange the release needs (XPKI-096).make build→bin/hsm-tool,bin/xpki-tool.make test,make testshort,make test RACE=true,make covtest coverage(per-package-coverpkg=./...merged by cov-report; exclusions in.project/gomod-project.mk).make fmtformats (gofmt -s);make fmt-checklists and diffs the filesmake fmtwould change and fails without writing, and also fails when gofmt cannot parse a file.make lint=fmt-check+ vet +vulns(govulncheck) +golangci-lint run, andcovtest/testintdepend onfmt-check, so none of the CI targets modifies the checkout (XPKI-095).make versionprintsGIT_VERSION, whichmake buildandmake hsmconfiglink into the CLIs throughLDFLAGS(XPKI-097).make docsruns gomarkdoc forcrypto11,cryptoprov,testcaintoDocumentation/and dumpsbin/*-tool --helpintoDocumentation/cli/(runmake buildfirst; thecli/directory must exist).make all= clean, tools, generate, change_log, start-local-kms, hsmconfig, covtest.docker-compose.yml(make start-local-kms, projectxpki-kms) runs twonsmithuk/local-kms:3.11.7containers on the project's default network, publishing:14555and:14556; no static addresses, noversion:key (XPKI-098). The emulator keeps its keys in memory, so--force-recreatestarts from an empty key store. Bump the image tag deliberately and rerun the KMS-dependent suites (awskmscrypto,authority,jwt,certutil,cmd/hsm-tool/cli)..golangci.yaml: v2, default linters plusreviveexported;_test.goexcluded.golangci-lint runmust stay clean (staticcheck SA1019 catches deprecated calls).- CI
.github/workflows/unittest.yml: on push tomain/release-*/tags and PRs.detect-noop(fkirc/skip-duplicate-actions) setsshould_skipfor a PR whose changes all matchpaths_ignore(Markdown, images,Documentation/) or that duplicates an already successful run; pushes, schedules and releases never skip. TheUnitTestjob runs only whenshould_skip != 'true'(XPKI-094):make tools,make lint,apt-get install softhsm2,make vars generate hsmconfig start-local-kms,make covtest,git diff --exit-code(the build must leave the checkout unchanged), then the PR status "code cov" (success when total coverage is strictly greater thanMIN_TESTCOV=90). When the job is skipped for a PR, thecode-cov-skippedjob posts "code cov" as success with the descriptionskipped: no Go or .VERSION changes, so a required status never stays pending. Lint failures (gofmt, vet, govulncheck, golangci-lint) fail the job (XPKI-095). On push tomainwith a changed.VERSION, a tag$(cat .VERSION).$(git rev-list --count HEAD)is created (settag.ymldoes the same on demand).