Documentation
¶
Overview ¶
Package cacpiv extends mtlsx.Principal with DOD CAC and federal PIV identity extraction per FIPS 201-3 and the X.509 Certificate Policy for the U.S. Federal PKI Common Policy Framework.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrRequirePerson is returned when the route demanded a PE // (Person Entity) but the certificate is a CardAuth, NPE, or // unknown classification. ErrRequirePerson = errors.New("cacpiv: route requires PE certificate") // ErrRequiredPolicyOID is returned when none of the required // PolicyOIDs are present on the certificate. ErrRequiredPolicyOID = errors.New("cacpiv: required certificate policy OID absent") // ErrUnknownClassification is returned when WithRejectUnknownClassification // is set and the certificate cannot be classified into any known PE/NPE // or CardAuth category. ErrUnknownClassification = errors.New("cacpiv: certificate classification unknown") )
Errors returned by Adapter.Apply.
Functions ¶
func ExtractEDIPI ¶
func ExtractEDIPI(c *x509.Certificate) string
ExtractEDIPI returns the EDIPI (DOD ID Number) found in the certificate.
A-S8 hardening (2026-05-28): the prior implementation ran a loose `\b\d{10}\b` regex over CommonName / UPN / email local-part, which could false-positive on any fortuitous 10-digit substring (e.g. a phone number inside an OU). Extraction now anchors to the documented EDIPI position in each source:
Subject CommonName: per DOD CAC convention "LAST.FIRST.M.EDIPI", EDIPI is the FINAL dot-separated component. Only that component is checked, and it must be EXACTLY ten ASCII digits.
SAN UPN otherName (typically EDIPI@mil): EDIPI is the entire local-part to the left of "@". Only that local-part is checked, same strict ten-digit rule. Uses mtlsx.ExtractUPN to read the OID-1.3.6.1.4.1.311.20.2.3 otherName, not raw DNS/email SANs.
SAN rfc822Name (email): EDIPI is the local-part to the left of "@". Same strict rule.
Returns "" when no source yields a strict ten-digit EDIPI match.
func ExtractEDIPIFromString ¶
ExtractEDIPIFromString is kept for tests and external callers that have already isolated a candidate string (e.g. via custom OID extraction). It applies the same strict ten-digit rule rather than the prior regex-anywhere scan.
A bare ten-digit string returns that string. Strings containing any other character (including leading/trailing whitespace) return "". Callers that want to feed a CommonName or full email should use ExtractEDIPI directly so the per-source anchoring runs first.
func PolicyOIDByName ¶
func PolicyOIDByName(name string) (asn1.ObjectIdentifier, bool)
PolicyOIDByName looks up an OID by its IANA / DOD label.
func PolicyOIDName ¶
func PolicyOIDName(oid asn1.ObjectIdentifier) (string, bool)
PolicyOIDName looks up the label for a known OID. Returns "" if unknown.
Types ¶
type Adapter ¶
type Adapter struct {
// contains filtered or unexported fields
}
Adapter post-processes mtlsx.Principal with CAC/PIV identity fields. Construct via New(opts...) and pass Adapter.Apply as mtlsx.VerifierConfig.PrincipalAdapter.
type Classification ¶
type Classification int
Classification labels for CAC/PIV certificates by certificate policy OID.
const ( ClassUnknown Classification = iota ClassPersonPIVAuth // federal PIV authentication cert ClassPersonCAC // DOD CAC (mediumHardware family) ClassCardAuthentication // PIV card-auth cert (uses PIN, no signing) ClassNonPersonEntity // DOD NPE / device cert )
func Classify ¶
func Classify(c *x509.Certificate) Classification
Classify inspects the certificate's policy OIDs and returns the most specific classification. The order of checks is deliberate: PIV Auth before CAC, CAC before NPE, NPE before CardAuth — because some DOD certs carry multiple policies and we want the strictest match first.
func (Classification) IsPerson ¶
func (c Classification) IsPerson() bool
IsPerson reports whether c represents a human cardholder (PE). PE endpoints (typical workforce / mission users) should refuse Card Authentication and NPE classifications.
func (Classification) String ¶
func (c Classification) String() string
String renders the canonical kebab-case label used by Principal.Classification.
type Option ¶
type Option func(*Adapter)
Option mutates an Adapter at construction.
func WithRejectUnknownClassification ¶
WithRejectUnknownClassification rejects certificates that cannot be classified into any of the known PE/NPE/CardAuth categories.
func WithRequirePerson ¶
WithRequirePerson rejects any certificate not classified as PE (PIV Auth or CAC). Use for human-only endpoints.
func WithRequiredPolicyOIDs ¶
func WithRequiredPolicyOIDs(oids []asn1.ObjectIdentifier) Option
WithRequiredPolicyOIDs requires at least one of the listed OIDs in the certificate's PolicyIdentifiers. Empty slice disables the check.
type PolicyOID ¶
type PolicyOID struct {
Name string
OID asn1.ObjectIdentifier
}
PolicyOID captures one named certificate policy used by federal/DOD PKIs.
func PolicyOIDs ¶
func PolicyOIDs() []PolicyOID
PolicyOIDs returns a copy of the catalog for callers that need to walk it.
Source Files