0
# js-sha256
1

2
js-sha256 is a simple SHA-256 / SHA-224 hash function library for JavaScript that supports UTF-8 encoding. It provides both direct hashing functions and streaming hash objects with update capabilities, supports HMAC authentication, and provides multiple output formats including hex strings, byte arrays, and ArrayBuffer.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
// Main import - provides sha256 function directly, sha224 as property
15
const sha256 = require('js-sha256');
16
const sha224 = sha256.sha224;
17
```
18

19
```javascript
20
// Named imports
21
const { sha256, sha224 } = require('js-sha256');
22
```
23

24
```javascript
25
// Explicit property access
26
const sha256 = require('js-sha256').sha256;
27
const sha224 = require('js-sha256').sha224;
28
```
29

30
ES6 modules:
31

32
```javascript
33
import { sha256, sha224 } from 'js-sha256';
34
```
35

36
## Basic Usage
37

38
```javascript
39
import { sha256, sha224 } from 'js-sha256';
40

41
// Direct hashing
42
const hash1 = sha256('Hello, World!');
43
const hash2 = sha224('Hello, World!');
44

45
// Incremental hashing
46
const hasher = sha256.create();
47
hasher.update('Hello, ');
48
hasher.update('World!');
49
const result = hasher.hex();
50

51
// HMAC authentication
52
const hmac = sha256.hmac('secret-key', 'message to authenticate');
53
```
54

55
## Capabilities
56

57
### SHA-256 Hashing
58

59
Core SHA-256 hash functionality with support for multiple input formats and output types.
60

61
```javascript { .api }
62
/**
63
 * Hash a message and return hex string
64
 * @param message - Data to hash (string, Array, Uint8Array, ArrayBuffer)
65
 * @returns 64-character hex string
66
 */
67
function sha256(message: Message): string;
68

69
/**
70
 * Create a hash object for incremental hashing
71
 * @returns Hasher instance for chaining operations
72
 */
73
sha256.create(): Hasher;
74

75
/**
76
 * Create a hash object and add initial message
77
 * @param message - Initial data to hash
78
 * @returns Hasher instance for chaining operations
79
 */
80
sha256.update(message: Message): Hasher;
81

82
/**
83
 * Hash a message and return hex string
84
 * @param message - Data to hash
85
 * @returns 64-character hex string
86
 */
87
sha256.hex(message: Message): string;
88

89
/**
90
 * Hash a message and return byte array
91
 * @param message - Data to hash
92
 * @returns Array of 32 integers (0-255)
93
 */
94
sha256.array(message: Message): number[];
95

96
/**
97
 * Hash a message and return byte array (alias for array)
98
 * @param message - Data to hash
99
 * @returns Array of 32 integers (0-255)
100
 */
101
sha256.digest(message: Message): number[];
102

103
/**
104
 * Hash a message and return ArrayBuffer
105
 * @param message - Data to hash
106
 * @returns ArrayBuffer with 32 bytes
107
 */
108
sha256.arrayBuffer(message: Message): ArrayBuffer;
109
```
110

111
### SHA-224 Hashing
112

113
Core SHA-224 hash functionality with identical API to SHA-256 but shorter output.
114

115
```javascript { .api }
116
/**
117
 * Hash a message and return hex string
118
 * @param message - Data to hash (string, Array, Uint8Array, ArrayBuffer)
119
 * @returns 56-character hex string
120
 */
121
function sha224(message: Message): string;
122

123
/**
124
 * Create a hash object for incremental hashing
125
 * @returns Hasher instance for chaining operations
126
 */
127
sha224.create(): Hasher;
128

129
/**
130
 * Create a hash object and add initial message
131
 * @param message - Initial data to hash
132
 * @returns Hasher instance for chaining operations
133
 */
134
sha224.update(message: Message): Hasher;
135

136
/**
137
 * Hash a message and return hex string
138
 * @param message - Data to hash
139
 * @returns 56-character hex string
140
 */
141
sha224.hex(message: Message): string;
142

143
/**
144
 * Hash a message and return byte array
145
 * @param message - Data to hash
146
 * @returns Array of 28 integers (0-255)
147
 */
148
sha224.array(message: Message): number[];
149

150
/**
151
 * Hash a message and return byte array (alias for array)
152
 * @param message - Data to hash
153
 * @returns Array of 28 integers (0-255)
154
 */
155
sha224.digest(message: Message): number[];
156

157
/**
158
 * Hash a message and return ArrayBuffer
159
 * @param message - Data to hash
160
 * @returns ArrayBuffer with 28 bytes
161
 */
