github.com/Psiphon-Labs/psiphon-tunnel-core@v2.0.28+incompatible/psiphon/common/crypto/nacl/secretbox/secretbox.go (about)

     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  /*
     6  Package secretbox encrypts and authenticates small messages.
     7  
     8  Secretbox uses XSalsa20 and Poly1305 to encrypt and authenticate messages with
     9  secret-key cryptography. The length of messages is not hidden.
    10  
    11  It is the caller's responsibility to ensure the uniqueness of nonces—for
    12  example, by using nonce 1 for the first message, nonce 2 for the second
    13  message, etc. Nonces are long enough that randomly generated nonces have
    14  negligible risk of collision.
    15  
    16  Messages should be small because:
    17  
    18  1. The whole message needs to be held in memory to be processed.
    19  
    20  2. Using large messages pressures implementations on small machines to decrypt
    21  and process plaintext before authenticating it. This is very dangerous, and
    22  this API does not allow it, but a protocol that uses excessive message sizes
    23  might present some implementations with no other choice.
    24  
    25  3. Fixed overheads will be sufficiently amortised by messages as small as 8KB.
    26  
    27  4. Performance may be improved by working with messages that fit into data caches.
    28  
    29  Thus 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
    31  chunk size.
    32  
    33  This package is interoperable with NaCl: https://nacl.cr.yp.to/secretbox.html.
    34  */
    35  package secretbox // import "github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon/common/crypto/nacl/secretbox"
    36  
    37  import (
    38  	"github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon/common/crypto/internal/poly1305"
    39  	"github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon/common/crypto/internal/subtle"
    40  	"golang.org/x/crypto/salsa20/salsa"
    41  )
    42  
    43  // Overhead is the number of bytes of overhead when boxing a message.
    44  const Overhead = poly1305.TagSize
    45  
    46  // setup produces a sub-key and Salsa20 counter given a nonce and key.
    47  func setup(subKey *[32]byte, counter *[16]byte, nonce *[24]byte, key *[32]byte) {
    48  	// We use XSalsa20 for encryption so first we need to generate a
    49  	// key and nonce with HSalsa20.
    50  	var hNonce [16]byte
    51  	copy(hNonce[:], nonce[:])
    52  	salsa.HSalsa20(subKey, &hNonce, key, &salsa.Sigma)
    53  
    54  	// The final 8 bytes of the original nonce form the new nonce.
    55  	copy(counter[:], nonce[16:])
    56  }
    57  
    58  // sliceForAppend takes a slice and a requested number of bytes. It returns a
    59  // slice with the contents of the given slice followed by that many bytes and a
    60  // second slice that aliases into it and contains only the extra bytes. If the
    61  // original slice has sufficient capacity then no allocation is performed.
    62  func sliceForAppend(in []byte, n int) (head, tail []byte) {
    63  	if total := len(in) + n; cap(in) >= total {
    64  		head = in[:total]
    65  	} else {
    66  		head = make([]byte, total)
    67  		copy(head, in)
    68  	}
    69  	tail = head[len(in):]
    70  	return
    71  }
    72  
    73  // Seal appends an encrypted and authenticated copy of message to out, which
    74  // must not overlap message. The key and nonce pair must be unique for each
    75  // distinct message and the output will be Overhead bytes longer than message.
    76  func Seal(out, message []byte, nonce *[24]byte, key *[32]byte) []byte {
    77  	var subKey [32]byte
    78  	var counter [16]byte
    79  	setup(&subKey, &counter, nonce, key)
    80  
    81  	// The Poly1305 key is generated by encrypting 32 bytes of zeros. Since
    82  	// Salsa20 works with 64-byte blocks, we also generate 32 bytes of
    83  	// keystream as a side effect.
    84  	var firstBlock [64]byte
    85  	salsa.XORKeyStream(firstBlock[:], firstBlock[:], &counter, &subKey)
    86  
    87  	var poly1305Key [32]byte
    88  	copy(poly1305Key[:], firstBlock[:])
    89  
    90  	ret, out := sliceForAppend(out, len(message)+poly1305.TagSize)
    91  	if subtle.AnyOverlap(out, message) {
    92  		panic("nacl: invalid buffer overlap")
    93  	}
    94  
    95  	// We XOR up to 32 bytes of message with the keystream generated from
    96  	// the first block.
    97  	firstMessageBlock := message
    98  	if len(firstMessageBlock) > 32 {
    99  		firstMessageBlock = firstMessageBlock[:32]
   100  	}
   101  
   102  	tagOut := out
   103  	out = out[poly1305.TagSize:]
   104  	for i, x := range firstMessageBlock {
   105  		out[i] = firstBlock[32+i] ^ x
   106  	}
   107  	message = message[len(firstMessageBlock):]
   108  	ciphertext := out
   109  	out = out[len(firstMessageBlock):]
   110  
   111  	// Now encrypt the rest.
   112  	counter[8] = 1
   113  	salsa.XORKeyStream(out, message, &counter, &subKey)
   114  
   115  	var tag [poly1305.TagSize]byte
   116  	poly1305.Sum(&tag, ciphertext, &poly1305Key)
   117  	copy(tagOut, tag[:])
   118  
   119  	return ret
   120  }
   121  
   122  // Open authenticates and decrypts a box produced by Seal and appends the
   123  // message to out, which must not overlap box. The output will be Overhead
   124  // bytes smaller than box.
   125  func Open(out, box []byte, nonce *[24]byte, key *[32]byte) ([]byte, bool) {
   126  	if len(box) < Overhead {
   127  		return nil, false
   128  	}
   129  
   130  	var subKey [32]byte
   131  	var counter [16]byte
   132  	setup(&subKey, &counter, nonce, key)
   133  
   134  	// The Poly1305 key is generated by encrypting 32 bytes of zeros. Since
   135  	// Salsa20 works with 64-byte blocks, we also generate 32 bytes of
   136  	// keystream as a side effect.
   137  	var firstBlock [64]byte
   138  	salsa.XORKeyStream(firstBlock[:], firstBlock[:], &counter, &subKey)
   139  
   140  	var poly1305Key [32]byte
   141  	copy(poly1305Key[:], firstBlock[:])
   142  	var tag [poly1305.TagSize]byte
   143  	copy(tag[:], box)
   144  
   145  	if !poly1305.Verify(&tag, box[poly1305.TagSize:], &poly1305Key) {
   146  		return nil, false
   147  	}
   148  
   149  	ret, out := sliceForAppend(out, len(box)-Overhead)
   150  	if subtle.AnyOverlap(out, box) {
   151  		panic("nacl: invalid buffer overlap")
   152  	}
   153  
   154  	// We XOR up to 32 bytes of box with the keystream generated from
   155  	// the first block.
   156  	box = box[Overhead:]
   157  	firstMessageBlock := box
   158  	if len(firstMessageBlock) > 32 {
   159  		firstMessageBlock = firstMessageBlock[:32]
   160  	}
   161  	for i, x := range firstMessageBlock {
   162  		out[i] = firstBlock[32+i] ^ x
   163  	}
   164  
   165  	box = box[len(firstMessageBlock):]
   166  	out = out[len(firstMessageBlock):]
   167  
   168  	// Now decrypt the rest.
   169  	counter[8] = 1
   170  	salsa.XORKeyStream(out, box, &counter, &subKey)
   171  
   172  	return ret, true
   173  }