x/crypto: add return value descriptions to select golang.org/x/crypto/nacl functions

nacl/box/box.go

@@ -84,39 +84,47 @@ func Precompute(sharedKey, peersPublicKey, privateKey *[32]byte) {
 }
 
 // Seal appends an encrypted and authenticated copy of message to out, which
-// will be Overhead bytes longer than the original and must not overlap it. The
-// nonce must be unique for each distinct message for a given pair of keys.
+// will be Overhead bytes longer than the original and must not overlap it.
+// The return value is a slice containing the appended output, which may
+// point to a newly allocated buffer if out lacks sufficient capacity.
 func Seal(out, message []byte, nonce *[24]byte, peersPublicKey, privateKey *[32]byte) []byte {
 	var sharedKey [32]byte
 	Precompute(&sharedKey, peersPublicKey, privateKey)
 	return secretbox.Seal(out, message, nonce, &sharedKey)
 }
 
 // SealAfterPrecomputation performs the same actions as Seal, but takes a
-// shared key as generated by Precompute.
+// shared key as generated by Precompute. The return value is a slice containing
+// the appended output, which may point to a newly allocated buffer if out lacks
+// sufficient capacity.
 func SealAfterPrecomputation(out, message []byte, nonce *[24]byte, sharedKey *[32]byte) []byte {
 	return secretbox.Seal(out, message, nonce, sharedKey)
 }
 
 // Open authenticates and decrypts a box produced by Seal and appends the
 // message to out, which must not overlap box. The output will be Overhead
-// bytes smaller than box.
+// bytes smaller than box. The return value is the updated out slice containing
+// the decrypted message and a boolean indicating whether authentication was
+// successful.
 func Open(out, box []byte, nonce *[24]byte, peersPublicKey, privateKey *[32]byte) ([]byte, bool) {
 	var sharedKey [32]byte
 	Precompute(&sharedKey, peersPublicKey, privateKey)
 	return secretbox.Open(out, box, nonce, &sharedKey)
 }
 
 // OpenAfterPrecomputation performs the same actions as Open, but takes a
-// shared key as generated by Precompute.
+// shared key as generated by Precompute. The return value is the updated out
+// slice containing the decrypted message and a boolean indicating whether
+// authentication was successful.
 func OpenAfterPrecomputation(out, box []byte, nonce *[24]byte, sharedKey *[32]byte) ([]byte, bool) {
 	return secretbox.Open(out, box, nonce, sharedKey)
 }
 
 // SealAnonymous appends an encrypted and authenticated copy of message to out,
 // which will be AnonymousOverhead bytes longer than the original and must not
 // overlap it. This differs from Seal in that the sender is not required to
-// provide a private key.
+// provide a private key. The return value is the updated out slice containing
+// the appended output.
 func SealAnonymous(out, message []byte, recipient *[32]byte, rand io.Reader) ([]byte, error) {
 	if rand == nil {
 		rand = cryptorand.Reader

nacl/secretbox/secretbox.go

@@ -72,7 +72,9 @@ func sliceForAppend(in []byte, n int) (head, tail []byte) {
 
 // Seal appends an encrypted and authenticated copy of message to out, which
 // must not overlap message. The key and nonce pair must be unique for each
-// distinct message and the output will be Overhead bytes longer than message.
+// distinct message. The output will be Overhead bytes longer than message.
+// The return value is a slice containing the entire output, which may point
+// to a newly allocated buffer if out lacks sufficient capacity.
 func Seal(out, message []byte, nonce *[24]byte, key *[32]byte) []byte {
 	var subKey [32]byte
 	var counter [16]byte
@@ -121,7 +123,10 @@ func Seal(out, message []byte, nonce *[24]byte, key *[32]byte) []byte {
 
 // Open authenticates and decrypts a box produced by Seal and appends the
 // message to out, which must not overlap box. The output will be Overhead
-// bytes smaller than box.
+// bytes smaller than box. The return value is a slice containing the entire
+// output, which may point to a newly allocated buffer if out lacks sufficient
+// capacity, and a boolean indicating whether the authentication was
+// successful.
 func Open(out, box []byte, nonce *[24]byte, key *[32]byte) ([]byte, bool) {
 	if len(box) < Overhead {
 		return nil, false

nacl/sign/sign.go

@@ -44,7 +44,9 @@ func GenerateKey(rand io.Reader) (publicKey *[32]byte, privateKey *[64]byte, err
 }
 
 // Sign appends a signed copy of message to out, which will be Overhead bytes
-// longer than the original and must not overlap it.
+// longer than the original and must not overlap it. The return value is a
+// slice containing the signed message, which may point to a newly allocated
+// buffer if out lacks sufficient capacity.
 func Sign(out, message []byte, privateKey *[64]byte) []byte {
 	sig := ed25519.Sign(ed25519.PrivateKey((*privateKey)[:]), message)
 	ret, out := sliceForAppend(out, Overhead+len(message))
@@ -58,7 +60,9 @@ func Sign(out, message []byte, privateKey *[64]byte) []byte {
 
 // Open verifies a signed message produced by Sign and appends the message to
 // out, which must not overlap the signed message. The output will be Overhead
-// bytes smaller than the signed message.
+// bytes smaller than the signed message. The return values are the updated out
+// slice containing the verified message and a boolean indicating whether the
+// signature verification was successful.
 func Open(out, signedMessage []byte, publicKey *[32]byte) ([]byte, bool) {
 	if len(signedMessage) < Overhead {
 		return nil, false