162
sha224.arrayBuffer(message: Message): ArrayBuffer;
163
```
164

165
### Incremental Hashing
166

167
Hasher interface for streaming and incremental hash computation.
168

169
```javascript { .api }
170
interface Hasher {
171
  /**
172
   * Add data to the hash computation
173
   * @param message - Data to add to hash
174
   * @returns this (for method chaining)
175
   */
176
  update(message: Message): Hasher;
177

178
  /**
179
   * Finalize hash and return hex string
180
   * @returns Hex string representation of hash
181
   */
182
  hex(): string;
183

184
  /**
185
   * Finalize hash and return hex string (alias for hex)
186
   * @returns Hex string representation of hash
187
   */
188
  toString(): string;
189

190
  /**
191
   * Finalize hash and return byte array
192
   * @returns Array of integers (0-255)
193
   */
194
  array(): number[];
195

196
  /**
197
   * Finalize hash and return byte array (alias for array)
198
   * @returns Array of integers (0-255)
199
   */
200
  digest(): number[];
201

202
  /**
203
   * Finalize hash and return ArrayBuffer
204
   * @returns ArrayBuffer with hash bytes
205
   */
206
  arrayBuffer(): ArrayBuffer;
207
}
208
```
209

210
**Usage Examples:**
211

212
```javascript
213
import { sha256 } from 'js-sha256';
214

215
// Stream large data
216
const hasher = sha256.create();
217
hasher.update('chunk1');
218
hasher.update('chunk2');
219
hasher.update('chunk3');
220
const finalHash = hasher.hex();
221

222
// Method chaining
223
const hash = sha256.update('initial data')
224
  .update('more data')
225
  .hex();
226

227
// Different output formats
228
const hasher2 = sha256.create().update('test data');
229
const hexOutput = hasher2.hex();        // '...' (64 chars)
230
const arrayOutput = hasher2.array();    // [n1, n2, ..., n32]
231
const bufferOutput = hasher2.arrayBuffer(); // ArrayBuffer(32)
232
```
233

234
### HMAC Authentication
235

236
Hash-based Message Authentication Code functionality for both SHA-256 and SHA-224.
237

238
```javascript { .api }
239
/**
240
 * Compute HMAC-SHA256 and return hex string
241
 * @param secretKey - Secret key for authentication
242
 * @param message - Message to authenticate
243
 * @returns 64-character hex string
244
 */
245
sha256.hmac(secretKey: Message, message: Message): string;
246

247
/**
248
 * Create HMAC hasher with secret key
249
 * @param secretKey - Secret key for authentication
250
 * @returns Hasher instance for incremental HMAC computation
251
 */
252
sha256.hmac.create(secretKey: Message): Hasher;
253

254
/**
255
 * Create HMAC hasher with secret key and initial message
256
 * @param secretKey - Secret key for authentication
257
 * @param message - Initial message to authenticate
258
 * @returns Hasher instance for chaining operations
259
 */
260
sha256.hmac.update(secretKey: Message, message: Message): Hasher;
261

262
/**
263
 * Compute HMAC-SHA256 and return hex string
264
 * @param secretKey - Secret key for authentication
265
 * @param message - Message to authenticate
266
 * @returns 64-character hex string
267
 */
268
sha256.hmac.hex(secretKey: Message, message: Message): string;
269

270
/**
271
 * Compute HMAC-SHA256 and return byte array
272
 * @param secretKey - Secret key for authentication
273
 * @param message - Message to authenticate
274
 * @returns Array of 32 integers (0-255)
275
 */
276
sha256.hmac.array(secretKey: Message, message: Message): number[];
277

278
/**
279
 * Compute HMAC-SHA256 and return byte array (alias for array)
280
 * @param secretKey - Secret key for authentication
281
 * @param message - Message to authenticate
282
 * @returns Array of 32 integers (0-255)
283
 */
284
sha256.hmac.digest(secretKey: Message, message: Message): number[];
285

286
/**
287
 * Compute HMAC-SHA256 and return ArrayBuffer
288
 * @param secretKey - Secret key for authentication
289
 * @param message - Message to authenticate
290
 * @returns ArrayBuffer with 32 bytes
291
 */
292
sha256.hmac.arrayBuffer(secretKey: Message, message: Message): ArrayBuffer;
293

294
/**
295
 * Compute HMAC-SHA224 and return hex string
296
 * @param secretKey - Secret key for authentication
297
 * @param message - Message to authenticate
298
 * @returns 56-character hex string
299
 */
300
sha224.hmac(secretKey: Message, message: Message): string;
301

302
/**
303
 * Create HMAC-SHA224 hasher with secret key
304
 * @param secretKey - Secret key for authentication
305
 * @returns Hasher instance for incremental HMAC computation
306
 */
307
sha224.hmac.create(secretKey: Message): Hasher;
308

309
/**
310
 * Create HMAC-SHA224 hasher with secret key and initial message
311
 * @param secretKey - Secret key for authentication
312
 * @param message - Initial message to authenticate
313
 * @returns Hasher instance for chaining operations
314
 */
315
sha224.hmac.update(secretKey: Message, message: Message): Hasher;
316

317
/**
318
 * Compute HMAC-SHA224 and return hex string
319
 * @param secretKey - Secret key for authentication
320
 * @param message - Message to authenticate
321
 * @returns 56-character hex string
322
 */
323
sha224.hmac.hex(secretKey: Message, message: Message): string;
324

