Documentation
¶
Overview ¶
Package cryptodkim2 owns shared DKIM2 public-key validation and signature verification.
It is a lower leaf with no provider, message, policy-engine, or coordinator dependencies. Diagnostics are closed and never retain key or signature bytes.
Index ¶
- Constants
- func ClonePublicKey(material any) any
- func ExpectedSignatureBytes(validated any) (int, bool)
- func MLDSA44Available() error
- func MLDSA44SignerOptions() *mldsa.Options
- func MaxSignatureBytesFor(algorithm signature.Algorithm) int
- func MessageRepresentative(algorithm signature.Algorithm, input []byte) ([]byte, error)
- func ParseMLDSA44PublicKey(raw []byte) (*mldsa.PublicKey, error)
- func ParseSigningPublicKeySPKI(algorithm signature.Algorithm, spki []byte) (any, error)
- func PublicKeysEqual(left, right any) bool
- func SelfVerifyRepresentative(algorithm signature.Algorithm, material any, ...) error
- func SigningKeyBelowFloor(material any) (int, bool)
- func SignsInputDirectly(algorithm signature.Algorithm) bool
- func ValidRSAPublicKeyStructure(key *rsa.PublicKey) bool
- func ValidRepresentativeLength(algorithm signature.Algorithm, length int) bool
- func ValidatePublicKey(algorithm signature.Algorithm, material any, limits Limits) (any, error)
- func ValidateSignatureLength(algorithm signature.Algorithm, material any, length int, limits Limits) error
- func VerifyRepresentative(algorithm signature.Algorithm, material any, ...) error
- type Error
- type ErrorCode
- type Limits
Constants ¶
const ( // MLDSA44PublicKeyBytes is the exact FIPS 204 ML-DSA-44 public-key size. // Draft-09 Section 14.5: any other length is a malformed key. MLDSA44PublicKeyBytes = mldsa.MLDSA44PublicKeySize // MLDSA44SignatureBytes is the exact FIPS 204 ML-DSA-44 signature size // (3228 base64 characters, Draft-09 Section 3.4). MLDSA44SignatureBytes = mldsa.MLDSA44SignatureSize // MLDSA44Context is the Draft-09 Section 3.4 ML-DSA context string: the // five ASCII octets "DKIM2" without terminator, used for signing and // verifying. MLDSA44Context = "DKIM2" )
const ( // MinSigningRSABits is the local signing floor: new signing credentials // and loaded signing profiles require RSA moduli of at least 2048 bits // (Draft-09 Section 3.2 SHOULD made a local MUST). Verification keeps the // 1024 to 8192 bit bounds of Limits. MinSigningRSABits = 2048 )
Variables ¶
This section is empty.
Functions ¶
func ClonePublicKey ¶
ClonePublicKey returns detached supported key material or nil for unknown types.
func ExpectedSignatureBytes ¶
ExpectedSignatureBytes returns the exact decoded signature size one validated public key produces: the modulus size for RSA, 64 octets for Ed25519, and 2420 octets for ML-DSA-44. Other material reports false.
func MLDSA44Available ¶
func MLDSA44Available() error
MLDSA44Available reports ErrorCodeAlgorithmUnavailable when the cryptographic runtime cannot provide ML-DSA-44, for example a binary built against the FIPS 140-3 Go Cryptographic Module v1.0.0. Every surface that enables mldsa44 (verifier algorithm policy, signing credentials, stored public keys) calls it so the feature fails closed at construction instead of silently degrading.
func MLDSA44SignerOptions ¶
MLDSA44SignerOptions returns the signing options every mldsa44 signer uses: pure ML-DSA.Sign over the message representative with the Draft-09 Section 3.4 context string "DKIM2". A custody signer passes them to the hedged (randomized) crypto/mldsa PrivateKey.Sign; the deterministic variant is not used in production.
func MaxSignatureBytesFor ¶
MaxSignatureBytesFor returns the per-algorithm decoded signature bound: the modulus size of the largest admitted RSA key (1024 octets) for rsa-sha256, exactly 64 octets for ed25519-sha256, and exactly 2420 octets for mldsa44. Unknown algorithms have no bound and return zero.
func MessageRepresentative ¶
MessageRepresentative returns the exact bytes algorithm passes to its signing or verification primitive for one Section 12.8 signature input. It is the single representative owner for signer and verifier:
- rsa-sha256 and ed25519-sha256 (Sections 3.2 and 3.3) sign the 32-byte SHA-256 digest of the input;
- mldsa44 (Section 3.4) is pure ML-DSA: the input bytes are signed directly without being hashed first, so the representative is a detached copy of the complete input.
Unknown algorithms and an empty input fail closed.
func ParseMLDSA44PublicKey ¶
ParseMLDSA44PublicKey decodes the raw FIPS 204 ML-DSA-44 public-key encoding carried in DNS p= values and returns an immutable key. Any length other than exactly 1312 octets, or an encoding crypto/mldsa rejects, is ErrorCodeInvalidKey; an unavailable runtime is ErrorCodeAlgorithmUnavailable.
func ParseSigningPublicKeySPKI ¶
ParseSigningPublicKeySPKI decodes one canonical SubjectPublicKeyInfo for a signable algorithm: a crypto/x509 encoding that round-trips byte for byte for rsa-sha256, ed25519-sha256, and mldsa44 (OID 2.16.840.1.101.3.4.3.17). Unknown algorithms fail closed; a parsed key of another type or ML-DSA parameter set is rejected by ValidatePublicKey. It is the single SPKI owner for stored signing credentials.
func PublicKeysEqual ¶
PublicKeysEqual compares exact algorithm-specific public key material for every signable algorithm.
func SelfVerifyRepresentative ¶
func SelfVerifyRepresentative(algorithm signature.Algorithm, material any, representative, signatureBytes []byte, limits Limits) error
SelfVerifyRepresentative applies the same strict verification contract to a newly created signature.
func SigningKeyBelowFloor ¶
SigningKeyBelowFloor reports the modulus size of an RSA public key below MinSigningRSABits; other algorithms and keys at or above the floor report false.
func SignsInputDirectly ¶
SignsInputDirectly reports whether algorithm signs the complete Section 12.8 input instead of its SHA-256 digest: true only for pure mldsa44 (Section 3.4, "DKIM2 does not use HashML-DSA").
func ValidRSAPublicKeyStructure ¶
ValidRSAPublicKeyStructure reports whether key satisfies basic RFC 8017 shape invariants.
func ValidRepresentativeLength ¶
ValidRepresentativeLength reports whether length is a coherent message representative size for algorithm: exactly 32 octets (SHA-256) for rsa-sha256 and ed25519-sha256, and any nonempty Section 12.8 input for mldsa44. The caller bounds the input size before it is produced.
func ValidatePublicKey ¶
ValidatePublicKey validates algorithm matching and returns detached key material.
func ValidateSignatureLength ¶
func ValidateSignatureLength(algorithm signature.Algorithm, material any, length int, limits Limits) error
ValidateSignatureLength enforces algorithm-specific completed signature lengths.
func VerifyRepresentative ¶
func VerifyRepresentative(algorithm signature.Algorithm, material any, representative, signatureBytes []byte, limits Limits) error
VerifyRepresentative validates all inputs and verifies one signature over the algorithm's message representative of a Section 12.8 signature input (see MessageRepresentative): the 32-byte SHA-256 digest for rsa-sha256 and ed25519-sha256, and the complete input bytes for mldsa44, which uses pure ML-DSA.Verify (FIPS 204 Algorithm 3) with the context string "DKIM2".
Types ¶
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error is a cause-free secret-safe crypto failure.
type ErrorCode ¶
type ErrorCode string
ErrorCode identifies one closed cryptographic contract failure.
const ( // ErrorCodeInvalidOptions reports widened or incoherent crypto limits. ErrorCodeInvalidOptions ErrorCode = "invalid_options" // ErrorCodeUnsupportedAlgorithm reports an algorithm outside the closed contract. ErrorCodeUnsupportedAlgorithm ErrorCode = "unsupported_algorithm" // ErrorCodeWrongKeyType reports material with a mismatched Go key type. ErrorCodeWrongKeyType ErrorCode = "wrong_key_type" // ErrorCodeInvalidKey reports malformed public-key material. ErrorCodeInvalidKey ErrorCode = "invalid_key" // ErrorCodeKeyPolicyRejected reports structurally valid material outside fixed policy. ErrorCodeKeyPolicyRejected ErrorCode = "key_policy_rejected" // ErrorCodeInvalidDigestLength reports a message representative whose // length does not fit the algorithm (not a 32-byte SHA-256 digest for // rsa-sha256 and ed25519-sha256, or an empty mldsa44 input). ErrorCodeInvalidDigestLength ErrorCode = "invalid_digest_length" // ErrorCodeInvalidSignatureLength reports an algorithm-incoherent signature length. ErrorCodeInvalidSignatureLength ErrorCode = "invalid_signature_length" // ErrorCodeSignatureMismatch reports cryptographic verification failure. ErrorCodeSignatureMismatch ErrorCode = "signature_mismatch" // cryptographic runtime cannot provide, such as mldsa44 under the FIPS // 140-3 Go Cryptographic Module v1.0.0. ErrorCodeAlgorithmUnavailable ErrorCode = "algorithm_unavailable" )
func ErrorCodeOf ¶
ErrorCodeOf returns a closed crypto code without inspecting error text.
type Limits ¶
type Limits struct {
// MinRSABits is the narrowable lower RSA modulus bound.
MinRSABits int
// MaxRSABits is the fixed upper RSA modulus bound.
MaxRSABits int
// RequiredRSAExponent is the fixed RSA public exponent.
RequiredRSAExponent int
// MaxSignatureBytes is the narrowable decoded signature-byte ceiling
// across all algorithms. Narrowing it below an algorithm's exact size
// makes that algorithm unusable for the narrowed contract.
MaxSignatureBytes int
}
Limits contains narrowable crypto policy and fixed algorithm contracts.
func DefaultLimits ¶
func DefaultLimits() Limits
DefaultLimits returns the exact shared DKIM2 cryptographic limits.