mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-14 15:58:56 +00:00
feat(scep-intune): parser + validator for Microsoft Intune Connector challenge format
Phase 7 of the SCEP RFC 8894 + Intune master bundle. Adds the
internal/scep/intune package that validates Microsoft Intune Certificate
Connector signed challenges embedded in SCEP CSR challengePassword
attributes. This is the parsing/validation foundation; Phase 8 wires it
into the SCEP service dispatcher.
What's included:
* doc.go — package architecture (Intune cloud → Connector → certctl
SCEP server) + 'what this package is NOT' guard rails. We do NOT
implement full JOSE: no JKU / kid / x5c trust, no JWKS fetch.
Trust anchor is operator-supplied at startup and pinned. The
package does NOT call Microsoft's API directly — the Connector
already did that; we validate its signed attestation.
* trust_anchor.go — LoadTrustAnchor(path) reads a PEM bundle of
Intune Connector signing certs. Skips non-CERTIFICATE PEM blocks
(operators sometimes paste chains with the priv key by mistake).
Rejects empty bundles + expired certs at startup with an
operator-actionable message including the cert subject. SIGHUP
reload lands in Phase 8.5; today it's load-once-at-boot.
* claim.go — ChallengeClaim struct + DeviceMatchesCSR helper.
Set-equality semantics for SAN-DNS/SAN-RFC822/SAN-UPN: the CSR
must carry EXACTLY the claim's elements, no extras and no missing.
Empty claim slice = no constraint on that dimension.
Per-dimension typed errors (ErrClaimCNMismatch /
ErrClaimSANDNSMismatch / ErrClaimSANRFC822Mismatch /
ErrClaimSANUPNMismatch) so audit logs surface the failure
dimension without string-matching. extractUPNSans is stubbed to
return nil with documented fail-closed behavior — non-empty UPN
claims fail the equalSets check (correct behavior; the rare deploy
that pins UPN SANs hot-fixes the ASN.1 walker per the inline
comment).
* replay.go — ReplayCache: bounded in-memory cache of seen nonces
with TTL. Sized for 100,000 entries (60-min Connector validity ×
25 RPS Intune fleet steady-state ≈ 90,000 challenges/hour with
headroom). sync.Map for concurrent read/write; janitor goroutine
wakes every TTL/4 to evict expired entries; at-cap O(N)
oldest-eviction (rarely fires; janitor keeps the cache below
cap). Redis-backed variant deferred to V3-Pro.
* challenge.go — the load-bearing piece:
- ParseChallenge(raw) splits the JWT-like compact serialization
into header/payload/signature and base64url-decodes each.
Tolerates both padded + unpadded encodings (some Connector
builds emit padded; RFC 7515 §2 says unpadded; we accept both).
Validates the header parses as JSON before returning so the
malformed-signal lands earlier in the pipeline.
- ValidateChallenge(raw, trust, expectedAudience, now):
1. ParseChallenge
2. JWS signature verify over (segment0 || '.' || segment1)
— re-derived from the raw on-wire bytes, NOT
re-base64-encoded, per RFC 7515 §3.1 (re-encoding could
produce a byte-different input than what was signed)
3. Signature alg dispatch:
RS256: rsa.VerifyPKCS1v15(SHA-256)
ES256: tries fixed-width r||s (JOSE-canonical) first,
falls back to ASN.1 DER (older Connectors)
alg=none: explicit reject with audit-log-friendly
message (RFC 7515 §3.6 attack vector)
HS*/PS*: rejected as 'unsupported alg' (no shared
secret in our threat model)
4. Version-detection prelude (versionedChallenge struct +
versionUnmarshalers map). Today's format is v1 (no
explicit version field; absence IS the v1 signal). Adding
v2 = adding a parser + a registration line; v1 path stays
untouched. Defends against the inevitable Microsoft format
change at ~30 LoC + 2 tests cost vs. a P0 incident.
5. Time bounds (iat / exp); audience pin (skipped when
expectedAudience == "").
Replay protection is the CALLER's job (handler glues parser +
cache; validator stays stateless + testable).
* Typed errors: ErrChallengeMalformed / ErrChallengeSignature /
ErrChallengeExpired / ErrChallengeNotYetValid /
ErrChallengeWrongAudience / ErrChallengeReplay /
ErrChallengeUnknownVersion. errors.Is-friendly so the handler
can audit failure dimension.
Tests (94.8% coverage):
* challenge_test.go (18 tests): happy-path RS256 + ES256
fixed-width + ES256 DER; TamperedSignature; TamperedPayload;
Expired; NotYetValid; WrongAudience; EmptyExpectedAudience
disables check; RotatedTrustAnchor; EmptyTrustBundle;
AlgNoneRejected; UnsupportedAlg (HS256); MissingAlg;
VersionV1ExplicitOK; VersionUnknownRejected;
MixedTrustBundle iter (skip key-type mismatches without
surfacing as Signature err); NonJSONPayloadButValidSignature;
Malformed cases (empty, missing dots, bad base64, non-JSON
header — 9 sub-cases); PaddedBase64Tolerated.
* claim_test.go (13 tests): per-dimension matching across CN +
SAN-DNS + SAN-RFC822 + SAN-UPN; nil guards; case-insensitive DNS
(RFC 4343); dedupe set-equality; empty claim = no constraint;
UPN stub canary; normaliseSet edge cases; equalSets length
mismatch.
* replay_test.go (11 tests): first-fresh; duplicate-rejected;
past-TTL-fresh; Sweep-evicts-expired; empty-nonce
short-circuits; at-cap LRU eviction; default-cap=100k;
Close-idempotent; TTL=0 disables janitor; concurrent-race-free
(50 goroutines × 200 inserts); empty-nonce twice is fresh both
times (we don't cache empties).
* trust_anchor_test.go: HappyPath single + multi cert; SkipsNonCertBlocks
(priv key + cert mix); EmptyBundleRejected; OnlyKeyBlocksRejected;
ExpiredCertRejected (with subject CN in error); MalformedCertRejected;
LoadTrustAnchor disk + EmptyPath + MissingFile.
* fuzz_test.go: FuzzParseChallenge with seed corpus covering both
the well-formed and the obvious-malformed shapes. Survived 187k
execs in 21s without panic on the local burst; CI runs 5 min.
Verification:
* gofmt -l ./internal/scep/intune: clean
* go vet ./internal/scep/intune/...: clean
* staticcheck ./internal/scep/intune/...: clean
* go test -count=1 -cover ./internal/scep/intune/...: 94.8%
(target was ≥85%)
* go vet ./internal/... ./cmd/...: clean (no rest-of-repo regressions)
* No new CERTCTL_* env vars (those land in Phase 8 with the
config gate); G-3 docs-drift CI guard not triggered.
* No new HTTP routes; openapi-parity guard not triggered.
Phase 8 will:
- Add SCEPProfileConfig.Intune* env vars + preflight gate
- Wire the validator into the SCEP service dispatcher
(Intune-shaped challenges → validator; static → existing path)
- Trust-anchor SIGHUP reload mirroring cmd/server/tls.go::watchSIGHUP
- Per-claim rate limit + audit metrics
Refs: cowork/scep-rfc8894-intune-master-prompt.md::Phase 7
cowork/scep-rfc8894-intune/progress.md
This commit is contained in:
shankar0123
@@ -0,0 +1,162 @@
|
||||
package intune
|
||||
|
||||
import (
|
||||
"crypto/x509"
|
||||
"errors"
|
||||
"fmt"
|
||||
"sort"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// ChallengeClaim is the parsed payload of an Intune dynamic challenge.
|
||||
//
|
||||
// SCEP RFC 8894 + Intune master bundle Phase 7.3.
|
||||
//
|
||||
// Fields documented from Microsoft's Connector source traces +
|
||||
// community implementations (smallstep/step-ca and HashiCorp Vault's
|
||||
// Intune integrations both reverse-engineered the same format). The
|
||||
// JSON tags match what the Connector emits today (v1 format); a v2
|
||||
// format would land alongside via the version-detection dispatcher
|
||||
// in challenge.go.
|
||||
//
|
||||
// Set-equality semantics: the SAN slices are normalised (sorted,
|
||||
// de-duped) before comparison so Microsoft's Connector emitting in a
|
||||
// non-deterministic order doesn't break DeviceMatchesCSR.
|
||||
type ChallengeClaim struct {
|
||||
Issuer string `json:"iss,omitempty"` // Connector identity (installation GUID typical)
|
||||
Subject string `json:"sub,omitempty"` // device GUID or user UPN
|
||||
Audience string `json:"aud,omitempty"` // expected SCEP endpoint URL (replay protection)
|
||||
IssuedAt time.Time `json:"-"` // populated by claim unmarshaler from "iat" Unix seconds
|
||||
ExpiresAt time.Time `json:"-"` // populated by claim unmarshaler from "exp" Unix seconds
|
||||
Nonce string `json:"nonce,omitempty"` // replay-protection token; opaque
|
||||
DeviceName string `json:"device_name,omitempty"` // expected CSR CommonName
|
||||
SANDNS []string `json:"san_dns,omitempty"` // expected SAN DNS names
|
||||
SANRFC822 []string `json:"san_rfc822,omitempty"` // expected SAN email addresses (user certs)
|
||||
SANUPN []string `json:"san_upn,omitempty"` // expected SAN userPrincipalName
|
||||
}
|
||||
|
||||
// Typed claim-mismatch errors so the caller can audit the specific
|
||||
// failure dimension without string-matching on error messages.
|
||||
var (
|
||||
ErrClaimCNMismatch = errors.New("intune claim: device_name does not match CSR CommonName")
|
||||
ErrClaimSANDNSMismatch = errors.New("intune claim: SAN DNS set does not match CSR")
|
||||
ErrClaimSANRFC822Mismatch = errors.New("intune claim: SAN RFC822 (email) set does not match CSR")
|
||||
ErrClaimSANUPNMismatch = errors.New("intune claim: SAN UPN (userPrincipalName) set does not match CSR")
|
||||
)
|
||||
|
||||
// DeviceMatchesCSR returns nil if the CSR's CN and SANs match the
|
||||
// claim's expected values. Returns a typed error otherwise so the
|
||||
// caller can audit the specific mismatch.
|
||||
//
|
||||
// Set-equality semantics: if the claim says
|
||||
// SANDNS=["a.example.com","b.example.com"] and the CSR has only
|
||||
// "a.example.com", that's a mismatch — the operator's Intune profile
|
||||
// was misconfigured or the CSR was tampered with. Both are "fail
|
||||
// closed" cases.
|
||||
//
|
||||
// Empty claim slices = no constraint on that dimension. So a claim
|
||||
// with SANDNS=nil + a CSR with DNS SANs is OK (Intune didn't pin DNS,
|
||||
// the CSR can carry whatever). A claim with SANDNS=["x"] + a CSR
|
||||
// with no DNS SANs is a mismatch (Intune pinned x, CSR doesn't have
|
||||
// it).
|
||||
func (c *ChallengeClaim) DeviceMatchesCSR(csr *x509.CertificateRequest) error {
|
||||
if c == nil {
|
||||
return errors.New("intune claim: nil claim")
|
||||
}
|
||||
if csr == nil {
|
||||
return errors.New("intune claim: nil CSR")
|
||||
}
|
||||
|
||||
// CN is straight equality. Empty claim CN = no constraint.
|
||||
if c.DeviceName != "" && c.DeviceName != csr.Subject.CommonName {
|
||||
return fmt.Errorf("%w: claim=%q csr=%q", ErrClaimCNMismatch, c.DeviceName, csr.Subject.CommonName)
|
||||
}
|
||||
|
||||
// SAN sets — set-equality means the SCEP CSR carries EXACTLY the
|
||||
// claim's elements, no extras and no missing. Normalising via
|
||||
// sorted lower-case slices makes the compare order-independent.
|
||||
if len(c.SANDNS) > 0 {
|
||||
got := normaliseSet(csr.DNSNames)
|
||||
want := normaliseSet(c.SANDNS)
|
||||
if !equalSets(got, want) {
|
||||
return fmt.Errorf("%w: claim=%v csr=%v", ErrClaimSANDNSMismatch, want, got)
|
||||
}
|
||||
}
|
||||
if len(c.SANRFC822) > 0 {
|
||||
got := normaliseSet(csr.EmailAddresses)
|
||||
want := normaliseSet(c.SANRFC822)
|
||||
if !equalSets(got, want) {
|
||||
return fmt.Errorf("%w: claim=%v csr=%v", ErrClaimSANRFC822Mismatch, want, got)
|
||||
}
|
||||
}
|
||||
if len(c.SANUPN) > 0 {
|
||||
// UPN SANs ride otherName extensions per RFC 4985 §1.1; Go's
|
||||
// stdlib doesn't surface them as a typed slice. Walk the raw
|
||||
// extensions if present. Most Intune deploys use SAN-RFC822
|
||||
// (email) for user certs rather than SAN-UPN, so this branch is
|
||||
// uncommon but pinned for correctness.
|
||||
got := normaliseSet(extractUPNSans(csr))
|
||||
want := normaliseSet(c.SANUPN)
|
||||
if !equalSets(got, want) {
|
||||
return fmt.Errorf("%w: claim=%v csr=%v", ErrClaimSANUPNMismatch, want, got)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// normaliseSet returns a sorted, lowercased, de-duplicated copy of s.
|
||||
// Lowercase because DNS / email comparison is case-insensitive (DNS
|
||||
// per RFC 4343, email local-part is case-sensitive per RFC 5321 but
|
||||
// Microsoft + most TLS stacks treat it case-insensitively for SAN
|
||||
// comparison). De-dup so a CSR with ["a","a"] matches a claim with
|
||||
// ["a"] — the cert's effective SAN set is what we're comparing, not
|
||||
// the multiset.
|
||||
func normaliseSet(s []string) []string {
|
||||
seen := map[string]struct{}{}
|
||||
out := make([]string, 0, len(s))
|
||||
for _, v := range s {
|
||||
v = strings.ToLower(strings.TrimSpace(v))
|
||||
if v == "" {
|
||||
continue
|
||||
}
|
||||
if _, ok := seen[v]; ok {
|
||||
continue
|
||||
}
|
||||
seen[v] = struct{}{}
|
||||
out = append(out, v)
|
||||
}
|
||||
sort.Strings(out)
|
||||
return out
|
||||
}
|
||||
|
||||
func equalSets(a, b []string) bool {
|
||||
if len(a) != len(b) {
|
||||
return false
|
||||
}
|
||||
for i := range a {
|
||||
if a[i] != b[i] {
|
||||
return false
|
||||
}
|
||||
}
|
||||
return true
|
||||
}
|
||||
|
||||
// extractUPNSans walks a CSR's raw extensions for SAN entries with the
|
||||
// otherName form carrying the id-ms-san-upn OID (1.3.6.1.4.1.311.20.2.3).
|
||||
// Returns the decoded UTF-8 string values. Returns empty slice when no
|
||||
// UPN SANs are present (the common case).
|
||||
//
|
||||
// Implementation note: Go's stdlib doesn't decode UPN SANs; we'd have
|
||||
// to walk the SubjectAltName extension's raw value as ASN.1 SEQUENCE OF
|
||||
// GeneralName, find the [0] otherName tags, parse each as
|
||||
// {OID, [0] EXPLICIT ANY}, match the OID, and decode the EXPLICIT value
|
||||
// as a UTF8String. That's ~50 LoC of ASN.1 fiddling. For Phase 7 v1 we
|
||||
// punt on it: returning an empty slice means SANUPN claims with non-
|
||||
// empty values fail the equalSets check below — which is the correct
|
||||
// fail-closed behavior for the rare deploy that pins UPN SANs but
|
||||
// hasn't audited the wire format. If/when an operator actually needs
|
||||
// SAN-UPN matching, hot-fix this function with the ASN.1 walker.
|
||||
func extractUPNSans(_ *x509.CertificateRequest) []string {
|
||||
return nil
|
||||
}
|
||||
Reference in New Issue
Block a user