box

package
v0.29.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 7, 2024 License: BSD-3-Clause Imports: 6 Imported by: 1,307

Documentation

Overview

Package box authenticates and encrypts small 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.

Messages should be small because:

1. The whole message needs to be held in memory to be processed.

2. Using large messages pressures implementations on small machines to decrypt and process plaintext before authenticating it. This is very dangerous, and this API does not allow it, but a protocol that uses excessive message sizes might present some implementations with no other choice.

3. Fixed overheads will be sufficiently amortised by messages as small as 8KB.

4. Performance may be improved by working with messages that fit into data caches.

Thus large amounts of data should be chunked so that each message is small. (Each message still needs a unique nonce.) If in doubt, 16KB is a reasonable chunk size.

This package is interoperable with NaCl: https://nacl.cr.yp.to/box.html. Anonymous sealing/opening is an extension of NaCl defined by and interoperable with libsodium: https://libsodium.gitbook.io/doc/public-key_cryptography/sealed_boxes.

Example
package main

import (
	crypto_rand "crypto/rand"
	"fmt"
	"io"

	"golang.org/x/crypto/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.
	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
Example (Precompute)
package main

import (
	crypto_rand "crypto/rand"
	"fmt"
	"io"

	"golang.org/x/crypto/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 := 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

Index

Examples

Constants

View Source
const (
	// Overhead is the number of bytes of overhead when boxing a message.
	Overhead = secretbox.Overhead

	// AnonymousOverhead is the number of bytes of overhead when using anonymous
	// sealed boxes.
	AnonymousOverhead = Overhead + 32
)

Variables

This section is empty.

Functions

func GenerateKey

func GenerateKey(rand io.Reader) (publicKey, privateKey *[32]byte, err error)

GenerateKey generates a new public/private key pair suitable for use with Seal and Open.

func Open

func Open(out, box []byte, nonce *[24]byte, peersPublicKey, privateKey *[32]byte) ([]byte, bool)

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

func OpenAfterPrecomputation(out, box []byte, nonce *[24]byte, sharedKey *[32]byte) ([]byte, bool)

OpenAfterPrecomputation performs the same actions as Open, but takes a shared key as generated by Precompute.

func OpenAnonymous

func OpenAnonymous(out, box []byte, publicKey, privateKey *[32]byte) (message []byte, ok bool)

OpenAnonymous authenticates and decrypts a box produced by SealAnonymous and appends the message to out, which must not overlap box. The output will be AnonymousOverhead bytes smaller than box.

func Precompute

func Precompute(sharedKey, peersPublicKey, privateKey *[32]byte)

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.

func Seal

func Seal(out, message []byte, nonce *[24]byte, peersPublicKey, privateKey *[32]byte) []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.

func SealAfterPrecomputation

func SealAfterPrecomputation(out, message []byte, nonce *[24]byte, sharedKey *[32]byte) []byte

SealAfterPrecomputation performs the same actions as Seal, but takes a shared key as generated by Precompute.

func SealAnonymous

func SealAnonymous(out, message []byte, recipient *[32]byte, rand io.Reader) ([]byte, error)

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.

Types

This section is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL