#[non_exhaustive]pub enum FormatDefect {
Show 18 variants
Truncated,
BadMagic,
ExtTooLarge {
len: u32,
},
MalformedTlv,
UnknownCriticalTag {
tag: u16,
},
NotAKeyFile,
WrongKeyFileType,
MalformedPublicKey,
WrongKind {
kind: u8,
},
MalformedHeader,
MalformedPayloadStream,
OversizedHeader {
header_len: u32,
},
RecipientCountOutOfRange {
count: u16,
},
MalformedTypeName,
MalformedRecipientEntry,
RecipientFlagsReserved,
MalformedPrivateKey,
UnsupportedArchiveVersion {
version: u8,
},
}Expand description
Structural defects detected while parsing a FerroCrypt encrypted file
or key file. Carried inside CryptoError::InvalidFormat so format
failures can be pattern-matched without substring comparisons and
without parsing display text.
Each variant is the most granular structural class FORMAT.md §12
admits. Resource-cap exceedances are not FormatDefects — they
are top-level CryptoError variants in the *CapExceeded family
(e.g. FormatDefect::OversizedHeader is the structural max
violation; the local-cap counterpart is
CryptoError::HeaderLenCapExceeded).
This enum remains Copy: structural defects carry values that can be
pattern-matched without heap-allocated strings, including future variants.
Variants (Non-exhaustive)§
This enum is marked as non-exhaustive
Truncated
The input ended before the 12-byte .fcr prefix, the header the
prefix declares, or the 32-byte header MAC was complete, whether it
was cut short or a damaged header_len declares more than it holds.
Decryptor::open and decryption report an
input shorter than the prefix this way whatever bytes it holds, so it
need not be a FerroCrypt file; probe_recipient_mode
returns None for one without the magic instead. A key file or an
encrypted payload that ends early reports its own error, such as
CryptoError::PayloadTruncated.
BadMagic
Leading magic bytes do not match "FCR\0".
ExtTooLarge
ext_len in a .fcr header’s fixed section exceeds the reader’s
structural cap (EXT_LEN_MAX, 64 KiB). The shared TLV scanner
re-checks its cap on every region it is handed, but the FCA and
private.key regions are capped by their containing formats
first (the latter as Self::MalformedPrivateKey), so only the
.fcr fixed-section check is reachable from input. Carried as
u32 because the cap is 65_536, which exceeds u16::MAX.
MalformedTlv
A TLV entry in the extension region is malformed: bad ordering,
duplicate or reserved tag, incomplete entry header, or a value length
exceeding the region or configured per-value cap.
FORMAT.md §6.
UnknownCriticalTag
A TLV tag in the critical range (0x8001..=0xFFFF) is not
recognised by this release. Per FORMAT.md §6, unknown
critical TLV tags must cause file rejection. The message advises a
newer FerroCrypt, except for the critical test tag 0x8001, which §6
sets aside and no release will implement.
NotAKeyFile
Input is not recognized as a key file: a private key has incorrect magic bytes, or a public key file is not valid UTF-8.
WrongKeyFileType
A private-key operation was given a file that starts like a
public.key, with fcr1, or a public-key operation was given one with
the private.key signature (FORMAT.md §8 and §7.1). A private-key
operation given a FerroCrypt file of another kind reports
FormatDefect::WrongKind instead.
MalformedPublicKey
public.key text file violates the canonical grammar
(FORMAT.md §7.1): the file must contain the lowercase fcr1…
recipient string optionally followed by exactly one trailing
\n, OR the typed payload itself is structurally invalid.
Leading/trailing whitespace other than a single final LF, CRLF
line endings, extra blank lines, internal whitespace, header
length-field violations, and internal-checksum mismatch all
surface here. One case reports differently: a recipient string that
is ASCII, longer than the recipient-string cap, and within the
20,000-character ceiling is refused as
CryptoError::RecipientStringCapExceeded even when it also has
one of these defects, because FORMAT.md §7 applies the cap before
the Bech32 rules. In a public.key file that passes the file checks
of FORMAT.md §7.1, the string is the text left once one final LF
is removed.
WrongKind
A binary FerroCrypt artifact’s kind byte does not match the
expected value for this operation (e.g. a caller asked for an
encrypted .fcr but got a binary private.key, or vice versa).
FORMAT.md §3.1 and §8.
MalformedHeader
Structural defect in the header_fixed layout (non-zero
header_flags, ext_len over the structural cap, or length
fields that don’t sum to header_len). Distinct from
Self::OversizedHeader (header_len > 16 MiB structural max) and
Self::RecipientCountOutOfRange (recipient_count outside 1..=4096).
FORMAT.md §3.2.
MalformedPayloadStream
The authenticated payload stream violates the canonical chunk grammar
in FORMAT.md §5. Currently this means an empty final chunk following
one or more non-final chunks; an empty final chunk is valid only when
it is the stream’s sole chunk and represents empty plaintext.
OversizedHeader
header_len exceeds the structural maximum (HEADER_LEN_MAX = 16 MiB per FORMAT.md §3.1). Distinct from
CryptoError::HeaderLenCapExceeded which fires on the
caller-configured local cap (resource policy, not format
violation).
RecipientCountOutOfRange
recipient_count is outside the structural range 1..=4096
(FORMAT.md §3.2). Distinct from
CryptoError::RecipientCountCapExceeded which fires on the
caller-configured local cap.
MalformedTypeName
Recipient type_name does not satisfy the grammar in
FORMAT.md §3.3 (lowercase ASCII, allowed character set, no
leading/trailing punctuation, no .. or //).
MalformedRecipientEntry
Recipient entry framing is structurally invalid: 8-byte header
truncated, length fields out of range, declared entry size
exceeds the bytes available, or the recipient region’s per-entry
total accounting doesn’t add up to recipient_entries_len.
Also covers invalid native flags, body lengths, public-key encodings,
and all-zero X25519 shared secrets (FORMAT.md §4).
RecipientFlagsReserved
Recipient entry has reserved bits set in recipient_flags. Per
FORMAT.md §3.4, only bit 0 (the critical flag) is defined;
all other bits must be zero on the wire.
MalformedPrivateKey
A private.key violates its structural or authenticated consistency
rules: a short header, reserved version or flags, invalid lengths,
mismatched total size, or invalid native key material. After unlock,
this also covers a stored public key that does not match the secret.
Incorrect magic returns Self::NotAKeyFile instead.
UnsupportedArchiveVersion
Inner FCA archive version byte is a nonzero value this release
cannot read (zero is reserved and rejects as malformed). Distinct
from the outer .fcr / private.key version
rejection in UnsupportedVersion: this variant fires inside
the encrypted payload after the outer container is accepted, so
it is a structural defect of the inner archive grammar (FCA),
not of the outer FerroCrypt file. Per FORMAT.md §9 / §12.