325
/**
326
 * Compute HMAC-SHA224 and return byte array
327
 * @param secretKey - Secret key for authentication
328
 * @param message - Message to authenticate
329
 * @returns Array of 28 integers (0-255)
330
 */
331
sha224.hmac.array(secretKey: Message, message: Message): number[];
332

333
/**
334
 * Compute HMAC-SHA224 and return byte array (alias for array)
335
 * @param secretKey - Secret key for authentication
336
 * @param message - Message to authenticate
337
 * @returns Array of 28 integers (0-255)
338
 */
339
sha224.hmac.digest(secretKey: Message, message: Message): number[];
340

341
/**
342
 * Compute HMAC-SHA224 and return ArrayBuffer
343
 * @param secretKey - Secret key for authentication
344
 * @param message - Message to authenticate
345
 * @returns ArrayBuffer with 28 bytes
346
 */
347
sha224.hmac.arrayBuffer(secretKey: Message, message: Message): ArrayBuffer;
348
```
349

350
**Usage Examples:**
351

352
```javascript
353
import { sha256, sha224 } from 'js-sha256';
354

355
// Direct HMAC computation
356
const hmac256 = sha256.hmac('my-secret-key', 'data to authenticate');
357
const hmac224 = sha224.hmac('my-secret-key', 'data to authenticate');
358

359
// Incremental HMAC computation
360
const hmacHasher = sha256.hmac.create('my-secret-key');
361
hmacHasher.update('chunk 1');
362
hmacHasher.update('chunk 2');
363
const authenticatedHash = hmacHasher.hex();
364

365
// Different output formats
366
const hmacHex = sha256.hmac.hex('key', 'message');      // hex string
367
const hmacArray = sha256.hmac.array('key', 'message');  // byte array
368
const hmacBuffer = sha256.hmac.arrayBuffer('key', 'message'); // ArrayBuffer
369
```
370

371
## Types
372

373
```javascript { .api }
374
/**
375
 * Supported message input types
376
 */
377
type Message = string | number[] | ArrayBuffer | Uint8Array;
378

379
/**
380
 * Hash computation interface for incremental operations
381
 */
382
interface Hasher {
383
  update(message: Message): Hasher;
384
  hex(): string;
385
  toString(): string;
386
  array(): number[];
387
  digest(): number[];
388
  arrayBuffer(): ArrayBuffer;
389
}
390

391
/**
392
 * Hash function interface with multiple output methods
393
 */
394
interface Hash {
395
  (message: Message): string;
396
  create(): Hasher;
397
  update(message: Message): Hasher;
398
  hex(message: Message): string;
399
  array(message: Message): number[];
400
  digest(message: Message): number[];
401
  arrayBuffer(message: Message): ArrayBuffer;
402
  hmac: Hmac;
403
}
404

405
/**
406
 * HMAC function interface
407
 */
408
interface Hmac {
409
  (secretKey: Message, message: Message): string;
410
  create(secretKey: Message): Hasher;
411
  update(secretKey: Message, message: Message): Hasher;
412
  hex(secretKey: Message, message: Message): string;
413
  array(secretKey: Message, message: Message): number[];
414
  digest(secretKey: Message, message: Message): number[];
415
  arrayBuffer(secretKey: Message, message: Message): ArrayBuffer;
416
}
417
```
418

419
## Error Handling
420

421
The library throws an `Error` with the message "input is invalid type" when:
422

423
- Input is `null` or `undefined`
424
- Input is an invalid object type (not array, ArrayBuffer, or typed array)
425
- Input is a non-string, non-object primitive type
426

427
**Valid input types:**
428

429
- **Strings**: UTF-8 encoded JavaScript strings including Unicode characters
430
- **Arrays**: Regular JavaScript arrays containing integers 0-255
431
- **Uint8Array**: Typed arrays for binary data
432
- **Int8Array**: Signed byte arrays (when ArrayBuffer support is available)
433
- **ArrayBuffer**: Raw binary data buffers
434
- **Other typed arrays**: Any ArrayBuffer view when available
435

436
## Platform Compatibility
437

438
The library automatically detects and optimizes for different JavaScript environments:
439

440
- **Browser**: Provides `window.sha256` and `window.sha224` global variables
441
- **Node.js**: Uses native `crypto` module optimizations when available
442
- **Web Workers**: Provides `self.sha256` and `self.sha224` global variables  
443
- **AMD/RequireJS**: Supports AMD module definition
444
- **CommonJS**: Standard `module.exports` support
445

446
## Output Formats
447

448
### Hex String Format
449
- **SHA-256**: 64-character lowercase hexadecimal string
450
- **SHA-224**: 56-character lowercase hexadecimal string
451

452
### Array Format
453
- **SHA-256**: Array of 32 integers (0-255)
454
- **SHA-224**: Array of 28 integers (0-255)
455

456
### ArrayBuffer Format
457
- **SHA-256**: ArrayBuffer containing 32 bytes
458
- **SHA-224**: ArrayBuffer containing 28 bytes
459
- Uses DataView for cross-platform compatibility