From 7cd208afcf91f69b786549a4bed77371a7b9cc2d Mon Sep 17 00:00:00 2001
From: Jack O'Connor <jack.oconnor@zoom.us>
Date: Fri, 30 Apr 2021 19:05:56 -0400
Subject: [PATCH] explicitly document the properties of short outputs

Suggested by @joshtriplett at:
https://github.com/BLAKE3-team/BLAKE3/issues/168#issuecomment-829609667
---
 c/README.md | 19 +++++++++++++++----
 src/lib.rs  | 11 +++++++++++
 2 files changed, 26 insertions(+), 4 deletions(-)

diff --git a/c/README.md b/c/README.md
index 8428e48ae..5026b0d4c 100644
--- a/c/README.md
+++ b/c/README.md
@@ -92,10 +92,21 @@ void blake3_hasher_finalize(
   size_t out_len);
 ```
 
-Finalize the hasher and emit an output of any length. This doesn't
-modify the hasher itself, and it's possible to finalize again after
-adding more input. The constant `BLAKE3_OUT_LEN` provides the default
-output length, 32 bytes.
+Finalize the hasher and return an output of any length, given in bytes.
+This doesn't modify the hasher itself, and it's possible to finalize
+again after adding more input. The constant `BLAKE3_OUT_LEN` provides
+the default output length, 32 bytes, which is recommended for most
+callers.
+
+Outputs shorter than the default length of 32 bytes (256 bits) provide
+less security. An N-bit BLAKE3 output is intended to provide N bits of
+first and second preimage resistance and N/2 bits of collision
+resistance, for any N up to 256. Longer outputs don't provide any
+additional security.
+
+Shorter BLAKE3 outputs are prefixes of longer ones. Explicitly
+requesting a short output is equivalent to truncating the default-length
+output. (Note that this is different between BLAKE2 and BLAKE3.)
 
 ## Less Common API Functions
 
diff --git a/src/lib.rs b/src/lib.rs
index cff55d2ef..9dacdcbec 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1337,6 +1337,17 @@ impl std::io::Write for Hasher {
 
 /// An incremental reader for extended output, returned by
 /// [`Hasher::finalize_xof`](struct.Hasher.html#method.finalize_xof).
+///
+/// Outputs shorter than the default length of 32 bytes (256 bits)
+/// provide less security. An N-bit BLAKE3 output is intended to provide
+/// N bits of first and second preimage resistance and N/2 bits of
+/// collision resistance, for any N up to 256. Longer outputs don't
+/// provide any additional security.
+///
+/// Shorter BLAKE3 outputs are prefixes of longer ones. Explicitly
+/// requesting a short output is equivalent to truncating the
+/// default-length output. (Note that this is different between BLAKE2
+/// and BLAKE3.)
 #[derive(Clone)]
 pub struct OutputReader {
     inner: Output,