1// Copyright 2012 The Go Authors. All rights reserved. 2// Use of this source code is governed by a BSD-style 3// license that can be found in the LICENSE file. 4 5/* 6Package box authenticates and encrypts small messages using public-key cryptography. 7 8Box uses Curve25519, XSalsa20 and Poly1305 to encrypt and authenticate 9messages. The length of messages is not hidden. 10 11It is the caller's responsibility to ensure the uniqueness of nonces—for 12example, by using nonce 1 for the first message, nonce 2 for the second 13message, etc. Nonces are long enough that randomly generated nonces have 14negligible risk of collision. 15 16Messages should be small because: 17 181. The whole message needs to be held in memory to be processed. 19 202. Using large messages pressures implementations on small machines to decrypt 21and process plaintext before authenticating it. This is very dangerous, and 22this API does not allow it, but a protocol that uses excessive message sizes 23might present some implementations with no other choice. 24 253. Fixed overheads will be sufficiently amortised by messages as small as 8KB. 26 274. Performance may be improved by working with messages that fit into data caches. 28 29Thus large amounts of data should be chunked so that each message is small. 30(Each message still needs a unique nonce.) If in doubt, 16KB is a reasonable 31chunk size. 32 33This package is interoperable with NaCl: https://nacl.cr.yp.to/box.html. 34*/ 35package box // import "golang.org/x/crypto/nacl/box" 36 37import ( 38 "io" 39 40 "golang.org/x/crypto/curve25519" 41 "golang.org/x/crypto/nacl/secretbox" 42 "golang.org/x/crypto/salsa20/salsa" 43) 44 45// Overhead is the number of bytes of overhead when boxing a message. 46const Overhead = secretbox.Overhead 47 48// GenerateKey generates a new public/private key pair suitable for use with 49// Seal and Open. 50func GenerateKey(rand io.Reader) (publicKey, privateKey *[32]byte, err error) { 51 publicKey = new([32]byte) 52 privateKey = new([32]byte) 53 _, err = io.ReadFull(rand, privateKey[:]) 54 if err != nil { 55 publicKey = nil 56 privateKey = nil 57 return 58 } 59 60 curve25519.ScalarBaseMult(publicKey, privateKey) 61 return 62} 63 64var zeros [16]byte 65 66// Precompute calculates the shared key between peersPublicKey and privateKey 67// and writes it to sharedKey. The shared key can be used with 68// OpenAfterPrecomputation and SealAfterPrecomputation to speed up processing 69// when using the same pair of keys repeatedly. 70func Precompute(sharedKey, peersPublicKey, privateKey *[32]byte) { 71 curve25519.ScalarMult(sharedKey, privateKey, peersPublicKey) 72 salsa.HSalsa20(sharedKey, &zeros, sharedKey, &salsa.Sigma) 73} 74 75// Seal appends an encrypted and authenticated copy of message to out, which 76// will be Overhead bytes longer than the original and must not overlap it. The 77// nonce must be unique for each distinct message for a given pair of keys. 78func Seal(out, message []byte, nonce *[24]byte, peersPublicKey, privateKey *[32]byte) []byte { 79 var sharedKey [32]byte 80 Precompute(&sharedKey, peersPublicKey, privateKey) 81 return secretbox.Seal(out, message, nonce, &sharedKey) 82} 83 84// SealAfterPrecomputation performs the same actions as Seal, but takes a 85// shared key as generated by Precompute. 86func SealAfterPrecomputation(out, message []byte, nonce *[24]byte, sharedKey *[32]byte) []byte { 87 return secretbox.Seal(out, message, nonce, sharedKey) 88} 89 90// Open authenticates and decrypts a box produced by Seal and appends the 91// message to out, which must not overlap box. The output will be Overhead 92// bytes smaller than box. 93func Open(out, box []byte, nonce *[24]byte, peersPublicKey, privateKey *[32]byte) ([]byte, bool) { 94 var sharedKey [32]byte 95 Precompute(&sharedKey, peersPublicKey, privateKey) 96 return secretbox.Open(out, box, nonce, &sharedKey) 97} 98 99// OpenAfterPrecomputation performs the same actions as Open, but takes a 100// shared key as generated by Precompute. 101func OpenAfterPrecomputation(out, box []byte, nonce *[24]byte, sharedKey *[32]byte) ([]byte, bool) { 102 return secretbox.Open(out, box, nonce, sharedKey) 103} 104