nacl/[secret]box: clarify message size comment.
While package comments shouldn't be novels, this throwaway word was not
sufficient (and wasn't mirrored in the `box` package).
This change attempts to include more reasoning without using too many
words.
Fixes golang/go#17673,golang/go#21139
Change-Id: I7fa11e2cd5b8e2010420cc14d784f9b0c65db6d2
Reviewed-on: https://go-review.googlesource.com/35910
Reviewed-by: Russ Cox <rsc@golang.org>
diff --git a/nacl/box/box.go b/nacl/box/box.go
index 7ed1864..7ab1a2e 100644
--- a/nacl/box/box.go
+++ b/nacl/box/box.go
@@ -3,7 +3,7 @@
// license that can be found in the LICENSE file.
/*
-Package box authenticates and encrypts messages using public-key cryptography.
+Package box authenticates and encrypts small messages using public-key cryptography.
Box uses Curve25519, XSalsa20 and Poly1305 to encrypt and authenticate
messages. The length of messages is not hidden.
@@ -13,6 +13,23 @@
message, etc. Nonces are long enough that randomly generated nonces have
negligible risk of collision.
+Messages should be small because:
+
+1. The whole message needs to be held in memory to be processed.
+
+2. Using large messages pressures implementations on small machines to decrypt
+and process plaintext before authenticating it. This is very dangerous, and
+this API does not allow it, but a protocol that uses excessive message sizes
+might present some implementations with no other choice.
+
+3. Fixed overheads will be sufficiently amortised by messages as small as 8KB.
+
+4. Performance may be improved by working with messages that fit into data caches.
+
+Thus large amounts of data should be chunked so that each message is small.
+(Each message still needs a unique nonce.) If in doubt, 16KB is a reasonable
+chunk size.
+
This package is interoperable with NaCl: https://nacl.cr.yp.to/box.html.
*/
package box // import "golang.org/x/crypto/nacl/box"
diff --git a/nacl/secretbox/secretbox.go b/nacl/secretbox/secretbox.go
index 1e1dff5..53ee83c 100644
--- a/nacl/secretbox/secretbox.go
+++ b/nacl/secretbox/secretbox.go
@@ -13,6 +13,23 @@
message, etc. Nonces are long enough that randomly generated nonces have
negligible risk of collision.
+Messages should be small because:
+
+1. The whole message needs to be held in memory to be processed.
+
+2. Using large messages pressures implementations on small machines to decrypt
+and process plaintext before authenticating it. This is very dangerous, and
+this API does not allow it, but a protocol that uses excessive message sizes
+might present some implementations with no other choice.
+
+3. Fixed overheads will be sufficiently amortised by messages as small as 8KB.
+
+4. Performance may be improved by working with messages that fit into data caches.
+
+Thus large amounts of data should be chunked so that each message is small.
+(Each message still needs a unique nonce.) If in doubt, 16KB is a reasonable
+chunk size.
+
This package is interoperable with NaCl: https://nacl.cr.yp.to/secretbox.html.
*/
package secretbox // import "golang.org/x/crypto/nacl/secretbox"
