From 56258084740407e3c3f606b22b8ab61de95df5f2 Mon Sep 17 00:00:00 2001 From: Jeff Wentworth 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