tagvalue

package
v0.3.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 6, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func EncodeBase64

func EncodeBase64(input []byte) string

EncodeBase64 returns canonical padded RFC 4648 Base64 for immutable input.

func FoldBase64

func FoldBase64(encoded string) string

FoldBase64 inserts exact CRLF HTAB boundaries after each 64-character chunk.

func FoldedBase64Size

func FoldedBase64Size(decodedBytes int) (int, bool)

FoldedBase64Size returns the exact padded encoding and fold byte count.

func IsErrorCode

func IsErrorCode(err error, code ErrorCode) bool

IsErrorCode reports whether err contains a scanner Error with code.

func ParseTextstring

func ParseTextstring(input []byte) (string, bool)

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

func WalkBase64Chunks(decodedBytes int, visit func(first bool, offset, size int)) (int, bool)

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) Code

func (e *Error) Code() ErrorCode

Code returns the stable scanner error code.

func (*Error) Count

func (e *Error) Count() int

Count returns the observed resource count or size associated with the error.

func (*Error) Error

func (e *Error) Error() string

Error returns a bounded diagnostic without raw tag values.

func (*Error) Format

func (e *Error) Format(state fmt.State, _ rune)

Format routes every fmt form through the secret-safe diagnostic.

func (*Error) GoString

func (e *Error) GoString() string

GoString returns the same secret-safe diagnostic for Go-syntax formatting.

func (*Error) Is

func (e *Error) Is(target error) bool

Is matches scanner errors by code for errors.Is.

func (*Error) Limit

func (e *Error) Limit() int

Limit returns the configured resource limit associated with the error.

func (*Error) LimitName

func (e *Error) LimitName() string

LimitName returns the resource limit name for structured callers only.

func (*Error) Location

func (e *Error) Location() ErrorLocation

Location returns bounded scanner location metadata.

func (*Error) TagName

func (e *Error) TagName() string

TagName returns the allowlisted canonical tag name associated with the error.

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"
)

func (ErrorCode) Known

func (c ErrorCode) Known() bool

Known reports whether code belongs to the closed tag-value vocabulary.

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 Scan

func Scan(input []byte, known KnownTags, limits Limits) (Field, error)

Scan parses a DNS key-record tag list with case-sensitive names and FWS unfolding.

func ScanHeader

func ScanHeader(input []byte, known KnownTags, limits Limits) (Field, error)

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) Get

func (f Field) Get(name string) (Tag, bool)

Get returns the tag with exactly the requested name.

func (Field) Has

func (f Field) Has(name string) bool

Has reports whether a tag name is present under the field's matching mode.

func (Field) Len

func (f Field) Len() int

Len returns the number of scanned tag specifications.

func (Field) Tags

func (f Field) Tags() []Tag

Tags returns the scanned tags in field order.

func (Field) UnknownTags

func (f Field) UnknownTags() []Tag

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

func MustKnownTags(names ...string) KnownTags

MustKnownTags validates known tag names and panics on programmer error.

func NewKnownTags

func NewKnownTags(names ...string) (KnownTags, error)

NewKnownTags validates known tag names for exact scanner lookup.

func (KnownTags) Contains

func (k KnownTags) Contains(name string) bool

Contains reports whether name is an exact case-sensitive known tag.

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.

func (LimitName) Known

func (n LimitName) Known() bool

Known reports whether name belongs to the closed scanner limit 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.

func (Limits) Validate

func (l Limits) Validate() error

Validate rejects unsafe scanner limit values before scanning begins.

type Tag

type Tag struct {
	// contains filtered or unexported fields
}

Tag stores one immutable DKIM2 tag specification.

func (Tag) Known

func (t Tag) Known() bool

Known reports whether the tag name was present in the scanner allowlist.

func (Tag) Name

func (t Tag) Name() string

Name returns the exact validated tag name.

func (Tag) RawName

func (t Tag) RawName() string

RawName returns the validated tag identifier with its original ASCII spelling, which equals Name because neither scanner mode folds names.

func (Tag) Value

func (t Tag) Value() string

Value returns the case-sensitive parser-owned tag value.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL