Enum KeystoreError 

pub enum KeystoreError {
    Backend(Arc<Error>),
    UnknownMagic {
        saw: [u8; 6],
    },
    UnsupportedFormat {
        found: u16,
    },
    SchemeMismatch {
        expected: u16,
        expected_name: &'static str,
        found: u16,
    },
    CrcMismatch {
        stored: u32,
        computed: u32,
    },
    DecryptFailed,
    InvalidKdfParams(&'static str),
    UnsupportedKdf(u8),
    UnsupportedCipher(u8),
    AlreadyExists(String),
    InvalidPlaintext {
        expected: usize,
        got: usize,
    },
    InvalidSeed(String),
    Truncated {
        claimed: usize,
        available: usize,
    },
}

Errors produced by keystore operations.

The enum is Clone so errors can be fanned out through broadcast channels or bubbled through async traits. The only non-Clone primitive (std::io::Error) is wrapped in Arc to preserve clonability.

Variants

Backend(Arc<Error>)

An underlying backend I/O operation failed.

This is the catch-all for filesystem errors from crate::FileBackend as well as any future backend (OS keyring / HSM). The wrapped std::io::Error preserves the original ErrorKind for callers who want to distinguish e.g. NotFound from PermissionDenied.

UnknownMagic

The file’s magic prefix did not match any known scheme.

First 6 bytes of a keystore file carry DIGVK1, DIGLW1, etc. If the caller pointed at a non-keystore file (or a future-version file this build doesn’t understand), decode fails here before any cryptography.

Fields

saw: [u8; 6]

The magic bytes that were actually read.

UnsupportedFormat

The file’s format version is newer or older than this library understands.

Format version is stored as a big-endian u16 right after the magic. This library recognizes crate::FORMAT_VERSION_V1 only.

Fields

found: u16

The format version byte read from the file.

SchemeMismatch

The file’s key-scheme id does not match the type parameter used to open it.

If the caller opens Keystore::<BlsSigning>::load(...) but the file on disk is L1WalletBls (scheme id 0x0003), we refuse. This guards against accidentally interpreting wallet master seeds as validator signing seeds, which would produce perfectly-valid-looking BLS signatures that bind to the wrong domain.

Fields

expected: u16

The scheme expected by the caller (K::SCHEME_ID).

expected_name: &'static str

Human-readable expected name (e.g., "BlsSigning").

found: u16

The scheme id actually stored in the file.

CrcMismatch

The CRC32 checksum at the end of the file did not match.

CRC is computed over every byte of the file except the trailing 4. A mismatch indicates disk corruption, partial write, or deliberate tampering. It is NOT a cryptographic integrity check (AES-GCM’s tag is) — CRC is only a fast-fail so we don’t burn ~0.5 s on Argon2 for a file that’s clearly garbage.

Fields

stored: u32

The CRC32 read from the file.

computed: u32

The CRC32 computed over the preceding bytes.

DecryptFailed

AES-GCM authentication tag failed.

This is the single error produced for any cryptographic decryption failure: wrong password, tampered ciphertext, tampered header (AAD mismatch), or truncated payload. We intentionally do NOT distinguish these variants at the error level to avoid side-channel leaks.

InvalidKdfParams(&'static str)

Argon2 or AES-GCM rejected the provided parameters.

Thrown when crate::KdfParams has out-of-bounds values (e.g., memory_kib < 8192) or when the underlying argon2 crate returns an error (rare — usually only on invalid output size).

UnsupportedKdf(u8)

The file advertised an unsupported KDF algorithm.

Currently only 0x01 = Argon2id is recognized. Non-0x01 values are reserved for future algorithms (scrypt, bcrypt, balloon).

UnsupportedCipher(u8)

The file advertised an unsupported symmetric cipher.

Currently only 0x01 = AES-256-GCM is recognized. Non-0x01 values are reserved for e.g. ChaCha20-Poly1305.

AlreadyExists(String)

Keystore::create was called for a path that already exists.

Deliberate: overwriting a keystore file is almost always an operator error. Callers that really want to replace a keystore should crate::Keystore::delete first, or simply crate::Keystore::change_password

• crate::Keystore::rotate_kdf which rotate in place.

InvalidPlaintext

The decrypted plaintext has the wrong length for the key scheme.

Each crate::KeyScheme declares a fixed SECRET_LEN. If unlock decrypts successfully but the plaintext length disagrees with the scheme (e.g., file was encrypted under v1 with a 32-byte seed and this build expects 48), we reject. Normally impossible once the scheme id check has passed; included for defence in depth.

Fields

expected: usize

Expected byte length.

got: usize

Actual byte length read.

InvalidSeed(String)

The provided seed bytes were malformed (e.g., not a valid BLS seed).

Rarely thrown — chia-bls::SecretKey::from_seed accepts any byte length — but reserved for schemes where the raw bytes must pass a scheme-specific validity check (e.g., secp256k1 scalar bounds).

Truncated

The file’s length header claims a payload larger than the file bytes.

Indicates a truncated file (disk full mid-write, network transfer cut, etc). Should be rare since we write files atomically via rename, but guard anyway.

Fields

claimed: usize

Bytes claimed by the header.

available: usize

Bytes actually available.

Trait Implementations

impl Clone for KeystoreError

fn clone(&self) -> KeystoreError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for KeystoreError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for KeystoreError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for KeystoreError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for KeystoreError

fn from(err: Error) -> Self

Wrap an I/O error as a backend error.

Used liberally through the ? operator in crate::FileBackend and other std::io-backed code paths.