Struct PrivateKeyDecryptor 

#[non_exhaustive]
pub struct PrivateKeyDecryptor { /* private fields */ }

Decryptor for public-key-sealed .fcr files. Returned from Decryptor::open when the file’s recipient list classifies as UnauthenticatedRecipientMode::PublicKey.

Implementations

impl PrivateKeyDecryptor

pub fn kdf_limit(self, limit: KdfLimit) -> Self

Sets the reader-side KDF resource policy for unlocking private.key.

The policy caps Argon2id memory cost, time cost, lane count, and combined work accepted from the key file’s cleartext header, before any derivation work begins. If unset, the decrypt path applies KdfLimit::default, a desktop-sized budget of 1 GiB and the writer’s own work budget, matching what this library writes.

A service that unlocks untrusted key files unattended should set a smaller limit and bound how many unlocks run at once: the key file’s cleartext header chooses the Argon2id cost, and the derivation runs before the wrapped secret is authenticated.

pub fn key_read_limits(self, limits: KeyReadLimits) -> Self

Overrides the key-file caps applied while reading the supplied private.key.

If unset, the decrypt path applies KeyReadLimits::default. Raise KeyReadLimits::max_private_key_wrapped_secret_len for a key file whose wrapped secret legitimately exceeds the default. It is the only KeyReadLimits cap a private.key uses.

pub fn archive_limits(self, limits: ArchiveLimits) -> Self

Sets archive resource caps for extraction.

Limits must admit the archive’s actual contents. Raising Encryptor::archive_limits does not itself require higher reader limits; only archives that exceed the defaults need them here.

pub fn header_read_limits(self, limits: HeaderReadLimits) -> Self

Overrides the header-read caps applied while parsing the .fcr header during decrypt. The same limits used at Decryptor::open / Decryptor::open_with_limits are carried into the variant; this builder lets callers tighten or loosen them between open and decrypt for advanced flows.

pub fn incomplete_output_policy(self, policy: IncompleteOutputPolicy) -> Self

Sets the policy that governs the .incomplete working tree when this decrypt fails.

Defaults to IncompleteOutputPolicy::DeleteOnError, which removes this run’s .incomplete plaintext while the output is still treated as staged, and reports in the returned error a removal that failed or could not be confirmed. It does not remove a complete output confirmed before a later filesystem namespace error. Pass IncompleteOutputPolicy::RetainOnError for backup-recovery or forensic flows where partial output is more useful than no output. See that variant for the truncation-prefix caveat callers must understand before acting on a retained partial.

pub fn decrypt( self, private_key: PrivateKey, output_dir: impl AsRef<Path>, on_event: impl Fn(&ProgressEvent), ) -> Result<DecryptOutcome, CryptoError>

Decrypts this public-key-recipient .fcr into output_dir.

private_key must reference a FerroCrypt private.key file. The private key is unlocked with the passphrase bound by PrivateKey::from_key_file, then the decryptor tries the supported x25519 recipient slots. The first candidate file key that verifies the header MAC is selected, but all supported slots are still attempted to reduce disclosure of the matching slot’s position through timing. On success, the decrypted file or directory is promoted into output_dir and returned in DecryptOutcome::output_path. The output directory must already exist and have trusted path ancestry. The archived root name determines the destination; existing final or .incomplete entries are rejected. See IncompleteOutputPolicy for cleanup behavior and ProgressEvent for callback behavior.

Errors

Returns CryptoError::InvalidInput for an empty or too-long private-key passphrase or an output conflict. An ArchiveLimits cap reports its own Archive*CapExceeded variant, never InvalidInput. An archived path the FCA grammar refuses returns CryptoError::UnsafeArchivePath, and a manifest whose tree shape is illegal returns CryptoError::InvalidArchiveTree. Returns CryptoError::DecryptorModeMismatch if the file at the path is no longer public-key-sealed: the header is read again here, so a change to a different recipient mode is refused. A replacement file with the same mode is processed normally. Returns CryptoError::InvalidFormat if the private key, encrypted container, or authenticated payload stream is structurally malformed; returns CryptoError::KeyFileUnlockFailed if the private key is tampered or protected by a different passphrase. Returns CryptoError::KdfResourceCapExceeded, CryptoError::KdfTimeCostCapExceeded, CryptoError::KdfLanesCapExceeded, or CryptoError::KdfWorkCapExceeded for private.key KDF costs above the KdfLimit. Returns CryptoError::UnsupportedKeyType if the private key wraps a key type this build does not support. Returns authentication errors such as CryptoError::RecipientUnwrapFailed, CryptoError::HeaderMacFailedAfterUnwrap, CryptoError::NoSupportedRecipient, CryptoError::PayloadTampered, or CryptoError::PayloadTruncated. RecipientUnwrapFailed means the private key matched no supported recipient slot, or a recipient body was modified; NoSupportedRecipient means the file contains no recipient type this build can process. Returns CryptoError::InputPath if the encrypted file or the private key file does not exist, and CryptoError::Io for other filesystem failures. Checks that run after the complete plaintext output is committed can still fail the call, with CryptoError::InvalidInput or CryptoError::Io. In that case IncompleteOutputPolicy does not remove the confirmed output, and the error message says that the output is complete, unless the check found the output’s final name missing or holding another entry, which is reported as a replacement.

Trait Implementations

impl Debug for PrivateKeyDecryptor

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

Formats the value using the given formatter.