Documentation
¶
Overview ¶
Package secretbox encrypts and authenticates small messages.
Secretbox uses XSalsa20 and Poly1305 to encrypt and authenticate messages with secret-key cryptography. 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/secretbox.html.
Example ¶
package main
import (
"fmt"
"github.com/kevinburke/nacl"
"github.com/kevinburke/nacl/secretbox"
)
func main() {
// Load your secret key from a safe place and reuse it across multiple
// Seal calls. (Obviously don't use this example key for anything
// real.) If you want to convert a passphrase to a key, use a suitable
// package like bcrypt or scrypt.
key, err := nacl.Load("6368616e676520746869732070617373776f726420746f206120736563726574")
if err != nil {
panic(err)
}
// This encrypts "hello world" and returns an encrypted message with a
// random nonce prepended. 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.
encrypted := secretbox.EasySeal([]byte("hello world"), key)
// When you decrypt, you must use the same nonce and key 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 := secretbox.EasyOpen(encrypted, key)
if err != nil {
panic(err)
}
fmt.Println(string(decrypted))
}
Output: hello world
Index ¶
Examples ¶
Constants ¶
const Overhead = onetimeauth.Size
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 key. A 24-byte nonce is generated and prepended to the output. The key and nonce pair must be unique for each distinct message, and the output will be Overhead+24 bytes longer than message.
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.
Types ¶
This section is empty.
Source Files