Documentation
¶
Overview ¶
Package tagvalue owns shared DKIM2 tag-list scanning rules.
Both scanners implement the draft-ietf-dkim-dkim2-spec-09 Section 8 tag-list grammar: at least one tag-spec, an optional final semicolon, case-sensitive names and values, and no duplicated tags. Scan is the DNS key record mode and unfolds valid CRLF WSP FWS. ScanHeader is the Message-Instance and DKIM2-Signature mode: it receives raw-header unfolded input and rejects any uppercase tag name under Sections 9 and 10, including unknown extension names. It also owns DKIM2 base64string parsing: space and tab FWS are stripped, non-canonical pad bits fail, and encoded plus decoded byte views remain immutable after parsing. ParseBase64String requires standard RFC 4648 padding for protocol header fields. ParseOptionalPaddingBase64String is the DNS-02 mode; it accepts omitted terminal padding and returns canonical padded encoded bytes without relaxing alphabet, pad-bit, or resource limits.
Errors from this package are structured and bounded. They expose stable codes, operational classes, safe location and limit metadata, and only allowlisted tag names; they must not include raw DKIM2 field values, decoded recipient paths, nonces, hashes, signatures, or other message-derived secret material.
Index ¶
- func EncodeBase64(input []byte) string
- func FoldBase64(encoded string) string
- func FoldedBase64Size(decodedBytes int) (int, bool)
- func IsErrorCode(err error, code ErrorCode) bool
- func ParseTextstring(input []byte) (string, bool)
- func WalkBase64Chunks(decodedBytes int, visit func(first bool, offset, size int)) (int, bool)
- func WalkContinuedBase64Chunks(decodedBytes int, visit func(first bool, offset, size int)) (int, bool)
- type Base64String
- func (v Base64String) Decoded() []byte
- func (v Base64String) DecodedLen() int
- func (v Base64String) Encoded() []byte
- func (v Base64String) EncodedString() string
- func (v Base64String) Format(state fmt.State, _ rune)
- func (v Base64String) GoString() string
- func (v Base64String) Original() []byte
- func (v Base64String) String() string
- type Error
- func (e *Error) Class() ErrorClass
- func (e *Error) Code() ErrorCode
- func (e *Error) Count() int
- func (e *Error) Error() string
- func (e *Error) Format(state fmt.State, _ rune)
- func (e *Error) GoString() string
- func (e *Error) Is(target error) bool
- func (e *Error) Limit() int
- func (e *Error) LimitName() string
- func (e *Error) Location() ErrorLocation
- func (e *Error) TagName() string
- type ErrorClass
- type ErrorCode
- type ErrorDetails
- type ErrorLocation
- type Field
- type KnownTags
- type LimitName
- type Limits
- type Tag
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EncodeBase64 ¶
EncodeBase64 returns canonical padded RFC 4648 Base64 for immutable input.
func FoldBase64 ¶
FoldBase64 inserts exact CRLF HTAB boundaries after each 64-character chunk.
func FoldedBase64Size ¶
FoldedBase64Size returns the exact padded encoding and fold byte count.
func IsErrorCode ¶
IsErrorCode reports whether err contains a scanner Error with code.
func ParseTextstring ¶
ParseTextstring validates one already-trimmed Draft-09 Section 2.14 textstring value (1*ALPHADIGITD) and returns it unchanged. Textstring values such as hash algorithm, signature algorithm, and flag names are case-sensitive, so no case folding is applied: "SHA256" and "sha256" are different names.
func WalkBase64Chunks ¶
WalkBase64Chunks visits the exact canonical chunks for a decoded byte count.
func WalkContinuedBase64Chunks ¶
func WalkContinuedBase64Chunks(decodedBytes int, visit func(first bool, offset, size int)) (int, bool)
WalkContinuedBase64Chunks is WalkBase64Chunks for a value that continues an already started physical line: the first chunk holds exactly one character and every later chunk restarts the 64-character fold. A fold before the first character would begin the base64string with FWS (Draft-09 Section 2.14).
Types ¶
type Base64String ¶
type Base64String struct {
// contains filtered or unexported fields
}
Base64String stores immutable views of one canonical DKIM2 Base64 value.
func ParseBase64String ¶
func ParseBase64String(input []byte, limits Limits) (Base64String, error)
ParseBase64String parses a padded RFC 4648 DKIM2 base64string value. Draft-09 Section 2.14 admits FWS only between characters and before padding, so a value that begins or ends with FWS is rejected.
func ParseOptionalPaddingBase64String ¶
func ParseOptionalPaddingBase64String(input []byte, limits Limits) (Base64String, error)
ParseOptionalPaddingBase64String parses RFC 4648 Base64 with optional terminal padding for DNS key records, whose DNS-02 grammar keeps its own FWS rules.
func (Base64String) Decoded ¶
func (v Base64String) Decoded() []byte
Decoded returns the decoded parser-owned bytes.
func (Base64String) DecodedLen ¶
func (v Base64String) DecodedLen() int
DecodedLen returns the decoded byte length without exposing decoded bytes.
func (Base64String) Encoded ¶
func (v Base64String) Encoded() []byte
Encoded returns the canonical no-FWS padded base64 bytes.
func (Base64String) EncodedString ¶
func (v Base64String) EncodedString() string
EncodedString returns the canonical no-FWS padded base64 string.
func (Base64String) Format ¶
func (v Base64String) Format(state fmt.State, _ rune)
Format routes every fmt form through the secret-safe summary.
func (Base64String) GoString ¶
func (v Base64String) GoString() string
GoString returns the same secret-safe summary for Go-syntax formatting.
func (Base64String) Original ¶
func (v Base64String) Original() []byte
Original returns the parser-owned encoded bytes before FWS stripping.
func (Base64String) String ¶
func (v Base64String) String() string
String returns a secret-safe summary instead of encoded or decoded content.
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error is a typed, secret-safe DKIM2 tag-value scanner error.
func NewError ¶
func NewError(code ErrorCode, location ErrorLocation, details ErrorDetails) *Error
NewError constructs a bounded scanner error for classification.
func (*Error) Class ¶
func (e *Error) Class() ErrorClass
Class returns the stable operational error class.
func (*Error) Location ¶
func (e *Error) Location() ErrorLocation
Location returns bounded scanner location metadata.
type ErrorClass ¶
type ErrorClass string
ErrorClass groups tag-value scanner failures into stable operational classes.
const ( // ErrorClassMalformed classifies malformed DKIM2 tag-list syntax. ErrorClassMalformed ErrorClass = "malformed" // ErrorClassDuplicate classifies duplicate tag names. ErrorClassDuplicate ErrorClass = "duplicate" // ErrorClassLimit classifies resource-limit failures. ErrorClassLimit ErrorClass = "limit" // ErrorClassInvariant classifies invalid scanner configuration. ErrorClassInvariant ErrorClass = "invariant" )
func (ErrorClass) Known ¶
func (c ErrorClass) Known() bool
Known reports whether class belongs to the closed tag-value vocabulary.
type ErrorCode ¶
type ErrorCode string
ErrorCode identifies a bounded DKIM2 tag-value scanner failure.
const ( // ErrorCodeEmptyTagSpec reports an empty tag spec except for a final semicolon. ErrorCodeEmptyTagSpec ErrorCode = "empty_tag_spec" // ErrorCodeMissingEquals reports a tag spec without a name/value separator. ErrorCodeMissingEquals ErrorCode = "missing_equals" // ErrorCodeInvalidTagName reports a tag name outside DKIM2 tag syntax. ErrorCodeInvalidTagName ErrorCode = "invalid_tag_name" // ErrorCodeInvalidTagValue reports an extension value outside printable tag-value syntax. ErrorCodeInvalidTagValue ErrorCode = "invalid_tag_value" // ErrorCodeDuplicateTag reports a duplicate known or extension tag. ErrorCodeDuplicateTag ErrorCode = "duplicate_tag" // ErrorCodeLimitExceeded reports a configured scanner resource limit violation. ErrorCodeLimitExceeded ErrorCode = "limit_exceeded" // ErrorCodeInvalidOptions reports unsafe scanner options or known-tag input. ErrorCodeInvalidOptions ErrorCode = "invalid_options" // ErrorCodeInvalidBase64Alphabet reports bytes outside the standard alphabet. ErrorCodeInvalidBase64Alphabet ErrorCode = "invalid_base64_alphabet" // ErrorCodeInvalidBase64Padding reports misplaced or excessive padding. ErrorCodeInvalidBase64Padding ErrorCode = "invalid_base64_padding" // ErrorCodeInvalidBase64Length reports an empty or structurally invalid encoded length. ErrorCodeInvalidBase64Length ErrorCode = "invalid_base64_length" // ErrorCodeInvalidBase64PadBits reports non-zero RFC 4648 pad bits. ErrorCodeInvalidBase64PadBits ErrorCode = "invalid_base64_pad_bits" // ErrorCodeInvalidBase64Whitespace reports FWS before the first or after // the last base64string character (Draft-09 Section 2.14). ErrorCodeInvalidBase64Whitespace ErrorCode = "invalid_base64_whitespace" )
type ErrorDetails ¶
type ErrorDetails struct {
// Class records the stable operational class for the error.
Class ErrorClass
// LimitName records the resource limit identifier for structured callers.
LimitName LimitName
// Limit records the configured limit when relevant.
Limit int
// Count records the observed count or size when relevant.
Count int
// contains filtered or unexported fields
}
ErrorDetails carries bounded metadata for Error.
type ErrorLocation ¶
type ErrorLocation struct {
// Offset records a zero-based byte offset when known.
Offset int
// TagIndex records a zero-based tag-spec index when known.
TagIndex int
}
ErrorLocation identifies bounded tag-list context for a scanner error.
type Field ¶
type Field struct {
// contains filtered or unexported fields
}
Field stores an immutable DKIM2 tag-list scan result.
func ScanHeader ¶
ScanHeader parses an unfolded Message-Instance or DKIM2-Signature tag list. Draft-09 Section 8 makes the final semicolon optional, and Sections 9 and 10 require every tag name, including unknown extension names, to be lowercase; an uppercase name is a syntax error rather than an ignored tag.
func (Field) UnknownTags ¶
UnknownTags returns syntactically valid extension tags in field order.
type KnownTags ¶
type KnownTags struct {
// contains filtered or unexported fields
}
KnownTags records validated tag names for exact case-sensitive lookup.
func MustKnownTags ¶
MustKnownTags validates known tag names and panics on programmer error.
func NewKnownTags ¶
NewKnownTags validates known tag names for exact scanner lookup.
type LimitName ¶
type LimitName string
LimitName identifies one closed tag-value scanner limit.
const ( LimitNameMaxFieldValueBytes LimitName = "max_field_value_bytes" LimitNameMaxTags LimitName = "max_tags" LimitNameMaxTagNameBytes LimitName = "max_tag_name_bytes" LimitNameMaxTagValueBytes LimitName = "max_tag_value_bytes" LimitNameMaxBase64DecodedBytes LimitName = "max_base64_decoded_bytes" )
Tag-value limit names form the closed scanner resource vocabulary.
type Limits ¶
type Limits struct {
// MaxFieldValueBytes bounds one unfolded DKIM2 header field value.
MaxFieldValueBytes int
// MaxTags bounds the number of tag specifications in one field.
MaxTags int
// MaxTagNameBytes bounds one tag identifier before canonicalization.
MaxTagNameBytes int
// MaxTagValueBytes bounds one tag value before tag-specific decoding.
MaxTagValueBytes int
// MaxBase64DecodedBytes bounds decoded parser-owned base64 containers.
MaxBase64DecodedBytes int
}
Limits contains fail-closed DKIM2 tag-value scanner resource settings.
func DefaultLimits ¶
func DefaultLimits() Limits
DefaultLimits returns the restrictive tag scanner defaults.
type Tag ¶
type Tag struct {
// contains filtered or unexported fields
}
Tag stores one immutable DKIM2 tag specification.