Chapter 85 Verification Policy: Protocol Whitelists and Trust Decisions

Chapter Orientation

All of TLS's security decisions condense into two configuration objects. The policy (xtlspolicy): which versions, suites, groups, and signature schemes are allowed — the protocol whitelist, the baseline of Chapter 84's negotiation; the defaults are the current security baseline (2 versions/9 suites/4 groups/14 schemes, no weak algorithms), and tightening is just swapping arrays. The verifier (xtlsverifier): trust decisions — the default path goes "trust-store chain building + purpose checks + name matching" (the composition of Chapters 80/81's primitives); a custom callback hands the decision entirely to the application (certificate pinning, embedded private CAs, audit logging), and a policy callback can additionally compose CRL/OCSP. Both are immutable, shareable concurrently via reference counting across sessions — "defined once, referenced everywhere". Chapter 82's client configuration completes its full picture here.

85.1引入

Three real needs. One: a compliance audit requires your service to "allow only TLS 1.3 and two or three specific suites" — you want one change to take effect on every connection, not hard-coded values scattered across every client/server config. Two: your client connects only to your own backends, and the public CAs' trust surface is too broad — you want to pin to one specific certificate (pinning), which Chapter 81's trust store cannot do as "single certificate as anchor + fingerprint comparison + audit log". Three: an experimental environment wants to add a temporary "revocation check" (Chapter 81's CRL query) without rewriting the chain-building logic.

The three needs map to this chapter's two layers: the policy object manages the protocol face (need one), and the verifier's three-layer extension points manage the trust face (needs two and three). The key design is decision-execution separation: the verifier manages only "trust decisions"; the protocol layer's signature verification and Finished checking are still done by XRT and no callback can bypass them — what you take over is "trust or not", not "is the protocol correct".

85.2概念

The policy object: the single source of truth for protocol preferences

xtlspolicy is a borrowing-style configuration: default initialization points at process-lifetime read-only constants (zero allocation); tightening swaps in your own arrays (whose lifecycle covers context creation):

Validation rules (catching configuration errors at startup): versions and suites must be non-empty; list pointers/counts consistent, elements unique, belonging to built-in capabilities; every suite corresponds to an enabled version and every version has at least one suite; a non-empty signature list must be usable by at least one enabled version — a 1.2-only PKCS#1 scheme cannot enter a pure-1.3 policy. Two boundaries: the policy describes only preferences and promises nothing about the current build's trimming containing the corresponding backends (session creation combines xrtTlsGroupAvailable etc. to generate the actual execution path); KeySharePolicy can override the local key-share selection mode (e.g. XTLS_KEY_SHARE_PREFER_GROUP) — which group's public key the ClientHello carries is decided by it.

The verifier: three layers of trust decisions

xrtTlsVerifierCreate(配置) deep-copies the optional trust store — after creation the source store may be freed or modified; without a custom callback you must provide at least one trust anchor, and an empty store fails at creation (the same root as Chapter 82's "no verification is not an option"). The three-layer decision structure:

• Default path (xrtTlsPeerVerify): path validation at the explicit time (Chapter 81's chain building) + role-based purpose checks (digitalSignature KeyUsage, serverAuth/clientAuth EKU) + the server role matching the requested name per RFC 9525 (Chapter 80). The wire chain runs leaf to root; anchors come from the store and are not required to appear in the peer's chain.
• Verify callback (complete takeover): XTLS_VERIFY_ACCEPT takes over trust / REJECT refuses / DEFAULT falls back to the immutable store / ERROR reports a structured error. What the callback receives is the cryptographically validated peer structure (signatures and Finished guaranteed by the protocol layer) — you only decide trust. An accept still cannot skip CertificateVerify and Finished — "taking over trust" is not "taking over the protocol".
• Policy callback (stacked checks): fires after all default checks succeed, reading the xtlsverifiedpeer (Path leaf-to-root without the anchor; all views borrowed only during the callback) — composing CRL (Chapter 81), OCSP, CT, pinning, enterprise rules without re-building the chain. Returning false may set an error, wrapped as the cause of XTLS_ERROR_VERIFY.

The time source is injectable (xtlsverifytimeproc): the path and the additional policy share one deterministic time — tests reproducible, caches decidable; omit it to use xrtNow().

Boundary: the TLS core never sneaks online

The TLS core does not implicitly load system roots, download CRLs, start OCSP, or submit CT queries — data loading, encoding, and networking belong to separate composition layers. The base client never suddenly blocks on file or system APIs during verification (Chapter 77's "system-layer failure" preventive design). Want CRL? Call Chapter 81's APIs yourself in the Policy callback — soft or hard fail is your policy decision; the verifier preserves unambiguous results for you.

Assembly shape: policy + verifier + session

The complete client assembly (the exploded view of Chapter 82's example):

85.3示例

First complete program: the policy baseline and tightening validation

The following program comes from examples/tls/policy/main.c, printing the default baseline and overriding the key-share mode:

#include <xrt/tls.h>

#include <stdio.h>






















 */


/* 展示默认策略和调用方覆盖本地 key-share 选择模式。 */
int main(void)
{
	xtlspolicy Policy;

	xrtTlsPolicyInit(&Policy);
	Policy.KeySharePolicy = XTLS_KEY_SHARE_PREFER_GROUP;
	if ( !xrtTlsPolicyValid(&Policy) ) {
		return 1;
	}
	printf(
		"versions=%zu ciphers=%zu groups=%zu signatures=%zu\n",
		Policy.VersionCount, Policy.CipherCount,
		Policy.GroupCount, Policy.SignatureCount
	);
	return 0;
}

What just happened. (1) The default baseline — output as evidence: 2 versions (1.2/1.3), 9 suites, 4 named groups, 14 signature schemes — no weak algorithms; this is the "safe even unconfigured" floor. (2) KeySharePolicy = XTLS_KEY_SHARE_PREFER_GROUP overrides the local key-share selection — the ClientHello carries the preferred group's public key first, reducing HRR round trips (Chapter 84). (3) PolicyValid is the configuration's gatekeeper — swapping Versions to 1.3-only while Ciphers still holds 1.2-only suites gets rejected; the tightening example (only 1.3 + the ChaCha20/AES-GCM two suites) swaps arrays and counts together, then validates once more. Once a policy snapshot is referenced by a context it is never modified — the same configuration serves differing hardware capabilities (backend inclusion decided at session creation).

Second complete program: a custom verifier taking over trust

The second program comes from examples/tls/verify/main.c, handing the certificate decision to the application via callback:

#include <xrt/tls_verify.h>

#include <stdio.h>






















 */


/* 示例回调以应用自有的证书固定策略接管信任决策。 */
static xtlsverifydecision exampleTlsVerify(
	const xtlspeer* pPeer,
	ptr pContext
)
{
	(void)pContext;
	return pPeer->CertificateCount != 0 ?
		XTLS_VERIFY_ACCEPT : XTLS_VERIFY_REJECT;
}



/* 创建可供多个 TLS 客户端共享的自定义验证器。 */
int main(void)
{
	xtlsverifierconfig Config;
	xtlsverifier* pVerifier;

	xrtTlsVerifierConfigInit(&Config);
	Config.Verify = exampleTlsVerify;
	pVerifier = xrtTlsVerifierCreate(&Config);
	if ( pVerifier == NULL ) {
		return 1;
	}
	printf("TLS verifier is ready\n");
	xrtTlsVerifierRelease(pVerifier);
	return 0;
}

What just happened. (1) VerifyConfig.Verify = exampleTlsVerify injects the callback — this form needs no store (decisions all inside the callback). (2) The callback receives the xtlspeer (peer info: certificate-chain views, negotiated parameters) and returns a decision enum — this example is the minimal policy "any certificate is accepted" (interface demonstration only, not a copyable production policy). (3) The verifier is shareable across clients — create once, inject into every ClientConfig.Verifier, release your own reference as you go. Production forms: certificate pinning (compare the leaf's SHA-256 against a preset fingerprint, REJECT on mismatch), embedded private CA (store holding only your own root + DEFAULT fallback), audit logging (a Policy callback recording each verification's peer and path before admitting) — each with its place in the three-layer decision structure.

85.4契约

• Policy validation: non-empty versions and suites; pointers/counts consistent, elements unique, within built-in capabilities; suite↔version bidirectional coverage; the signature list usable by at least one enabled version; validation modifies no input and allocates nothing.
• Policy boundary: describes preferences, promises no backend inclusion; session creation combines GroupAvailable/AEAD/identity/verification backends to build the actual path; the raw policy snapshot is immutable.
• KeySharePolicy: the local key-share selection mode (e.g. XTLS_KEY_SHARE_PREFER_GROUP) — affects which group the ClientHello carries, reducing HRR.
• Verifier mandate: without a Verify callback, at least one trust anchor is required; an empty store fails at creation; after the deep copy, the source store may be freed/modified.
• Three-layer decisions: default path (chain + purpose + name) / Verify callback (complete takeover, four-state decisions) / Policy callback (stacked after all defaults pass; views borrowed only during the callback).
• Protocol unbypassable: an accept decision cannot skip CertificateVerify and Finished — signatures and integrity are guaranteed by the protocol layer.
• Time injection: xtlsverifytimeproc provides one deterministic time for path and policy; omit for xrtNow().
• Concurrency: the verifier is immutable and reference-counted; Verify/Policy/Time callbacks may be invoked concurrently — they must not rely on thread-local mutable sharing.
• No implicit networking: no loading system roots, no downloading CRLs, no sending OCSP, no querying CT — the composition layer's and policy callback's business.
• Error wrapping: a callback returning false with an error set → XTLS_ERROR_VERIFY + cause; without an error → an explicit XERR_PERMISSION rejection.

Common Mistakes

/* assume configured means usable */
Policy.Ciphers = ChaChaFirst;
Policy.CipherCount = 1;
/* built with --feature lacking CHACHA20: every negotiation fails on the target */

/* verify capabilities before deployment: groups via GroupAvailable, suites per the build manifest */
if ( !xrtTlsGroupAvailable(XTLS_GROUP_X25519) ) {
	/* report the capability gap at startup, not as online connection failures */
}
/* run negotiation smoke tests in CI against the target build — policy and capability verified together */

static xtlsverifydecision myVerify(const xtlspeer* pPeer, ptr pCtx) {
	/* redoing signature verification: duplicate, error-prone, and already guaranteed */
	if ( !self_verify_signature(pPeer) ) { return XTLS_VERIFY_REJECT; }
	return XTLS_VERIFY_ACCEPT;
}

static xtlsverifydecision myVerify(const xtlspeer* pPeer, ptr pCtx) {
	/* trust decisions only: e.g. certificate pinning */
	if ( !pin_matches(pPeer /* leaf digest comparison */ ) ) {
		return XTLS_VERIFY_REJECT;
	}
	return XTLS_VERIFY_ACCEPT;   /* protocol checks guaranteed by XRT */
}

static bool myPolicy(const xtlsverifiedpeer* pPeer, ptr pCtx) {
	g_SavedCert = pPeer->Path[0];   /* saving a borrowed view: dangles on return */
	return true;
}

static bool myPolicy(const xtlsverifiedpeer* pPeer, ptr pCtx) {
	audit_log(pPeer);   /* read and record inside the callback */
	/* for long-term retention: copy the DER bytes here and manage the lifetime yourself */
	return true;
}

Programming Exercises

Summary