nacl/box: Add examples
These largely follow the pattern laid out in the secretbox example
file. Hopefully they should demonstrate the best ways to use the `box`
primitives.
Change-Id: I99be5f886e6ffe5f859268d6caa282e263eeacd0
Reviewed-on: https://go-review.googlesource.com/44736
Reviewed-by: Adam Langley <agl@golang.org>
diff --git a/nacl/box/example_test.go b/nacl/box/example_test.go
new file mode 100644
index 0000000..25e42d2
--- /dev/null
+++ b/nacl/box/example_test.go
@@ -0,0 +1,95 @@
+package box_test
+
+import (
+ crypto_rand "crypto/rand" // Custom so it's clear which rand we're using.
+ "fmt"
+ "io"
+
+ "golang.org/x/crypto/nacl/box"
+)
+
+func Example() {
+ senderPublicKey, senderPrivateKey, err := box.GenerateKey(crypto_rand.Reader)
+ if err != nil {
+ panic(err)
+ }
+
+ recipientPublicKey, recipientPrivateKey, err := box.GenerateKey(crypto_rand.Reader)
+ if err != nil {
+ panic(err)
+ }
+
+ // You must use a different nonce for each message you encrypt with the
+ // same key. Since the nonce here is 192 bits long, a random value
+ // provides a sufficiently small probability of repeats.
+ var nonce [24]byte
+ if _, err := io.ReadFull(crypto_rand.Reader, nonce[:]); err != nil {
+ panic(err)
+ }
+
+ msg := []byte("Alas, poor Yorick! I knew him, Horatio")
+ // This encrypts msg and appends the result to the nonce.
+ encrypted := box.Seal(nonce[:], msg, &nonce, recipientPublicKey, senderPrivateKey)
+
+ // The recipient can decrypt the message using their private key and the
+ // sender's public key. When you decrypt, you must use the same nonce you
+ // used to encrypt the message. One way to achieve this is to store the
+ // nonce alongside the encrypted message. Above, we stored the nonce in the
+ // first 24 bytes of the encrypted text.
+ var decryptNonce [24]byte
+ copy(decryptNonce[:], encrypted[:24])
+ decrypted, ok := box.Open(nil, encrypted[24:], &decryptNonce, senderPublicKey, recipientPrivateKey)
+ if !ok {
+ panic("decryption error")
+ }
+ fmt.Println(string(decrypted))
+ // Output: Alas, poor Yorick! I knew him, Horatio
+}
+
+func Example_precompute() {
+ senderPublicKey, senderPrivateKey, err := box.GenerateKey(crypto_rand.Reader)
+ if err != nil {
+ panic(err)
+ }
+
+ recipientPublicKey, recipientPrivateKey, err := box.GenerateKey(crypto_rand.Reader)
+ if err != nil {
+ panic(err)
+ }
+
+ // The shared key can be used to speed up processing when using the same
+ // pair of keys repeatedly.
+ sharedEncryptKey := new([32]byte)
+ box.Precompute(sharedEncryptKey, recipientPublicKey, senderPrivateKey)
+
+ // You must use a different nonce for each message you encrypt with the
+ // same key. Since the nonce here is 192 bits long, a random value
+ // provides a sufficiently small probability of repeats.
+ var nonce [24]byte
+ if _, err := io.ReadFull(crypto_rand.Reader, nonce[:]); err != nil {
+ panic(err)
+ }
+
+ msg := []byte("A fellow of infinite jest, of most excellent fancy")
+ // This encrypts msg and appends the result to the nonce.
+ encrypted := box.SealAfterPrecomputation(nonce[:], msg, &nonce, sharedEncryptKey)
+
+ // The shared key can be used to speed up processing when using the same
+ // pair of keys repeatedly.
+ var sharedDecryptKey [32]byte
+ box.Precompute(&sharedDecryptKey, senderPublicKey, recipientPrivateKey)
+
+ // The recipient can decrypt the message using the shared key. When you
+ // decrypt, you must use the same nonce you used to encrypt the message.
+ // One way to achieve this is to store the nonce alongside the encrypted
+ // message. Above, we stored the nonce in the first 24 bytes of the
+ // encrypted text.
+ var decryptNonce [24]byte
+ copy(decryptNonce[:], encrypted[:24])
+ decrypted, ok := box.OpenAfterPrecomputation(nil, encrypted[24:], &decryptNonce, &sharedDecryptKey)
+ if !ok {
+ panic("decryption error")
+ }
+ fmt.Println(string(decrypted))
+ // Output: A fellow of infinite jest, of most excellent fancy
+}
diff --git a/nacl/secretbox/example_test.go b/nacl/secretbox/example_test.go
index b25e663..789f4ff 100644
--- a/nacl/secretbox/example_test.go
+++ b/nacl/secretbox/example_test.go
@@ -43,7 +43,7 @@
// 24 bytes of the encrypted text.
var decryptNonce [24]byte
copy(decryptNonce[:], encrypted[:24])
- decrypted, ok := secretbox.Open([]byte{}, encrypted[24:], &decryptNonce, &secretKey)
+ decrypted, ok := secretbox.Open(nil, encrypted[24:], &decryptNonce, &secretKey)
if !ok {
panic("decryption error")
}
