openziti-cng

module
v0.2.3 Latest Latest
Warning

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

Go to latest
Published: Nov 17, 2026 License: Apache-2.0

README

Keppin-OSS OpenZiti-CNG

An OpenZiti identity engine adapter for existing machine-scoped Windows CNG keys in the Microsoft Software Key Storage Provider.

Dependencies

  • Go 1.26.8
  • github.com/keppin-oss/cng v0.3.1
  • github.com/openziti/identity v1.0.140
  • github.com/openziti/sdk-golang/v2 v2.0.0-pre4

The engine registers on every platform. Key access requires Windows; other platforms return the CNG platform-not-supported error.

Activation and API

Consumers must register the engine, including when using enrollment helpers:

import (
    _ "github.com/keppin-oss/openziti-cng/cngengine"
    "github.com/keppin-oss/openziti-cng/enrollcng"
)
  • enrollcng.KeyReference(name) constructs a validated reference.
  • enrollcng.BuildFlags(jwt, claims, name) wires SDK flags without network access. Callers using these flags directly own SDK error handling and diagnostics.
  • enrollcng.Enroll(jwt, name) validates the token and delegates OTT enrollment. It returns safe stage/category errors instead of raw SDK diagnostics. The category comes from positive evidence of a network error only (see errors and logging).
  • enrollcng.CertMatchesSigner(cfg, name) compares the leaf certificate public key with the CNG signer. It does not verify certificate trust or prove CSR provenance.

Key reference

Canonical form: cng:<container-name>?.

Names follow [A-Za-z0-9][A-Za-z0-9._-]{0,127}. Names are exact and are never trimmed or decoded. Whitespace, slashes, colons, percent escapes, Unicode, query values, fragments and other ambiguous forms are rejected.

The trailing ? remains required by the pinned OpenZiti identity Windows parser. Always construct references using KeyReference. An arbitrary direct call to upstream identity.LoadKey can still panic on a missing delimiter. See technical details.

Examples

  • signverify: sign and verify using an existing key.
  • enroll: enroll and save a new identity JSON file.
  • loadidentity: accept only a canonical CNG reference, load its signer, and print a status without the identity key field.

Enrollment requires a protected JWT file and a new output file:

go run -buildvcs=false ./examples/enroll -jwt C:\secure\identity.jwt -key Keppin.Identity.001 -out C:\secure\identity.json
go run -buildvcs=false ./examples/loadidentity -config C:\secure\identity.json

The enrollment example rejects raw JWT command-line arguments and refuses to overwrite output. It reserves the output before enrollment and checks writing, syncing and closing. Protect the directory using Windows ACLs: Go mode 0600 is not a Windows DACL guarantee. Disk/process failures after token consumption can still require configuration recovery; preserve the key and any partial output.

The enrollment example builds on every platform but runs only on Windows. Its errors are redacted: if windowscng.LoadOrCreate reports ErrCleanupFailed, it prints a fixed message saying the newly created key may still be persisted and needs verification and controlled manual cleanup; any other key failure, and a failure to verify the saved certificate against the CNG key after enrollment, is reported only by stage and broad category. With CNG v0.3.1, LoadOrCreate attempts a best-effort rollback of a key created by the failing call (including when exporting its public key fails) and reports ErrCleanupFailed only when that rollback fails (since CNG v0.3.0, not for a denied finalize that left no key). The rollback is not transactional, so a generic failure is not proof that no new key exists: check whether the named key exists before retrying (see key custody).

Security and ownership

CNG owns private-key custody and signing. The adapter opens existing keys and does not export or serialize private-key bytes. CNG v0.3.1 checks export policy and the DACL before exposing a signer and exports a public-key blob for verification; an anomalous public-key export result, a security descriptor read that reports 0 bytes written and an Export Policy read that does not report exactly 4 bytes are returned as errors, without a signer, instead of causing a panic or being accepted as valid. This is a software-provider/API property, not hardware isolation or a guarantee against administrator compromise or the key's history before opening.

CNG requests restrictive provisioning permissions and validates required principals plus selected disallowed principals. It does not certify exclusive principal membership or full Windows effective access. LOCAL SERVICE is shared by multiple services. See the precise DACL boundary.

Close directly owned signers when no signing operation can still use them. Since CNG v0.2.1, Sign and Close are synchronized and Close is idempotent, but Close does not drain in-flight callers. Closing releases handles; it does not delete persisted keys. The pinned SDK does not close its internally loaded enrollment signer, and the module cannot retrieve it through the public enrollment API. This residual limitation is documented; no global signer cache is used.

Protect OTT tokens, identity configuration and logs. The module sanitizes returned enrollment errors, but does not override the SDK's global logger. The separately reported Controller v2.0.3 service-session JWT logging issue is upstream context, outside this module's remediation.

Validation

go mod verify
go mod tidy -diff
go build -buildvcs=false ./...
go vet -buildvcs=false ./...
go test -buildvcs=false -count=1 ./...

Default tests exercise parsing, registration, safe diagnostics, examples and configuration serialization, plus error propagation and signer-close handling around Open/LoadOrCreate using in-memory fake signers. They do not perform live enrollment or create/delete persisted CNG keys. On Windows a few default tests open the software KSP to look up key names that do not exist. See validation boundaries, validation status of the CNG v0.3.1 upgrade and tagged fixture tests.

Directories

Path Synopsis
Package cngengine registers a Windows CNG/KSP identity engine with OpenZiti's identity package.
Package cngengine registers a Windows CNG/KSP identity engine with OpenZiti's identity package.
Package enrollcng wires Keppin-OSS CNG machine keys into OpenZiti's native OTT enrollment flow.
Package enrollcng wires Keppin-OSS CNG machine keys into OpenZiti's native OTT enrollment flow.
examples
enroll command
Command enroll saves a usable OpenZiti identity configuration using a CNG key.
Command enroll saves a usable OpenZiti identity configuration using a CNG key.
loadidentity command
Command loadidentity accepts only canonical CNG identity references.
Command loadidentity accepts only canonical CNG identity references.
signverify command
Command signverify signs and verifies using an existing CNG-backed key.
Command signverify signs and verifies using an existing CNG-backed key.
internal
diagnostic
Package diagnostic provides errors safe to print at identity boundaries.
Package diagnostic provides errors safe to print at identity boundaries.
keyref
Package keyref defines the shared, deliberately restricted CNG reference grammar.
Package keyref defines the shared, deliberately restricted CNG reference grammar.

Jump to

Keyboard shortcuts

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