0
# Secret-Key Authenticated Encryption
1

2
Secret-key authenticated encryption using xsalsa20-poly1305. This system provides confidentiality and authenticity using a shared secret key, ideal for scenarios where both parties already share a secret.
3

4
## Capabilities
5

6
### Encryption and Decryption
7

8
Encrypt and decrypt messages using a shared secret key.
9

10
```javascript { .api }
11
/**
12
 * Encrypts and authenticates a message using a secret key
13
 * @param {Uint8Array} message - The plaintext message to encrypt
14
 * @param {Uint8Array} nonce - Unique nonce for this encryption (24 bytes)
15
 * @param {Uint8Array} key - Secret key shared between parties (32 bytes)
16
 * @returns {Uint8Array} Encrypted and authenticated message (16 bytes longer than original)
17
 */
18
nacl.secretbox(message, nonce, key): Uint8Array
19

20
/**
21
 * Authenticates and decrypts a secret box using the secret key
22
 * @param {Uint8Array} box - The encrypted message to decrypt
23
 * @param {Uint8Array} nonce - The nonce used for encryption (24 bytes)
24
 * @param {Uint8Array} key - Secret key shared between parties (32 bytes)
25
 * @returns {Uint8Array | null} Decrypted message or null if authentication fails
26
 */
27
nacl.secretbox.open(box, nonce, key): Uint8Array | null
28
```
29

30
**Usage Example:**
31

32
```javascript
33
const nacl = require('tweetnacl');
34

35
// Generate a random secret key (in practice, derive from password or exchange securely)
36
const key = nacl.randomBytes(nacl.secretbox.keyLength);
37

38
// Encrypt a message
39
const message = new TextEncoder().encode("Secret message");
40
const nonce = nacl.randomBytes(nacl.secretbox.nonceLength);
41
const encrypted = nacl.secretbox(message, nonce, key);
42

43
// Decrypt the message
44
const decrypted = nacl.secretbox.open(encrypted, nonce, key);
45
if (decrypted) {
46
  console.log(new TextDecoder().decode(decrypted)); // "Secret message"
47
} else {
48
  console.log("Decryption failed - message was tampered with");
49
}
50
```
51

52
**Multiple Messages Example:**
53

54
```javascript
55
const nacl = require('tweetnacl');
56

57
const key = nacl.randomBytes(nacl.secretbox.keyLength);
58

59
// Encrypt multiple messages with the same key (but different nonces)
60
const messages = ["Message 1", "Message 2", "Message 3"];
61
const encrypted = messages.map(msg => {
62
  const messageBytes = new TextEncoder().encode(msg);
63
  const nonce = nacl.randomBytes(nacl.secretbox.nonceLength);
64
  const box = nacl.secretbox(messageBytes, nonce, key);
65
  return { box, nonce };
66
});
67

68
// Decrypt all messages
69
const decrypted = encrypted.map(({ box, nonce }) => {
70
  const plaintext = nacl.secretbox.open(box, nonce, key);
71
  return plaintext ? new TextDecoder().decode(plaintext) : null;
72
});
73

74
console.log(decrypted); // ["Message 1", "Message 2", "Message 3"]
75
```
76

77
## Constants
78

79
```javascript { .api }
80
nacl.secretbox.keyLength: number        // 32 - Length of secret key in bytes
81
nacl.secretbox.nonceLength: number      // 24 - Length of nonce in bytes
82
nacl.secretbox.overheadLength: number   // 16 - Length of overhead added to encrypted messages
83
```
84

85
## Security Considerations
86

87
- **Key Management**: The secret key must be shared securely between parties and kept confidential.
88
- **Nonce Uniqueness**: Each message encrypted with the same key must use a unique nonce. Reusing nonces with the same key breaks security.
89
- **Nonce Generation**: Use `nacl.randomBytes(nacl.secretbox.nonceLength)` to generate cryptographically secure random nonces.
90
- **Message Integrity**: If `nacl.secretbox.open` returns `null`, the message was tampered with or the wrong key/nonce was used.
91
- **Overhead**: Encrypted messages are 16 bytes longer than the original due to authentication data.
92

93
## Comparison with Public-Key Encryption
94

95
Use secretbox when:
96
- Both parties already share a secret key
97
- Performance is critical (secretbox is faster than box operations)
98
- Communicating with yourself (e.g., encrypting local data)
99

100
Use box when:
101
- Parties don't share a pre-established secret
102
- You need key exchange capabilities
103
- You want to avoid the key distribution problem