Documentation
¶
Overview ¶
Package service coordinates bounded current-message verification and maps protocol-core facts into deterministic four-state internal results.
Service is the sole authentication boundary for policy projections. It validates the verify-owned target flag candidate against the authoritative selected target, upgrades current flags only after aggregate PASS, and seals complete pre-retention signature and DNS key metadata. Public fact-retention limits never reconstruct or narrow that policy evidence. Pre-target failures are sealed as fact-free unavailable projections; incoherent provenance fails closed. Service does not parse signature fields or raw f= values.
Index ¶
- Constants
- func SignatureSelectorCoherent(status SignatureStatus, reason Reason, selector string) bool
- type Algorithm
- type Assessment
- type CheckClass
- type CheckFact
- type Config
- type Custody
- type Error
- type ErrorCode
- type HistoricalState
- type Limits
- type Reason
- type ReplayProjection
- func (p ReplayProjection) Draft() string
- func (p ReplayProjection) Exploded() bool
- func (ReplayProjection) Format(state fmt.State, _ rune)
- func (ReplayProjection) GoString() string
- func (p ReplayProjection) OriginReplayDigest() ([32]byte, bool)
- func (p ReplayProjection) ReplayEligible() bool
- func (ReplayProjection) String() string
- func (p ReplayProjection) Valid() bool
- type Request
- type Result
- func (r Result) Checks() []CheckFact
- func (r Result) Custody() Custody
- func (r Result) Draft() string
- func (Result) Format(state fmt.State, _ rune)
- func (Result) GoString() string
- func (r Result) HistoricalContent() HistoricalState
- func (r Result) HistoricalSignatures() HistoricalState
- func (r Result) LocallyDisabledAlgorithm() bool
- func (r Result) PolicyProjection() policy.Projection
- func (r Result) PrimaryReason() Reason
- func (r Result) ReplayProjection() (ReplayProjection, bool)
- func (r Result) Scope() Scope
- func (r Result) SignatureSets() []SignatureSetFact
- func (r Result) State() State
- func (Result) String() string
- func (r Result) Target() Target
- func (r Result) VerifierProjection() (VerifierProjection, bool)
- type Scope
- type SignatureSetFact
- type SignatureStatus
- type State
- type Target
- type Verifier
- type VerifierHopFact
- type VerifierProjection
- func (p VerifierProjection) Binding() [32]byte
- func (p VerifierProjection) Draft() string
- func (VerifierProjection) Format(state fmt.State, _ rune)
- func (VerifierProjection) GoString() string
- func (p VerifierProjection) Hops() []VerifierHopFact
- func (p VerifierProjection) Schema() string
- func (VerifierProjection) String() string
- func (p VerifierProjection) Valid() bool
- type VerifierRecipeDescriptor
Constants ¶
const DraftIdentifier = "draft-ietf-dkim-dkim2-spec-09"
DraftIdentifier is the exact behavior baseline carried by service results.
Variables ¶
This section is empty.
Functions ¶
func SignatureSelectorCoherent ¶
func SignatureSelectorCoherent(status SignatureStatus, reason Reason, selector string) bool
SignatureSelectorCoherent is the single rule for per-set selector presence (Draft-09 Section 14.6 step 8): a passing set carries no selector, an internal-contract fact that names no parsed set carries none, and every other non-passing set (fail, permerror including key and unknown or disabled algorithm errors, temperror) carries its bounded parsed selector.
Types ¶
type Algorithm ¶
type Algorithm string
Algorithm identifies a bounded signature algorithm family.
const ( // AlgorithmRSASHA256 identifies RSA-SHA256. AlgorithmRSASHA256 Algorithm = "rsa-sha256" // AlgorithmEd25519SHA256 identifies Ed25519-SHA256. AlgorithmEd25519SHA256 Algorithm = "ed25519-sha256" // AlgorithmMLDSA44 identifies pure ML-DSA-44. AlgorithmMLDSA44 Algorithm = "mldsa44" // AlgorithmUnknown bounds unrecognized algorithm spellings. AlgorithmUnknown Algorithm = "unknown" )
type Assessment ¶
type Assessment struct {
// contains filtered or unexported fields
}
Assessment is one closed inbound applicability decision with an optional verification result.
func (Assessment) Applicable ¶
func (a Assessment) Applicable() bool
Applicable reports whether DKIM2 protocol fields required an actual verification.
func (Assessment) Valid ¶
func (a Assessment) Valid() bool
Valid reports whether the assessment is either not applicable or owns one valid result.
func (Assessment) Verification ¶
func (a Assessment) Verification() (Result, bool)
Verification returns the four-state result only when verification was applicable.
type CheckClass ¶
type CheckClass string
CheckClass identifies a bounded verification concern.
const ( // CheckMessage identifies raw RFC 5322 parsing. CheckMessage CheckClass = "message" // CheckProtocol identifies DKIM2 structural processing. CheckProtocol CheckClass = "protocol" // CheckBodyHash identifies current body hash verification. CheckBodyHash CheckClass = "body_hash" // CheckHeaderHash identifies current header hash verification. CheckHeaderHash CheckClass = "header_hash" // CheckSignature identifies cryptographic signature verification. CheckSignature CheckClass = "signature" // CheckKey identifies public-key validity and availability. CheckKey CheckClass = "key" // CheckTimestamp identifies timestamp policy evaluation. CheckTimestamp CheckClass = "timestamp" // CheckEnvelope identifies current SMTP envelope matching. CheckEnvelope CheckClass = "envelope" // CheckDomainAlignment identifies signing-domain alignment. CheckDomainAlignment CheckClass = "domain_alignment" // CheckNextDomain identifies structural next-domain processing. CheckNextDomain CheckClass = "next_domain" // CheckProvider identifies injected key-provider behavior. CheckProvider CheckClass = "provider" // CheckInternalContract identifies inconsistent internal facts. CheckInternalContract CheckClass = "internal_contract" )
func (CheckClass) Known ¶
func (c CheckClass) Known() bool
Known reports whether the check class belongs to the closed service vocabulary.
type CheckFact ¶
type CheckFact struct {
Class CheckClass
Reason Reason
}
CheckFact records one bounded check and reason.
type Config ¶
type Config struct {
Limits Limits
AlgorithmPolicy verify.AlgorithmPolicy
Clock verify.Clock
}
Config contains immutable verifier policies and limits.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns restrictive current-verification defaults.
type Custody ¶
type Custody string
Custody identifies bounded structural next-domain coverage.
const ( // CustodyNotEvaluated reports that earlier failure prevented reliable nd= detection. CustodyNotEvaluated Custody = "not_evaluated" // CustodyNotPresent reports successful extraction found no nd= link. CustodyNotPresent Custody = "not_present" // CustodyNDLinksEvaluated reports one or more intermediate links were evaluated. CustodyNDLinksEvaluated Custody = "nd_links_evaluated" // CustodyTerminalNDRequiresOOB reports terminal nd= requires unavailable OOB trust. CustodyTerminalNDRequiresOOB Custody = "terminal_nd_requires_oob" )
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error is a cause-free bounded service API error.
type HistoricalState ¶
type HistoricalState string
HistoricalState identifies one deliberately unevaluated historical dimension.
const ( // HistoricalNotEvaluated reports that historical reconstruction or crypto did not run. HistoricalNotEvaluated HistoricalState = "not_evaluated" // HistoricalComplete reports authenticated coverage through the origin. HistoricalComplete HistoricalState = "complete" // HistoricalPartial reports authenticated coverage with an explicit // unavailable body. Draft-09 Section 13 makes such a history FAIL // body_history_unavailable, so verification no longer produces it. HistoricalPartial HistoricalState = "partial" )
func (HistoricalState) Known ¶
func (s HistoricalState) Known() bool
Known reports whether historical state belongs to the closed service vocabulary.
type Limits ¶
type Limits struct {
MaxRawMessageBytes int
MaxRecipients int
MaxInstanceHashSets int
MaxSignatureSets int
MaxCheckFacts int
MaxSignatureFacts int
}
Limits bounds service input, extraction, and retained facts.
type Reason ¶
type Reason string
Reason identifies a bounded verification outcome reason.
const ( // ReasonNone reports no failure. ReasonNone Reason = "none" // ReasonInvalidRequest reports request API misuse. ReasonInvalidRequest Reason = "invalid_request" // ReasonLimitExceeded reports a configured resource limit. ReasonLimitExceeded Reason = "limit_exceeded" // ReasonMalformedMessage reports malformed RFC 5322 bytes. ReasonMalformedMessage Reason = "malformed_message" // ReasonMalformedProtocol reports malformed DKIM2 state. ReasonMalformedProtocol Reason = "malformed_protocol" // ReasonDuplicateHashAlgorithm reports any repeated h= algorithm name. ReasonDuplicateHashAlgorithm Reason = "duplicate_hash_algorithm" // ReasonInvalidRecipeJSON reports authenticated recipe text that is not // valid JSON or not a JSON object. ReasonInvalidRecipeJSON Reason = "invalid_recipe_json" // ReasonInvalidRecipe reports valid authenticated recipe JSON whose // schema, steps, or application are invalid (Draft-09 Section 14.2). ReasonInvalidRecipe Reason = "invalid_recipe" // ReasonFromNotAuthentic reports a From header field state that is not // Authentic for its responsible signature (Draft-09 Section 14.8). ReasonFromNotAuthentic Reason = "from_not_authentic" // ReasonFromSubdomainForbidden reports a From state that is Authentic // only through the upward match while the From domain's Domain Policy // Record carries the strict flag (Draft-09 Sections 3.8 and 14.8, FAIL). ReasonFromSubdomainForbidden Reason = "from_subdomain_forbidden" // ReasonDomainPolicyTemporary reports a Domain Policy Record that could // not be retrieved because of a temporary DNS failure (Section 3.8, // TEMPERROR). ReasonDomainPolicyTemporary Reason = "domain_policy_temporary" // ReasonDomainPolicyAmbiguous reports more than one Domain Policy Record // beginning with v=DKIM1 (Section 3.8, PERMERROR). ReasonDomainPolicyAmbiguous Reason = "domain_policy_ambiguous" // ReasonDomainPolicyInvalid reports a Domain Policy Record that begins // with v=DKIM1 but is not a valid tag-list, or a permanent lookup failure // (local interpretation D1, PERMERROR). ReasonDomainPolicyInvalid Reason = "domain_policy_invalid" // ReasonDuplicateSelector reports a repeated selector in one signature field. ReasonDuplicateSelector Reason = "duplicate_selector" // ReasonMissingProtocol reports absent required DKIM2 state. ReasonMissingProtocol Reason = "missing_protocol" // ReasonSequenceInvalid reports invalid signature or instance numbering. ReasonSequenceInvalid Reason = "sequence_invalid" // ReasonUnsupportedAlgorithm reports no checkable required algorithm. ReasonUnsupportedAlgorithm Reason = "unsupported_algorithm" // ReasonHashMismatch reports a supported digest mismatch. ReasonHashMismatch Reason = "hash_mismatch" // ReasonSignatureMismatch reports a supported signature mismatch. ReasonSignatureMismatch Reason = "signature_mismatch" // ReasonMissingKey reports absent public-key material. ReasonMissingKey Reason = "missing_key" // ReasonInvalidKey reports invalid public-key material. ReasonInvalidKey Reason = "invalid_key" // ReasonAmbiguousKey reports ambiguous public-key material. ReasonAmbiguousKey Reason = "ambiguous_key" // ReasonRevokedKey reports an explicitly revoked DNS public key. ReasonRevokedKey Reason = "revoked_key" // ReasonUnsupportedKeyType reports an unsupported DNS key type. ReasonUnsupportedKeyType Reason = "unsupported_key_type" // ReasonKeyAlgorithmMismatch reports disagreement between requested algorithm and DNS key type. ReasonKeyAlgorithmMismatch Reason = "key_algorithm_mismatch" // ReasonProviderTemporary reports typed retryable provider failure. ReasonProviderTemporary Reason = "provider_temporary" // ReasonProviderPermanent reports typed unrecoverable provider failure. ReasonProviderPermanent Reason = "provider_permanent" // ReasonProviderContract reports inconsistent provider behavior. ReasonProviderContract Reason = "provider_contract" // ReasonTimestampInvalid reports rejected timestamp state. ReasonTimestampInvalid Reason = "timestamp_invalid" // ReasonEnvelopeMismatch reports current SMTP envelope disagreement. ReasonEnvelopeMismatch Reason = "envelope_mismatch" // ReasonDomainAlignmentMismatch reports signing-domain misalignment. ReasonDomainAlignmentMismatch Reason = "domain_alignment_mismatch" // ReasonNextDomainMismatch reports structural next-domain disagreement. ReasonNextDomainMismatch Reason = "next_domain_mismatch" // ReasonCustodyMismatch reports a Chain of Custody adjacency failure: an // mf= or d= that does not match the previous signature's rt= (Draft-09 // Sections 7.1 and 14.4). ReasonCustodyMismatch Reason = "custody_mismatch" // ReasonOutOfBandRequired reports terminal nd= requiring OOB trust. ReasonOutOfBandRequired Reason = "out_of_band_required" // Recipe, so the message is not Fully Verified (Draft-09 Section 13). ReasonBodyHistoryUnavailable Reason = "body_history_unavailable" // ReasonInternalContract reports inconsistent internal facts. ReasonInternalContract Reason = "internal_contract" )
type ReplayProjection ¶
type ReplayProjection struct {
// contains filtered or unexported fields
}
ReplayProjection carries sealed replay facts across the trusted root boundary.
func (ReplayProjection) Draft ¶
func (p ReplayProjection) Draft() string
Draft returns the exact bounded behavior baseline.
func (ReplayProjection) Exploded ¶
func (p ReplayProjection) Exploded() bool
Exploded returns the authenticated complete-chain OR fact.
func (ReplayProjection) Format ¶
func (ReplayProjection) Format(state fmt.State, _ rune)
Format prevents every formatting verb from exposing authenticated digest bytes.
func (ReplayProjection) GoString ¶
func (ReplayProjection) GoString() string
GoString returns a constant representation without authenticated digest bytes.
func (ReplayProjection) OriginReplayDigest ¶
func (p ReplayProjection) OriginReplayDigest() ([32]byte, bool)
OriginReplayDigest returns the message-wide origin digest by value.
func (ReplayProjection) ReplayEligible ¶
func (p ReplayProjection) ReplayEligible() bool
ReplayEligible reports whether local replay policy applies to the message.
func (ReplayProjection) String ¶
func (ReplayProjection) String() string
String returns a constant representation without authenticated digest bytes.
func (ReplayProjection) Valid ¶
func (p ReplayProjection) Valid() bool
Valid reports whether the projection contains complete baseline facts.
type Request ¶
type Request struct {
// contains filtered or unexported fields
}
Request owns raw RFC 5322 and current SMTP envelope bytes.
func NewRequest ¶
NewRequest constructs an immutable internal service request.
func (Request) ForwardPaths ¶
ForwardPaths returns independent forward-path copies.
func (Request) RawMessage ¶
RawMessage returns an independent raw-message copy.
func (Request) ReversePath ¶
ReversePath returns an independent reverse-path copy.
type Result ¶
type Result struct {
// contains filtered or unexported fields
}
Result is an immutable internal current-verification outcome.
func (Result) HistoricalContent ¶
func (r Result) HistoricalContent() HistoricalState
HistoricalContent returns historical content coverage.
func (Result) HistoricalSignatures ¶
func (r Result) HistoricalSignatures() HistoricalState
HistoricalSignatures returns historical cryptographic coverage.
func (Result) LocallyDisabledAlgorithm ¶
LocallyDisabledAlgorithm reports whether the unsupported_algorithm outcome was decided by a locally disabled algorithm.
func (Result) PolicyProjection ¶
func (r Result) PolicyProjection() policy.Projection
PolicyProjection returns an independent internal facade-transfer clone.
func (Result) PrimaryReason ¶
PrimaryReason returns the highest-precedence bounded reason.
func (Result) ReplayProjection ¶
func (r Result) ReplayProjection() (ReplayProjection, bool)
ReplayProjection returns one independent sealed replay projection when present.
func (Result) SignatureSets ¶
func (r Result) SignatureSets() []SignatureSetFact
SignatureSets returns immutable bounded signature-set facts.
func (Result) VerifierProjection ¶
func (r Result) VerifierProjection() (VerifierProjection, bool)
VerifierProjection returns one independent sealed projection when present.
type SignatureSetFact ¶
type SignatureSetFact struct {
Algorithm Algorithm
Status SignatureStatus
Reason Reason
Selector string
}
SignatureSetFact records one bounded signature-set outcome.
type SignatureStatus ¶
type SignatureStatus string
SignatureStatus identifies one bounded signature-set outcome.
const ( // SignaturePASS reports one supported signature pass. SignaturePASS SignatureStatus = "pass" // SignatureFAIL reports one supported signature mismatch. SignatureFAIL SignatureStatus = "fail" // SignaturePERMERROR reports permanent set-level failure. SignaturePERMERROR SignatureStatus = "permerror" // SignatureTEMPERROR reports typed temporary provider failure. SignatureTEMPERROR SignatureStatus = "temperror" )
func (SignatureStatus) Known ¶
func (s SignatureStatus) Known() bool
Known reports whether signature status belongs to the closed service vocabulary.
type State ¶
type State string
State identifies one of the four current-verification outcomes.
const ( // StatePASS reports complete success for the declared authenticated scope. StatePASS State = "PASS" // StateFAIL reports completed verification of a message that is not a // Fully Verified DKIM2 Message (Draft-09 Section 14.1). StateFAIL State = "FAIL" // StatePERMERROR reports permanent malformed, missing, or ambiguous state. StatePERMERROR State = "PERMERROR" // StateTEMPERROR reports a typed temporary provider failure. StateTEMPERROR State = "TEMPERROR" )
func StateForReason ¶
StateForReason returns the Draft-09 Section 14.1 state that a result with this primary reason reports. The policy package owns the classification; an unknown or request-only reason is PERMERROR, which fails closed.
type Target ¶
type Target struct{ Sequence, Instance uint64 }
Target identifies the current signature and instance numbers.
type Verifier ¶
type Verifier struct {
// contains filtered or unexported fields
}
Verifier owns validated current-verification coordination dependencies.
func NewVerifier ¶
func NewVerifier(provider verify.KeyProvider, fromAuthorization verify.FromAuthorization, config Config) (Verifier, error)
NewVerifier constructs a service coordinator with immutable validated policy. fromAuthorization is the explicit Draft-09 Section 11.1 choice; a zero value fails construction closed.
func (Verifier) Assess ¶
Assess classifies complete protocol absence before starting DKIM2 verification.
type VerifierHopFact ¶
type VerifierHopFact struct {
SignerDomain string
Algorithms []string
CustodyTransition string
RecipeMode string
HistoryHeaderState string
HistoryBodyState string
BodyAvailability string
Recipe VerifierRecipeDescriptor
Binding [32]byte
Sequence uint64
MessageInstance uint64
Feedback bool
FeedHere bool
Exploded bool
}
VerifierHopFact stores one cloned authenticated chain record.
type VerifierProjection ¶
type VerifierProjection struct {
// contains filtered or unexported fields
}
VerifierProjection carries cloned sealed verifier evidence across the facade boundary.
func (VerifierProjection) Binding ¶
func (p VerifierProjection) Binding() [32]byte
Binding returns the verifier-owned complete projection binding.
func (VerifierProjection) Draft ¶
func (p VerifierProjection) Draft() string
Draft returns the exact verifier baseline.
func (VerifierProjection) Format ¶
func (VerifierProjection) Format(state fmt.State, _ rune)
Format prevents formatting verbs from exposing message-derived facts.
func (VerifierProjection) GoString ¶
func (VerifierProjection) GoString() string
GoString returns a constant representation without message-derived facts.
func (VerifierProjection) Hops ¶
func (p VerifierProjection) Hops() []VerifierHopFact
Hops returns detached ordered chain facts.
func (VerifierProjection) Schema ¶
func (p VerifierProjection) Schema() string
Schema returns the exact projection identity.
func (VerifierProjection) String ¶
func (VerifierProjection) String() string
String returns a constant representation without message-derived facts.
func (VerifierProjection) Valid ¶
func (p VerifierProjection) Valid() bool
Valid reports whether the projection was mapped from one sealed verifier-owned source.