[Benoît Cortier (CBenoit)]

Devolutions Agent can obtain its own device identity from an authority such as Devolutions Server: a server-issued identity ID and an X.509 certificate for a P-256 key that never leaves the machine.
One reusable enrollment token, deployable with identity enroll - or the MSI's IDENTITY_ENROLLMENT_TOKEN property, enrolls any number of machines.
After enrolling, the agent renews its certificate on its own and keeps an authenticated, bidirectional gRPC channel to the authority, so the authority can push config changes and ask for a renewal; while no channel works, the agent checks in over HTTPS instead.

The agent-facing protocol is product-neutral and specified in docs/agent-identity/CONTRACT.agent-identity.md: the enrollment token, the HTTP API, an RFC 9421 request-signature profile, certificate rules, the gRPC channel and its proof-of-possession handshake, and renewal and root rotation.
Design decisions shared by every component are in docs/agent-identity/INTENT.agent-identity.md, and each crate has its own INTENT.md.
docs/agent-identity/test-vectors.json holds signature, channel-proof and CSR vectors for every implementation, checked independently by verify_vectors.py.

Structure:

• device-key: non-exportable P-256 device keys, in the Microsoft Software Key Storage Provider on Windows or as protected PKCS#8 files.
• agent-identity-httpsig: signs the agent's requests and channel openings with httpsig, under the contract's profile.
• agent-identity: tokens, pending-enrollment files, stored identities and their trust checks, schedules, CSRs and the HTTP client.
• agent-channel-proto and agent-channel-client: the channel schema, also published as the Devolutions.Agent.Channel NuGet package for .NET authorities, and the client that opens, authenticates and keeps the stream.
• devolutions-agent/src/identity: the identity enroll command, the Identity configuration section and the service task that enrolls, renews, checks in and runs the channel.
• package/AgentWindowsManaged: the MSI's enrollment property, and cleanup of identities and their machine keys on full uninstall.
• agent-identity-mock and agent-identity-conformance: a mock authority and a conformance tester that checks an authority (the mock or a real DVLS) and the agent against the contract; the testsuite runs both.
• http-client-proxy: proxy selection per URL, shared by identity requests, the channel and the agent's other outbound HTTP.

The operator guide is docs/agent-identity/README.md.
Agent Tunnel's existing enroll command and files are unchanged.

Issue: DGW-478

[Benoît Cortier (CBenoit)]

Implementation notes (Phase 1: contract and conformance suite)

Contents

• docs/agent-identity/CONTRACT.md v0.3 (approved), including the §10.1 clarification that extra_trusted_root is a PEM bundle.
• docs/agent-identity/test-vectors.json, produced by a throwaway generator that builds the signature bases by hand and signs deterministically (RFC 6979).
  It was cross-checked with Python cryptography and includes RFC 9421 Appendix B.2.4.
• agent-identity-channel-proto: tonic/prost code generated with vendored protoc, passed through prost_build::Config::protoc_executable rather than set_var.
  The same .proto builds the Devolutions.AgentIdentity.Channel NuGet package (net10.0, Google.Protobuf + Grpc.Core.Api).
  CI builds the package and publish-libraries.yml publishes it; the new package ID may need nuget.org trusted-publishing setup.
• agent-identity-mock: the conformance oracle.
  It verifies the RFC 9421 profile by hand with p256, without an RFC 9421 library, applying the §6 checks in contract order and committing each nonce only after its signature verifies.
  Authenticated handlers take an AuthenticatedDevice that only the verifier can construct.
  A unit test runs every entry of test-vectors.json through the server's own verifier.
• agent-identity-conformance: a custom harness that exits non-zero on failure.
  • Protocol tests act as a raw client, with their own signer written independently of the mock.
  • Agent tests spawn devolutions-agent run with DAGENT_CONFIG_PATH and stand in for the MSI through the pending file (Unix 0600; Windows DPAPI machine scope with a protected DACL).
  • Observation order: admin API first, agent files second, logs last.
  • Mock-only tests are skipped with --target dvls.
  • Rotation tests against DVLS need --disposable-dvls-target.
• The testsuite starts two mocks under /mock and runs the tester against them.

Current results (Windows, local)

• 47/47 protocol tests pass against the mock (about 15 s).
• Expected to fail until the agent implementation lands: the 22 a_* tests below, which need devolutions-agent identity support.
  a_file_backend_permissions is Unix-only and skips on Windows.
  Until then, the testsuite test agent_identity::conformance is red in CI; fmt, clippy, the existing tests and the protocol tests are green.
  • a_pending_file_enroll_success, a_pending_file_deleted_on_permanent_error, a_pending_file_kept_on_transient_error, a_token_never_logged
  • a_same_token_no_enrollment, a_same_token_rejected_identity_no_enrollment, a_different_token_replaces_identity, a_cli_identity_enroll_writes_pending_file
  • a_renewal_happy_path, a_renewal_lost_response_retried, a_channel_connected_and_metadata, a_make_before_break_on_renewal
  • a_request_renewal_connected, a_request_renewal_while_offline, a_reconnect_make_before_break, a_revocation_stops_agent
  • a_device_unknown_recorded, a_no_channel_when_absent, a_multi_authority, a_key_non_exportable
  • a_rotation_migrates_connected_agent, a_rotation_migrates_on_schedule

Dependencies

