Stabilize closing mechanism for EncWriter and DecWriter

[aead]

Background Information

The en/decryption of the last fragment differs from all previous fragments since the
first bit of the associated data is flipped from 0 to 1 (i.e. aad[0] |= 0x80). Now, readers and
writers must somehow detect whether the entire plaintext/ciphertext stream has been received -
we don't know whether the (ciphertext) data is authentic but we need to somehow detect the end-of-stream symbol to trigger the "special" logic for the last fragment.

For readers we can assume an EOF after Ok(0). However, for writers the caller has to signal "somehow" that no more data will be written. Therefore, some "close"/"flush" mechanism is necessary.

How to signal an end-of-stream for EncWriter and DecWriter

In general, there are two main options:

1. An end-of-stream is signaled by calling the flush method defined by std::io::Write.
   Optionally, a flush can happen in the destructor - again like BufWriter.
2. We can define a separate close method that signales the end-of-stream.
   Optionally, the close can happen (if not called explicitly) in the destructor.

Drop behavior

Invoking the "close" mechanism (if not invoked explicitly) does not seem to be correct.

• EncWriter:
  If the EncWriter is "closed" implicitly (during drop) it is not possible to handle any error
  that happens during writing the final fragment to the underlying writer - the only option would
  be to panic. Not handling the error may cause silent data corruption since an incomplete
  ciphertext cannot be distinguished from a maliciously truncated one, and therefore, cannot be
  decrypted successfully & securely. However, panic'ing when writing to the underlying writer
  fails introduces non-deterministic program failures. In general, the destructor should not
  panic.
• DecWriter:
  The same is true for DecWriter. In addition, "closing" during drop also fails if the ciphertext
  stream is not authentic. Not handling that error causes incomplete plaintexts such that an
  attacker can mount truncation attacks against programs that use the implicit "close" - either
  intentionally or accidentally. On the other side, panic'ing in that case gives an attacker the
  ability to mount DoS attacks against such programs.

Therefore:

1. There should be no (implicit) "close" mechanism when dropped.
2. The "close" mechanism must be invoked explicitly by the caller.

Now, given that the "close" mechanism must be invoked explicitly, not doing so is a logic bug. Therefore, I suspect that the "correct" behavior (even though unconventional and maybe controversial) is to panic when an EncWriter or DecWriter gets dropped but hasn't been "closed" explicitly. More general, when not "closed" and no previous write call failed.

"Close" mechanisms

Using flush

Initially flush may seem to be an appropriate way to trigger the en/decryption of the last fragment. However, there are the following issues:

• flush takes a (mut) reference to self and therefore it's possible to write any combination
  of write and flush calls - e.g.:

  w.write(buf)?;
  w.flush()?;
  w.write(buf)?;  // This must fail b/c `flush` triggered the last fragment
  

  While this is completely fine for e.g. BufWriter any write that happens after flush must fail
  for EncWriter or DecWriter. Actually, trying to write more data to a "closed" writer is a logic
  bug.
  To prevent this we would need a method takes ownership of the writer - e.g.
  flush(mut self) -> io::Result<()> or close(mut self) -> io::Result<()>.

Alternatives

There are some alternatives to flush. However, there is the fundamental problem that we need to "close" a chain of internal writers since io::Write should be composable:

• A method close(mut self) -> io::Result<()>. However, it would not be possible to invoke
  it on any inner writer since it does not implement a close method.
• A Close trait with a close(mut self) -> io::Result<()> method. Still, this only works
  for the top level EncWriter / DecWriter (if we write a custom Drop implementation).
• A Close trait with a close(&mut self) -> io::Result<()> method and a NopCloser type
  that wraps any type that does not implement Close. So far that's the most flexible
  approach since callers can provide custom implementations of Close such that we can have
  a chain of close calls. However, a caller can still e.g. write to EncWriter / DecWriter after
  close. We could define a separate close(mut self) -> io::Result<()> method for EncWriter
  and DecWriter such that specialization will select the close that takes ownership. However,
  callers can still do the wrong thing by calling Close::close(w) and than write to w. The
  Close trait documentation can also help by indicating the Close should be implemented but
  never directly used. Anyway, even though the incorrect example may be artificial an ideal
  solution would be to proof in the type system that such an error cannot be made by
  callers.

[aead]

Update

Currently the most promising approach is a quite interesting trait construction.
So there is a publicly exported trait:

pub trait Close {
    fn close(&mut self) -> std::io::Result<()>;
}

and a crate-internal non-exported trait in another module - e.g.:

mod internal {
    pub trait Close {
          fn close(&mut self) -> std::io::Result<()>;
    }
}

Now, any external type can (in theory) implement the publicly exported Close trait but not the
non-exported internal::Close trait. Then we can define EncWriter (and similarly DecWriter) like this:

pub struct EncWriter<A: Algorithm, W: std::io::Write + internal::Close> { 
    ... 
}

Further EncWriter and DecWriter don't implement the exported trait Close but define a method:
pub fn close(mut self) -> std::io::Result<()> {...}

Interestingly, at the moment no external type can be used as inner writer for EncWriter (and DecWriter) since they cannot implement internal::Close. However, we can fix this by:

impl<T: Close + ?Sized> internal::Close for T {
    fn close(&mut self) -> std::io::Result<()> {
          Close::close(self)
    }
}

Now, any type that implements the Close trait can be wrapped by an EncWriter while EncWriter does not expose a close(&mut self) but a close(mut self) method. This proofs "no write-after-close" bugs with the type system:

let mut writer = EncWriter::new(...);
writer.close()?;
writer.write(...)?; // This does not compile.

Additionally we can provide a NopCloser type to wrap types which don't implement Close.
Further, we may need to opt-out of the "no write-after-close" compile-time guarantees when composing EncWriter / DecWriter and other writers (e.g. BufWriter). However, we can explicitly document that and return a impl Write + Close to make the opt-out even more explicit.