`digest::Update`, `FixedOutput`, and `Mac` are infallible; hardware backends are forced to panic when operations fail

Inizia con le definizioni di digest::Update, digest::FixedOutput, digest::FixedOutputReset, universal_hash::UniversalHash e cipher::StreamCipher, quindi confronta il pattern TryCryptoRng di rand_core. Esamina i percorsi di implementazione di wolfcrypt elencati in digest.rs, hmac.rs, cmac.rs e poly1305.rs per comprendere i fallimenti che vengono nascosti. Il lavoro è completato quando la forma dell’API fallible e la strategia di compatibilità sono concordate per tutti i trait interessati.

Repo: RustCrypto/traits
Labels: api-design, digest, hardware

Background

Issue 1 covers infallible constructors. This issue covers infallible runtime
operations.

The core streaming traits define methods that return ():

• digest::Update::update(&mut self, data: &[u8])
• digest::FixedOutput::finalize_into(self, out: &mut Output<Self>)
• digest::FixedOutputReset::finalize_into_reset(&mut self, out: &mut Output<Self>)
• universal_hash::UniversalHash::update(&mut self, blocks: &[Block<Self>])

For a pure-Rust software implementation, these are genuinely infallible.
A SHA-256 update call is a few arithmetic operations; it cannot fail.
Making the return type Result<(), E> for software implementations would be
noise — the Err branch is unreachable.

The problem

For a hardware backend, every one of these operations dispatches to a driver,
HSM, or hardware accelerator that can fail at runtime:

wolfCrypt's WOLF_CRYPTO_CB mechanism routes each algorithm operation through a
registered C callback. That callback can return WC_NO_ERR_TRACE(CRYPTOCB_UNAVAILABLE)
when the hardware device is busy, or a device-specific error code if the
hardware operation fails. The trait gives us nowhere to put that error.

In our implementation

Discovered while implementing wolfcrypt, a RustCrypto backend wrapping wolfCrypt — a FIPS 140-3 validated C cryptographic library with hardware dispatch via WOLF_CRYPTO_CB.

In every case, we are forced to assert! on the C return code, converting
hardware failures into panics:

• digest::Update::update asserts on wc_Sha256Update:
  wolfcrypt/src/digest.rs:94-97
• digest::FixedOutput::finalize_into asserts on wc_Sha256Final:
  wolfcrypt/src/digest.rs:103-105
• digest::FixedOutputReset::finalize_into_reset asserts on both finalize and
  re-init: wolfcrypt/src/digest.rs:119-124
• Mac (HMAC) Update::update asserts on wolfcrypt_hmac_update:
  wolfcrypt/src/hmac.rs:88-91
• Mac (HMAC) FixedOutput::finalize_into asserts on wolfcrypt_hmac_final:
  wolfcrypt/src/hmac.rs:99-102
• Mac (CMAC) Update::update asserts on wolfcrypt_cmac_update:
  wolfcrypt/src/cmac.rs:90-93
• UniversalHash::update (Poly1305) asserts on wc_Poly1305Update:
  wolfcrypt/src/poly1305.rs:96-99
• UniversalHash finalize (Poly1305) asserts on wc_Poly1305Final:
  wolfcrypt/src/poly1305.rs:111-114

Proposed change

Add Try* variants of the affected traits with fallible signatures and blanket
impls for existing software implementations:

pub trait TryUpdate {
    type Error;
    fn try_update(&mut self, data: &[u8]) -> Result<(), Self::Error>;
}

// Blanket impl: all existing Update implementors get TryUpdate for free
impl<T: Update> TryUpdate for T {
    type Error = core::convert::Infallible;
    fn try_update(&mut self, data: &[u8]) -> Result<(), Infallible> {
        self.update(data);
        Ok(())
    }
}

pub trait TryFixedOutput: TryUpdate {
    fn try_finalize_into(self, out: &mut Output<Self>) -> Result<(), Self::Error>;
}

Hardware backends implement TryUpdate and TryFixedOutput directly.
Software implementations get them via the blanket impls at zero cost. The
existing Update and FixedOutput traits are unchanged; no existing code
breaks.

Prior art

rand_core 0.9 already solved this exact problem for the RNG case by adding
TryCryptoRng with a fallible try_fill_bytes method (see companion
Issue 10). We are asking for the same pattern to be applied to digest::Update
and digest::FixedOutput.

The embedded-hal crate uses type Error associated types on all peripheral
traits for the same reason: hardware peripherals can fail at any method call,
not just at construction time.