From 9ba3862cf6a5452ae579de98f9364dd2e544844c Mon Sep 17 00:00:00 2001 From: Adam Langley Date: Fri, 27 Jan 2017 11:13:05 -0800 Subject: [PATCH] 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 --- nacl/box/box.go | 19 ++++++++++++++++++- nacl/secretbox/secretbox.go | 17 +++++++++++++++++ 2 files changed, 35 insertions(+), 1 deletion(-) 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 @@ example, by using nonce 1 for the first message, nonce 2 for the second 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 @@ example, by using nonce 1 for the first message, nonce 2 for the second 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"