0
# Digital Signatures
1

2
Digital signatures using ed25519. Create and verify cryptographic signatures for message authentication, integrity, and non-repudiation. Ed25519 provides fast signature generation and verification with strong security guarantees.
3

4
## Capabilities
5

6
### Signing and Verification
7

8
Create and verify digital signatures for messages.
9

10
```javascript { .api }
11
/**
12
 * Signs a message using the secret key and returns a signed message
13
 * @param {Uint8Array} message - The message to sign
14
 * @param {Uint8Array} secretKey - The signing secret key (64 bytes)
15
 * @returns {Uint8Array} Signed message (original message + 64-byte signature)
16
 */
17
nacl.sign(message, secretKey): Uint8Array
18

19
/**
20
 * Verifies a signed message and returns the original message
21
 * @param {Uint8Array} signedMessage - The signed message to verify
22
 * @param {Uint8Array} publicKey - The signer's public key (32 bytes)
23
 * @returns {Uint8Array | null} Original message if valid, null if verification fails
24
 */
25
nacl.sign.open(signedMessage, publicKey): Uint8Array | null
26
```
27

28
**Usage Example:**
29

30
```javascript
31
const nacl = require('tweetnacl');
32

33
// Generate a key pair for signing
34
const keyPair = nacl.sign.keyPair();
35

36
// Sign a message
37
const message = new TextEncoder().encode("This is a signed message");
38
const signedMessage = nacl.sign(message, keyPair.secretKey);
39

40
// Verify the signature
41
const verified = nacl.sign.open(signedMessage, keyPair.publicKey);
42
if (verified) {
43
  console.log(new TextDecoder().decode(verified)); // "This is a signed message"
44
} else {
45
  console.log("Signature verification failed");
46
}
47
```
48

49
### Detached Signatures
50

51
Create and verify detached signatures that are separate from the message.
52

53
```javascript { .api }
54
/**
55
 * Creates a detached signature for a message
56
 * @param {Uint8Array} message - The message to sign
57
 * @param {Uint8Array} secretKey - The signing secret key (64 bytes)
58
 * @returns {Uint8Array} The signature (64 bytes)
59
 */
60
nacl.sign.detached(message, secretKey): Uint8Array
61

62
/**
63
 * Verifies a detached signature for a message
64
 * @param {Uint8Array} message - The original message
65
 * @param {Uint8Array} signature - The signature to verify (64 bytes)
66
 * @param {Uint8Array} publicKey - The signer's public key (32 bytes)
67
 * @returns {boolean} True if signature is valid, false otherwise
68
 */
69
nacl.sign.detached.verify(message, signature, publicKey): boolean
70
```
71

72
**Usage Example:**
73

74
```javascript
75
const nacl = require('tweetnacl');
76

77
const keyPair = nacl.sign.keyPair();
78
const message = new TextEncoder().encode("Document to be signed");
79

80
// Create detached signature
81
const signature = nacl.sign.detached(message, keyPair.secretKey);
82

83
// Verify detached signature
84
const isValid = nacl.sign.detached.verify(message, signature, keyPair.publicKey);
85
console.log(isValid); // true
86

87
// Signatures can be stored/transmitted separately from the message
88
console.log(`Message: ${message.length} bytes`);
89
console.log(`Signature: ${signature.length} bytes`); // Always 64 bytes
90
```
91

92
### Key Generation
93

94
Generate key pairs for digital signatures.
95

96
```javascript { .api }
97
/**
98
 * Generates a new random key pair for signing
99
 * @returns {{publicKey: Uint8Array, secretKey: Uint8Array}} Key pair object
100
 */
101
nacl.sign.keyPair(): {publicKey: Uint8Array, secretKey: Uint8Array}
102

103
/**
104
 * Derives a signing key pair from an existing 64-byte secret key
105
 * @param {Uint8Array} secretKey - The secret key (64 bytes)
106
 * @returns {{publicKey: Uint8Array, secretKey: Uint8Array}} Key pair with corresponding public key
107
 */
108
nacl.sign.keyPair.fromSecretKey(secretKey): {publicKey: Uint8Array, secretKey: Uint8Array}
109

110
/**
111
 * Generates a deterministic key pair from a 32-byte seed
112
 * @param {Uint8Array} seed - Cryptographically secure seed (32 bytes)
113
 * @returns {{publicKey: Uint8Array, secretKey: Uint8Array}} Deterministic key pair
114
 */
115
nacl.sign.keyPair.fromSeed(seed): {publicKey: Uint8Array, secretKey: Uint8Array}
116
```
117

118
**Usage Examples:**
119

120
```javascript
121
const nacl = require('tweetnacl');
122

123
// Generate a new random key pair
124
const randomKeyPair = nacl.sign.keyPair();
125
console.log(randomKeyPair.publicKey.length);  // 32
126
console.log(randomKeyPair.secretKey.length);  // 64
127

128
// Derive key pair from existing secret key
129
const derivedKeyPair = nacl.sign.keyPair.fromSecretKey(randomKeyPair.secretKey);
130
// derivedKeyPair.publicKey will be identical to randomKeyPair.publicKey
131

132
// Generate deterministic key pair from seed
133
const seed = nacl.randomBytes(nacl.sign.seedLength);
134
const seedKeyPair = nacl.sign.keyPair.fromSeed(seed);
135

136
// Same seed always produces the same key pair
137
const seedKeyPair2 = nacl.sign.keyPair.fromSeed(seed);
138
console.log(seedKeyPair.publicKey.every((byte, i) => byte === seedKeyPair2.publicKey[i])); // true
139
```
140

141
## Constants
142

143
```javascript { .api }
144
nacl.sign.publicKeyLength: number   // 32 - Length of public key in bytes
145
nacl.sign.secretKeyLength: number   // 64 - Length of secret key in bytes
146
nacl.sign.seedLength: number        // 32 - Length of seed for deterministic key generation
147
nacl.sign.signatureLength: number   // 64 - Length of signature in bytes
148
```
149

150
## Security Considerations
151

152
- **Secret Key Security**: Keep signing secret keys absolutely confidential. Anyone with the secret key can create valid signatures.
153
- **Message Integrity**: If signature verification fails, the message was either tampered with or signed by a different key.
154
- **Non-repudiation**: Valid signatures provide cryptographic proof that the holder of the secret key signed the message.
155
- **Deterministic Generation**: Only use `fromSeed` with cryptographically secure seeds. Never use predictable values.
156
- **Key Lifecycle**: Rotate signing keys periodically and revoke compromised keys through your application's key management system.
157

158
## Use Cases
159

160
- **API Authentication**: Sign API requests to prove authenticity
161
- **Document Signing**: Create tamper-evident digital documents
162
- **Software Distribution**: Sign software packages to verify publisher identity
163
- **Blockchain Transactions**: Sign cryptocurrency transactions
164
- **Message Authentication**: Prove message origin in communication systems