Documentation
¶
Index ¶
- Constants
- Variables
- func CleanupMachine() error
- func CleanupMachineBySHA256(fp [32]byte) error
- func CleanupSmoke(rootDir string, caCertDER []byte) error
- func CleanupSmokeAnchorBySHA256(hexFP string) error
- func ComputeSHA256Fingerprint(der []byte) [32]byte
- func MachineAgentPath() (string, error)
- func MachineTLSPath() (string, error)
- func ParseSHA256Fingerprint(hexFP string) ([32]byte, error)
- func TestCreateKey(name string) (crypto.Signer, error)
- func TestDeleteKey(name string) error
- func TestOpenKey(name string) (crypto.Signer, error)
- func TestSignAndVerify(signer crypto.Signer) error
- type MachineKeyDeleter
- type MachineKeyStore
- type Material
- func LoadServingMaterial() (Material, error)
- func Provision(dataDir string, protector Protector, trustStore TrustStore, ...) (Material, error)
- func ProvisionMachine() (Material, error)
- func ProvisionSmoke(rootDir string) (Material, error)
- func ProvisionWithKeyStore(dataDir string, keyStore MachineKeyStore, trustStore TrustStore, ...) (Material, error)
- func ReloadMachine() (Material, error)
- type Protector
- type TrustProvisioner
- type TrustState
- type TrustStore
- type TrustVerifier
Constants ¶
const ( SmokeCAKeyName = identity.SmokeCAKeyName SmokeServerKeyName = identity.SmokeServerKeyName )
Smoke key names — explicitly in the Keppin.Test.* namespace.
const ( // RenewalThreshold is how close to expiry we renew the server certificate. RenewalThreshold = 30 * 24 * time.Hour )
Variables ¶
var ErrKeyNotFound = errors.New("persisted CNG key not found")
ErrKeyNotFound indicates that the exact persisted CNG key does not exist. Cleanup treats this as an idempotent success, not a failure.
var ErrTrustAnchorNotFound = errors.New("trust anchor certificate not found in LocalMachine\\Root")
ErrTrustAnchorNotFound indicates that the exact CA trust anchor is not present in the machine trust store (i.e. it is already absent). Cleanup treats this as an idempotent success, not a failure.
Functions ¶
func CleanupMachine ¶
func CleanupMachine() error
CleanupMachine removes exactly the Local-TLS-owned production material:
- the exact Local CA trust anchor in LocalMachine\Root (identified by the on-disk CA certificate DER);
- the exact persisted Local-TLS CA CNG key;
- the exact persisted Local-TLS server CNG key;
- the Local-TLS-owned TLS state directory (...\Agent\tls).
It is suitable for an elevated installer/uninstaller/repair context and is idempotent for artifacts that are already absent.
Cleanup is best-effort across independently removable artifacts, but every failure that cannot be attributed to "already absent" is returned so that a security-sensitive artifact failure is never silently reported as success.
Trust-anchor removal is by exact SHA-256 fingerprint derived from the on-disk CA certificate. If the CA certificate DER (and thus the state directory) is already gone, CleanupMachine cannot remove the trust anchor by exact match and reports that exact boundary; call CleanupMachineBySHA256 with the known fingerprint instead.
func CleanupMachineBySHA256 ¶
CleanupMachineBySHA256 is CleanupMachine, but it removes the CA trust anchor by its exact SHA-256 fingerprint instead of the on-disk DER. Use it when the Local-TLS state directory (and thus the CA certificate DER) has already been removed and only the fingerprint is known.
func CleanupSmoke ¶
CleanupSmoke removes exactly the smoke-test TLS material.
Performs three exact operations through native CNG APIs:
- Deletes the CA certificate from LocalMachine\Root by exact SHA-256 fingerprint (using RemoveTrust).
- Deletes the CNG test keys by exact name (using TestDeleteKey).
- Removes the state directory.
No wildcard/CN-based mutation. No certutil. No external tools.
func CleanupSmokeAnchorBySHA256 ¶
CleanupSmokeAnchorBySHA256 removes exactly one certificate from LocalMachine\Root by its SHA-256 fingerprint. Unlike CleanupSmoke, this does not require the DER file — it works directly from the fingerprint. Use for cleaning up stale anchors after state directory deletion or when the original DER is unavailable.
Requires Administrator elevation.
func ComputeSHA256Fingerprint ¶
ComputeSHA256Fingerprint returns the SHA-256 fingerprint of a DER certificate.
func MachineAgentPath ¶
MachineAgentPath returns the production machine state root. On Windows this resolves %ProgramData%\Keppin\Agent\.
This directory is machine-scoped (not per-user) and is the authoritative location for the machine Agent Service state, local TLS material, and installation-level configuration. Per-user credentials or session state MUST NOT be stored here.
ACL intent (not enforced by Go):
- SYSTEM: Full Control
- Administrators: Full Control
- LOCAL SERVICE: only required access
- Ordinary interactive users: no direct access to machine-private state
func MachineTLSPath ¶
MachineTLSPath returns the production local TLS material directory. This is MachineAgentPath() + "\tls\".
Only public certificate DER files are persisted here. No private-key files exist — private keys live in the machine-scoped CNG key store.
func ParseSHA256Fingerprint ¶
ParseSHA256Fingerprint parses a 64-character hex SHA-256 fingerprint into a [32]byte. It accepts surrounding whitespace and is case-insensitive.
func TestCreateKey ¶
TestCreateKey creates a persisted CNG test key with the given name using the same security path as production keys. The name must stay in the test namespace.
func TestDeleteKey ¶
TestDeleteKey deletes exactly one persisted CNG test key.
func TestOpenKey ¶
TestOpenKey opens an existing test key as the current principal. This is kept intentionally separate from TestCreateKey so the manual proof can test the principal's actual KSP access behavior directly.
func TestSignAndVerify ¶
TestSignAndVerify proves the actual signing capability of the current principal by performing an ECDSA signing operation through crypto.Signer and verifying the resulting signature. This is the authoritative LocalService allow-test.
Types ¶
type MachineKeyDeleter ¶
type MachineKeyDeleter interface {
// DeleteCAKey deletes the exact persisted Local-TLS CA key.
// Returns ErrKeyNotFound when the key does not exist.
DeleteCAKey() error
// DeleteServerKey deletes the exact persisted Local-TLS server key.
// Returns ErrKeyNotFound when the key does not exist.
DeleteServerKey() error
}
MachineKeyDeleter deletes exactly the Local-TLS-owned persisted machine keys. It must never delete keys that are not owned by this module, and it deletes only by exact persisted key name — never by wildcard or CN.
func PlatformKeyDeleter ¶
func PlatformKeyDeleter() (MachineKeyDeleter, error)
PlatformKeyDeleter returns the platform-appropriate MachineKeyDeleter. On Windows this deletes the exact persisted CNG keys via the Microsoft Software Key Storage Provider. On other platforms it returns an error.
type MachineKeyStore ¶
type MachineKeyStore interface {
// LoadOrCreateCAKey returns a signer for the local TLS CA key.
// If the key does not exist it is created as a persistent,
// non-exportable machine-scoped key.
LoadOrCreateCAKey() (crypto.Signer, error)
// LoadOrCreateServerKey returns a signer for the local TLS server key.
// If the key does not exist it is created as a persistent,
// non-exportable machine-scoped key.
LoadOrCreateServerKey() (crypto.Signer, error)
}
MachineKeyStore provides machine-scoped persistent signing keys. On Windows this is backed by CNG/KSP; on other platforms it is unsupported.
The production implementation never returns private-key bytes. Keys are identified by stable names and persist across process restarts.
func PlatformKeyStore ¶
func PlatformKeyStore() (MachineKeyStore, error)
PlatformKeyStore returns the platform-appropriate MachineKeyStore. On Windows this uses CNG/KSP with the Microsoft Software Key Storage Provider. On other platforms it returns an error — machine-scoped key storage is not supported outside Windows.
type Material ¶
type Material struct {
Certificate tls.Certificate
CACertificate *x509.Certificate
ServerCertificate *x509.Certificate
CAFingerprintSHA256 [32]byte
}
Material contains the provisioned local TLS material.
func LoadServingMaterial ¶
LoadServingMaterial loads only the TLS material required for HTTPS serving. Unlike ReloadMachine, it does NOT open the CA private key and does NOT attempt certificate renewal.
It loads:
- CA certificate from disk (public DER only)
- server certificate from disk (public DER only)
- server private key via CNG (openProductionKey, read-only)
It verifies:
- server cert ↔ server KSP public key match
- server cert was issued by the public CA
- server certificate SANs
- CA trust via read-only TrustVerifier (missing or conflicting trust fails closed)
LoadServingMaterial never mutates LocalMachine\Root and never accesses the CA private key. It does not renew the server certificate; use ReloadMachine for the maintenance/renewal path. It is the function the HTTPS listener MUST use for normal runtime startup.
If the caller cannot open the server key (e.g., running as a user without LocalService rights), it fails closed.
func Provision ¶
func Provision(dataDir string, protector Protector, trustStore TrustStore, now func() time.Time) (Material, error)
Provision provisions local TLS using a Protector. This is kept for backwards-compatible tests that use exported private keys.
func ProvisionMachine ¶
ProvisionMachine provisions or repairs the production machine TLS material.
MUST be run elevated (Administrator). It:
- creates or opens machine-scoped persisted CNG keys (CA + server)
- generates self-signed CA and CA-signed server certificates
- persists only public certificate DERs to disk (no private-key files)
- installs the CA certificate in LocalMachine\Root (idempotent)
ProvisionMachine never returns private-key bytes. Keys are identified by stable names and persist in the Microsoft Software KSP across process restarts.
Repeated provisioning with the same persisted keys is idempotent: the same CA identity (fingerprint) is preserved and the CA certificate is not re-installed if already present. The server certificate is only renewed when near or past expiry.
func ProvisionSmoke ¶
ProvisionSmoke provisions smoke-test TLS material under the given root directory using test-only CNG key names. The root directory should be a temporary or clearly scoped test directory, NOT the production machine state root.
Requires Administrator elevation (creates machine-scoped CNG keys and installs the test CA in LocalMachine\Root).
Repeated provisioning with the same root is idempotent: the same CA identity is preserved and the CA certificate is not re-installed if already present.
func ProvisionWithKeyStore ¶
func ProvisionWithKeyStore(dataDir string, keyStore MachineKeyStore, trustStore TrustStore, now func() time.Time) (Material, error)
ProvisionWithKeyStore provisions local TLS using a MachineKeyStore for persistent signing keys. Only public certificate DERs are written to disk; private keys remain in the machine-scoped key store.
func ReloadMachine ¶
ReloadMachine loads existing production machine TLS material for normal runtime.
ReloadMachine is safe for non-elevated use. It:
- loads existing CA and server certificate DERs from disk
- opens (does NOT create) persisted machine-scoped CNG keys
- verifies cert ↔ KSP public key match for both CA and server
- verifies the server certificate was issued by the CA
- validates server certificate SANs (localhost / 127.0.0.1 / ::1)
- performs read-only trust verification through TrustVerifier
- renews the server certificate if near/past expiry (reuses existing KSP key)
ReloadMachine never mutates LocalMachine\Root. If the CA trust anchor is missing or a conflicting certificate exists, ReloadMachine fails closed — elevated provisioning/repair is required.
func (*Material) Close ¶
Close releases the process-local native CNG handle backing the serving signer. It never deletes the persisted CNG key, never removes certificates or trust anchors, and never triggers CleanupMachine or CleanupMachineBySHA256. Lifecycle release is distinct from persisted-key deletion and from Local TLS uninstall/cleanup.
Close is safe to call after a successful production machine operation. It is idempotent in effect: the underlying CNG signer's Close is safe to call repeatedly and reports no error. After Close, the serving certificate must not be used for new TLS handshakes.
Material is single-owner: do not copy it by value and then reuse the copy after Close, since both copies reference the same underlying signer.
type Protector ¶
type Protector interface {
Protect(plaintext []byte) ([]byte, error)
Unprotect(ciphertext []byte) ([]byte, error)
}
Protector transforms sensitive material for at-rest persistence on the legacy exported-key provisioning path. The production machine path does not use Protector: it keeps private keys in CNG/KSP and persists only public certificate DER. Protector is a seam — this package does not define which implementation (if any) actually encrypts the bytes it receives.
func PlatformProtector ¶
PlatformProtector returns the platform-appropriate Protector. Machine-scoped key protection is not configured: the production machine path uses CNG/KSP key custody rather than the protector-based path, so this function returns an error.
type TrustProvisioner ¶
type TrustProvisioner interface {
// InstallTrust installs the CA certificate DER into the machine
// trust store. It is idempotent: if the exact same certificate
// (matched by SHA-256 fingerprint) already exists, the call
// succeeds without creating a duplicate.
InstallTrust(certificateDER []byte) error
// RemoveTrust removes the exact CA certificate identified by DER
// from the machine trust store. Only the exact certificate
// (matched by SHA-256 fingerprint) is removed.
// Returns ErrTrustAnchorNotFound when the certificate is not present.
RemoveTrust(certificateDER []byte) error
// RemoveTrustBySHA256 removes the exact CA certificate identified by
// its SHA-256 fingerprint from the machine trust store. This is used
// when the original DER is no longer available (e.g. the state
// directory was already removed).
//
// Removal is by exact 32-byte SHA-256 identity only; no subject/CN
// matching is performed. Returns ErrTrustAnchorNotFound when the
// certificate is not present.
RemoveTrustBySHA256(fp [32]byte) error
}
TrustProvisioner performs elevated certificate trust operations. Mutating operations MUST only be called from an elevated context (installer, provisioning, repair). Normal runtime MUST NOT use this.
type TrustState ¶
type TrustState int
TrustState describes the result of a runtime trust verification.
const ( // TrustHealthy means the expected CA certificate is present exactly once // in the machine trust store. TrustHealthy TrustState = iota // TrustAbsent means the expected CA certificate is not present in the // machine trust store. Repair (elevated provisioning) is required. TrustAbsent // TrustConflict means a certificate with a matching subject name but a // different fingerprint exists. Manual resolution is required. TrustConflict // TrustError means the verification itself failed (store access, etc.). TrustError )
func VerifySmokeTrust ¶
func VerifySmokeTrust(caCertDER []byte) (TrustState, error)
VerifySmokeTrust performs a read-only trust verification of the smoke CA certificate. Safe for non-elevated use; never mutates Root.
func (TrustState) String ¶
func (s TrustState) String() string
String returns a human-readable representation of the trust state.
type TrustStore ¶
type TrustStore interface {
TrustProvisioner
TrustVerifier
// EnsureTrusted installs the CA certificate DER into the trust store
// if it is not already present.
// Deprecated: use TrustProvisioner.InstallTrust for elevated operations,
// and TrustVerifier.VerifyTrust for runtime checks.
EnsureTrusted(certificateDER []byte) error
}
TrustStore is the combined interface for backward compatibility. New code should use TrustProvisioner and TrustVerifier separately.
func PlatformTrustStore ¶
func PlatformTrustStore() (TrustStore, error)
PlatformTrustStore returns the platform-appropriate TrustStore. Machine-scoped trust deployment targets LocalMachine\Root on Windows.
type TrustVerifier ¶
type TrustVerifier interface {
// VerifyTrust checks whether the given CA certificate DER is
// trusted in the machine trust store. It returns the trust state
// and, when TrustError, an error describing the failure.
VerifyTrust(certificateDER []byte) (TrustState, error)
// IsTrustedSHA256 reports whether a certificate with the given
// SHA-256 fingerprint is present in the trust store.
IsTrustedSHA256(fingerprint [32]byte) (bool, error)
}
TrustVerifier performs read-only trust verification. It is safe for normal (non-elevated) runtime use.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
verify
command
Command verify performs manual verification for the Local TLS module.
|
Command verify performs manual verification for the Local TLS module. |
|
examples
|
|
|
fingerprint
command
Command fingerprint demonstrates the non-destructive fingerprint / cleanup handoff utilities of Local TLS.
|
Command fingerprint demonstrates the non-destructive fingerprint / cleanup handoff utilities of Local TLS. |
|
provision
command
Command provision demonstrates the elevated first-install/repair flow using ProvisionMachine.
|
Command provision demonstrates the elevated first-install/repair flow using ProvisionMachine. |
|
serving
command
Command serving demonstrates the preferred production HTTPS serving startup flow using LoadServingMaterial.
|
Command serving demonstrates the preferred production HTTPS serving startup flow using LoadServingMaterial. |
|
internal
|
|
|
identity
Package identity centralises the product-branding constants used by the Local TLS module.
|
Package identity centralises the product-branding constants used by the Local TLS module. |