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 }