• The workspace resolves p256 0.14.0-rc.14 and ecdsa 0.17.0-rc.22, because ironrdp-connector 0.10 → sspi 0.21 → picky =7.0.0-rc.25 pins those release candidates.
  The mock and tester therefore pin p256 =0.14.0-rc.14.
• The agent's signing layer, in the next phase, holds httpsig at =0.0.24 for the same reason.
  httpsig is used only to build and sign the agent's own requests, never to parse incoming headers, because 0.0.24 can panic on malformed Signature-Input.
• Follow-up: once IronRDP releases on sspi 0.22 (picky rc.26), bump the picky pins to rc.26 and httpsig to 0.0.26, and drop the duplicate p256/ecdsa generation.

Suite decisions

• Enroll idempotence is checked before token expiry and exhaustion, so a lost response on a maxUses = 1 token can be retried.
• Chain checks:
  • The last chain element must equal a published root byte for byte.
  • Links are checked by name, and their signatures are verified for P-256 issuers.
  • Validity is checked at evaluation time.
  • There's no full RFC 5280 path validation (§4, invariant 10).
• Windows test cleanup deletes a machine key only when the key didn't exist before the test, its name matches the contract pattern, and its authority is the server-issued authority_id.

Review
Each suite task went through a coder ↔ reviewer loop using the repository code-review skill.
The tester task ended after 3 rounds (19 → 14 → 8 findings); a follow-up fix task addressed the remaining 8 and was approved in round 2.

Note

LLM-assisted content (no human feedback).

[Benoît Cortier (CBenoit)]

The head moved from 7a81460d to 15fc4910 to bind each enrollment to its token's URL and to follow the revised contract; CI run 40161741007 is green (50 jobs; skipped: Upload git-log output, OneDrive), after one re-run of the agent tunnel end-to-end test, whose Docker build hit a GitHub API rate limit while installing PowerShell.

• What changed, as the contract now states it:
  • Every certificate an authority issues for an identity carries a non-critical enrollment URL extension holding the enrolling token's u without trailing slashes, and the agent's CSR requests it with the URL it contacts.
  • An authority refuses an enrollment CSR that names no enrollment URL, or another one, with the permanent token_url_mismatch; the agent refuses a leaf that doesn't name its token's u as authority_url_mismatch. A server holding another authority's token can no longer relay a device's enrollment.
  • A token's u is ASCII only.
  • When a known authority moves to another base URL, the agent verifies the new chain with ecdsa-with-SHA256 over P-256 or ecdsa-with-SHA384 over P-384, never RSA.
  • Enrollment tokens are revoked, not deleted, carry no config, and report a status.
• The enrollment URL extension uses 1.3.6.1.4.1.32473.1.1, under the enterprise number RFC 5612 reserves for documentation; the contract moves it under Devolutions' own enterprise number before the feature is released.
• Conformance against the mock, locally on Windows at 15fc4910: file backend 188 PASS, 0 FAIL, 1 SKIP, 2 N/A.
• Test vectors: the CSR vectors are regenerated with Python cryptography and checked by verify_vectors.py; csr.valid now requests the enrollment URL, valid_with_empty_extension_request keeps its bytes, and a new expected_at field gives each CSR's outcome at enrollment and at renewal.
• Dependencies: p384 (P-384 verification) is a new direct dependency of agent-identity, and rsa a dev-dependency for a genuine RSA-signed test chain; both were already in Cargo.lock at the same versions, so no package is added.
• Known gap: the conformance suite can't yet drive the agent's chain check for a moved authority end to end; unit tests cover it.

New untested properties, one per UNTESTED: comment added:

• crates/agent-identity/src/client.rs: every enrollment response, first enrollments included, is refused when its leaf doesn't name the token's URL.
• devolutions-agent/src/identity/mod.rs: the enrollment CSR names the token's u without trailing slashes.
• devolutions-agent/src/identity/runner.rs: the renewal CSR names the identity's base URL.

Note

Human-tuned, LLM-assisted content.

[Benoît Cortier (CBenoit)]

The head moved from 15fc4910 to 7a09e162 to merge master, which adds a macOS leg to CI, and to fix the one test that failed on it; CI run 40195669577 is green (52 jobs; skipped: Upload git-log output, OneDrive).

• The macOS leg runs cargo test --workspace for aarch64-apple-darwin, so it now builds and tests agent-identity, agent-identity-mock, agent-identity-conformance, devolutions-agent and private-fs; agent_identity::conformance passes there.
• agent_identity::outer_timeout_kills_agent_group failed on macOS because it found an agent's session through the sess column of ps, which macOS fills with a kernel session pointer rather than a session ID. The test now lists PIDs with ps -e -o pid= and matches each with getsid, skipping PID 0, which getsid and kill read as the caller.

The untested-properties list from the earlier comment loses one line, because CI now compiles and tests the macOS code:

• CI compiles neither the agent crates nor private-fs for macOS; the macOS code was only type-checked locally with clippy for aarch64-apple-darwin.

These two still hold, because no test sets "Ignore ownership on this volume" or adds an extended ACL:

• crates/private-fs/src/macos.rs: a volume with "Ignore ownership on this volume" set is detected, and the boot volume isn't.
• crates/private-fs/src/macos.rs: a file with extended ACL entries is detected, and one without isn't.

Note

Human-tuned, LLM-assisted content.