0
# Digital Signatures
1

2
Ed25519-based digital signatures provide message authentication and non-repudiation. These signatures are deterministic, fast, and provide high security with small signature sizes.
3

4
## Capabilities
5

6
### Standard Signatures
7

8
```javascript { .api }
9
/**
10
 * Generates a new Ed25519 key pair for digital signatures
11
 * @returns Object with publicKey, privateKey, and keyType properties
12
 */
13
function crypto_sign_keypair();
14

15
/**
16
 * Signs a message and returns the signed message
17
 * @param message - The message to sign
18
 * @param privateKey - 64-byte private key
19
 * @returns Signed message (signature + original message)
20
 */
21
function crypto_sign(message, privateKey);
22

23
/**
24
 * Verifies a signed message and extracts the original message
25
 * @param signedMessage - The signed message to verify
26
 * @param publicKey - 32-byte public key of the signer
27
 * @returns Original message if signature is valid
28
 * @throws Error if signature verification fails
29
 */
30
function crypto_sign_open(signedMessage, publicKey);
31

32
/**
33
 * Creates a detached signature for a message
34
 * @param message - The message to sign
35
 * @param privateKey - 64-byte private key
36
 * @returns 64-byte detached signature
37
 */
38
function crypto_sign_detached(message, privateKey);
39

40
/**
41
 * Verifies a detached signature
42
 * @param signature - 64-byte signature to verify
43
 * @param message - The original message that was signed
44
 * @param publicKey - 32-byte public key of the signer
45
 * @returns true if signature is valid, false otherwise
46
 */
47
function crypto_sign_verify_detached(signature, message, publicKey);
48

49
/**
50
 * Generates a deterministic key pair from a seed
51
 * @param seed - 32-byte seed for key generation
52
 * @returns Object with publicKey, privateKey, and keyType properties
53
 */
54
function crypto_sign_seed_keypair(seed);
55
```
56

57
**Usage Example:**
58

59
```javascript
60
// Generate signing key pair
61
const keyPair = sodium.crypto_sign_keypair();
62

63
// Sign a message
64
const message = sodium.from_string("Hello, World!");
65
const signedMessage = sodium.crypto_sign(message, keyPair.privateKey);
66

67
// Verify and extract message
68
const verified = sodium.crypto_sign_open(signedMessage, keyPair.publicKey);
69
console.log(sodium.to_string(verified)); // "Hello, World!"
70

71
// Detached signature
72
const signature = sodium.crypto_sign_detached(message, keyPair.privateKey);
73
const isValid = sodium.crypto_sign_verify_detached(signature, message, keyPair.publicKey);
74
console.log(isValid); // true
75
```
76

77
### Streaming Signatures
78

79
For large messages that don't fit in memory, use streaming signature operations.
80

81
```javascript { .api }
82
/**
83
 * Initializes a streaming signature context
84
 * @returns State address for subsequent operations
85
 */
86
function crypto_sign_init();
87

88
/**
89
 * Updates the streaming signature with a message chunk
90
 * @param state_address - State from crypto_sign_init
91
 * @param message_chunk - Part of the message to sign
92
 */
93
function crypto_sign_update(state_address, message_chunk);
94

95
/**
96
 * Finalizes streaming signature and creates the signature
97
 * @param state_address - State from crypto_sign_init  
98
 * @param privateKey - 64-byte private key
99
 * @returns 64-byte signature
100
 */
101
function crypto_sign_final_create(state_address, privateKey);
102

103
/**
104
 * Finalizes streaming signature verification
105
 * @param state_address - State from crypto_sign_init
106
 * @param signature - 64-byte signature to verify
107
 * @param publicKey - 32-byte public key of the signer
108
 * @returns true if signature is valid, false otherwise
109
 */
110
function crypto_sign_final_verify(state_address, signature, publicKey);
111
```
112

113
**Streaming Usage Example:**
114

115
```javascript
116
// Sign large message in chunks
117
let state = sodium.crypto_sign_init();
118
sodium.crypto_sign_update(state, chunk1);
119
sodium.crypto_sign_update(state, chunk2);
120
sodium.crypto_sign_update(state, chunk3);
121
const signature = sodium.crypto_sign_final_create(state, privateKey);
122

123
// Verify large message in chunks
124
state = sodium.crypto_sign_init();
125
sodium.crypto_sign_update(state, chunk1);
126
sodium.crypto_sign_update(state, chunk2);
127
sodium.crypto_sign_update(state, chunk3);
128
const isValid = sodium.crypto_sign_final_verify(state, signature, publicKey);
129
```
130

131
### Key Conversion
132

133
Convert between Ed25519 and Curve25519 keys for use with other algorithms.
134

135
```javascript { .api }
136
/**
137
 * Converts Ed25519 public key to Curve25519 public key
138
 * @param edPk - 32-byte Ed25519 public key
139
 * @returns 32-byte Curve25519 public key
140
 */
141
function crypto_sign_ed25519_pk_to_curve25519(edPk);
142

143
/**
144
 * Converts Ed25519 secret key to Curve25519 secret key
145
 * @param edSk - 64-byte Ed25519 secret key  
146
 * @returns 32-byte Curve25519 secret key
147
 */
148
function crypto_sign_ed25519_sk_to_curve25519(edSk);
149

150
/**
151
 * Extracts public key from Ed25519 secret key
152
 * @param privateKey - 64-byte Ed25519 secret key
153
 * @returns 32-byte Ed25519 public key
154
 */
155
function crypto_sign_ed25519_sk_to_pk(privateKey);
156

157
/**
158
 * Extracts seed from Ed25519 secret key
159
 * @param privateKey - 64-byte Ed25519 secret key
160
 * @returns 32-byte seed used to generate the key pair
161
 */
162
function crypto_sign_ed25519_sk_to_seed(privateKey);
163
```
164

165
## Key Pair Structure
166

167
```javascript { .api }
168
interface SigningKeyPair {
169
  publicKey: Uint8Array;  // 32 bytes - share with others for verification
170
  privateKey: Uint8Array; // 64 bytes - keep secret for signing
171
  keyType: string;        // "ed25519"
172
}
173
```
174

175
## Constants
176

177
```javascript { .api }
178
const crypto_sign_BYTES = 64;           // Signature size
179
const crypto_sign_PUBLICKEYBYTES = 32;  // Public key size
180
const crypto_sign_SECRETKEYBYTES = 64;  // Secret key size  
181
const crypto_sign_SEEDBYTES = 32;       // Seed size
182
```
183

184
## Security Considerations
185

186
- **Private Key Security**: Ed25519 private keys must be kept absolutely secret
187
- **Deterministic Signatures**: Ed25519 signatures are deterministic - the same message with the same key always produces the same signature
188
- **Key Generation**: Always use `crypto_sign_keypair()` or `crypto_sign_seed_keypair()` for secure key generation
189
- **Message Integrity**: Signatures provide authentication and integrity but not confidentiality - encrypt if needed
190
- **Public Key Verification**: Ensure public keys are obtained from trusted sources to prevent impersonation attacks