From 56258084740407e3c3f606b22b8ab61de95df5f2 Mon Sep 17 00:00:00 2001
From: Jeff Wentworth <jeff@curvegrid.com>
Date: Sun, 12 Jan 2025 14:25:47 +0900
Subject: [PATCH] update docs for return values
---
nacl/box/box.go | 20 ++++++++++++++------
nacl/secretbox/secretbox.go | 9 +++++++--
nacl/sign/sign.go | 8 ++++++--
3 files changed, 27 insertions(+), 10 deletions(-)
diff --git a/nacl/box/box.go b/nacl/box/box.go
index 357bdc773c..995d22802c 100644
--- a/nacl/box/box.go
+++ b/nacl/box/box.go
@@ -84,8 +84,9 @@ 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)
@@ -93,14 +94,18 @@ func Seal(out, message []byte, nonce *[24]byte, peersPublicKey, privateKey *[32]
}
// 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)
@@ -108,7 +113,9 @@ func Open(out, box []byte, nonce *[24]byte, peersPublicKey, privateKey *[32]byte
}
// 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)
}
@@ -116,7 +123,8 @@ func OpenAfterPrecomputation(out, box []byte, nonce *[24]byte, sharedKey *[32]by
// 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
diff --git a/nacl/secretbox/secretbox.go b/nacl/secretbox/secretbox.go
index 1fe600ad03..52b4acb5a9 100644
--- a/nacl/secretbox/secretbox.go
+++ b/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
diff --git a/nacl/sign/sign.go b/nacl/sign/sign.go
index 109c08bb95..32bd688fe5 100644
--- a/nacl/sign/sign.go
+++ b/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