0
# TweetNaCl.js
1

2
TweetNaCl.js is a JavaScript port of the TweetNaCl cryptographic library that provides comprehensive cryptographic primitives including public-key authenticated encryption, secret-key authenticated encryption, digital signatures, scalar multiplication, hashing, and secure random byte generation. The library offers two implementations: nacl.js (direct port) and nacl-fast.js (optimized version used by default).
3

4
## Package Information
5

6
- **Package Name**: tweetnacl
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install tweetnacl`
10

11
## Core Imports
12

13
```javascript
14
const nacl = require('tweetnacl');
15
```
16

17
For ES modules:
18

19
```javascript
20
import nacl from 'tweetnacl';
21
```
22

23
For TypeScript with types:
24

25
```typescript
26
import * as nacl from 'tweetnacl';
27
// or
28
import nacl from 'tweetnacl';
29
```
30

31
## Basic Usage
32

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

36
// Generate a random key pair
37
const keyPair = nacl.box.keyPair();
38

39
// Create a message and nonce
40
const message = new Uint8Array([1, 2, 3, 4, 5]);
41
const nonce = nacl.randomBytes(nacl.box.nonceLength);
42

43
// Encrypt the message
44
const encrypted = nacl.box(message, nonce, keyPair.publicKey, keyPair.secretKey);
45

46
// Decrypt the message
47
const decrypted = nacl.box.open(encrypted, nonce, keyPair.publicKey, keyPair.secretKey);
48

49
console.log(decrypted); // [1, 2, 3, 4, 5]
50
```
51

52
## Architecture
53

54
TweetNaCl.js is organized around five core cryptographic capabilities:
55

56
- **Public-Key Cryptography**: Key exchange and authenticated encryption using Curve25519 and XSalsa20-Poly1305
57
- **Secret-Key Cryptography**: Authenticated encryption using XSalsa20-Poly1305 for shared-key scenarios
58
- **Digital Signatures**: Message signing and verification using Ed25519
59
- **Scalar Multiplication**: Low-level Curve25519 operations for custom protocols
60
- **Utility Functions**: Hashing (SHA-512), random byte generation, and constant-time comparison
61

62
The library automatically detects the runtime environment (browser or Node.js) and initializes the appropriate cryptographically secure random number generator.
63

64
## Capabilities
65

66
### Public-Key Authenticated Encryption
67

68
Public-key authenticated encryption using x25519-xsalsa20-poly1305. Provides confidentiality and authenticity between two parties using their key pairs.
69

70
```javascript { .api }
71
nacl.box(message, nonce, theirPublicKey, mySecretKey): Uint8Array
72
nacl.box.open(box, nonce, theirPublicKey, mySecretKey): Uint8Array | null
73
nacl.box.keyPair(): {publicKey: Uint8Array, secretKey: Uint8Array}
74
```
75

76
[Public-Key Encryption](./box.md)
77

78
### Secret-Key Authenticated Encryption
79

80
Secret-key authenticated encryption using xsalsa20-poly1305. Provides confidentiality and authenticity using a shared secret key.
81

82
```javascript { .api }
83
nacl.secretbox(message, nonce, key): Uint8Array
84
nacl.secretbox.open(box, nonce, key): Uint8Array | null
85
```
86

87
[Secret-Key Encryption](./secretbox.md)
88

89
### Digital Signatures
90

91
Digital signatures using ed25519. Create and verify cryptographic signatures for message authentication and non-repudiation.
92

93
```javascript { .api }
94
nacl.sign(message, secretKey): Uint8Array
95
nacl.sign.open(signedMessage, publicKey): Uint8Array | null
96
nacl.sign.keyPair(): {publicKey: Uint8Array, secretKey: Uint8Array}
97
```
98

99
[Digital Signatures](./sign.md)
100

101
### Scalar Multiplication
102

103
Low-level scalar multiplication using x25519. Enables custom cryptographic protocols and key derivation.
104

105
```javascript { .api }
106
nacl.scalarMult(n, p): Uint8Array
107
nacl.scalarMult.base(n): Uint8Array
108
```
109

110
[Scalar Multiplication](./scalarmult.md)
111

112
### Hashing and Utilities
113

114
Core utility functions including SHA-512 hashing, secure random byte generation, and constant-time comparison.
115

116
```javascript { .api }
117
nacl.hash(message): Uint8Array
118
nacl.randomBytes(length): Uint8Array
119
nacl.verify(x, y): boolean
120
nacl.setPRNG(fn): void
121
```
122

123
[Utilities](./utilities.md)
124

125
### Low-Level API
126

127
Advanced low-level cryptographic primitives for custom protocol implementation and performance optimization. These functions provide direct access to underlying operations.
128

129
```javascript { .api }
130
nacl.lowlevel.crypto_box(c, m, mlen, n, pk, sk): number
131
nacl.lowlevel.crypto_secretbox(c, m, mlen, n, k): number
132
nacl.lowlevel.crypto_sign(sm, smlen_p, m, mlen, sk): number
133
```
134

135
[Low-Level API](./lowlevel.md)