Documentation
¶
Overview ¶
Package box authenticates and encrypts messages using public-key cryptography.
Box uses Curve25519, XSalsa20 and Poly1305 to encrypt and authenticate messages. The length of messages is not hidden.
It is the caller's responsibility to ensure the uniqueness of nonces—for 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.
This package is interoperable with NaCl: https://nacl.cr.yp.to/box.html.
Example ¶
package main
import (
crypto_rand "crypto/rand"
"fmt"
"github.com/kevinburke/nacl/box"
)
func main() {
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.
msg := []byte("Alas, poor Yorick! I knew him, Horatio")
// This encrypts msg and appends the result to the nonce.
encrypted := box.EasySeal(msg, 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.
decrypted, err := box.EasyOpen(encrypted, senderPublicKey, recipientPrivateKey)
if err != nil {
panic(err)
}
fmt.Println(string(decrypted))
}
Output: Alas, poor Yorick! I knew him, Horatio
Example (Precompute) ¶
package main
import (
crypto_rand "crypto/rand"
"fmt"
"github.com/kevinburke/nacl"
"github.com/kevinburke/nacl/box"
)
func main() {
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 := box.Precompute(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.
nonce := nacl.NewNonce()
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.
sharedDecryptKey := box.Precompute(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
Index ¶
- Constants
- func EasyOpen(box []byte, peersPublicKey, privateKey nacl.Key) ([]byte, error)
- func EasySeal(message []byte, peersPublicKey, privateKey nacl.Key) []byte
- func GenerateKey(rand io.Reader) (publicKey, privateKey nacl.Key, err error)
- func Open(out, box []byte, nonce nacl.Nonce, peersPublicKey, privateKey nacl.Key) ([]byte, bool)
- func OpenAfterPrecomputation(out, box []byte, nonce nacl.Nonce, sharedKey nacl.Key) ([]byte, bool)
- func Precompute(peersPublicKey, privateKey nacl.Key) nacl.Key
- func Seal(out, message []byte, nonce nacl.Nonce, peersPublicKey, privateKey nacl.Key) []byte
- func SealAfterPrecomputation(out, message []byte, nonce nacl.Nonce, sharedKey nacl.Key) []byte
Examples ¶
Constants ¶
const Overhead = secretbox.Overhead
Overhead is the number of bytes of overhead when boxing a message.
Variables ¶
This section is empty.
Functions ¶
func EasyOpen ¶
EasyOpen decrypts box using key. We assume a 24-byte nonce is prepended to the encrypted text in box. The key and nonce pair must be unique for each distinct message.
func EasySeal ¶
EasySeal encrypts message using peersPublicKey and privateKey. The output will have a randomly generated nonce prepended to it. The output will be Overhead + 24 bytes longer than the original.
func GenerateKey ¶
GenerateKey generates a new public/private key pair suitable for use with Seal and Open.
func Open ¶
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.
func OpenAfterPrecomputation ¶
OpenAfterPrecomputation performs the same actions as Open, but takes a shared key as generated by Precompute.
func Precompute ¶
Precompute calculates the shared key between peersPublicKey and privateKey and writes it to sharedKey. The shared key can be used with OpenAfterPrecomputation and SealAfterPrecomputation to speed up processing when using the same pair of keys repeatedly.
Types ¶
This section is empty.
Source Files