0
# jsSHA
1

2
jsSHA provides a pure TypeScript/JavaScript streaming implementation of the complete Secure Hash Standard (SHA) family. It supports all SHA variants (SHA-1, SHA-224/256/384/512, SHA3-224/256/384/512, SHAKE128/256, cSHAKE128/256, and KMAC128/256) with HMAC functionality, streaming input processing, multiple input/output formats, and zero dependencies.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import jsSHA from "jssha";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const jsSHA = require("jssha");
21
```
22

23
Submodule imports for specific SHA variants:
24

25
```typescript
26
import jsSHA1 from "jssha/sha1";
27
import jsSHA256 from "jssha/sha256";
28
import jsSHA512 from "jssha/sha512";
29
import jsSHA3 from "jssha/sha3";
30
```
31

32
## Basic Usage
33

34
```typescript
35
import jsSHA from "jssha";
36

37
// Basic hashing
38
const shaObj = new jsSHA("SHA-256", "TEXT", { encoding: "UTF8" });
39
shaObj.update("This is a test");
40
const hash = shaObj.getHash("HEX");
41

42
// HMAC
43
const hmacObj = new jsSHA("SHA-256", "TEXT", {
44
  hmacKey: { value: "secret-key", format: "TEXT" }
45
});
46
hmacObj.update("This is a test");
47
const hmac = hmacObj.getHash("HEX");
48

49
// Variable length output (SHAKE)
50
const shakeObj = new jsSHA("SHAKE128", "TEXT");
51
shakeObj.update("This is a test");
52
const shakeHash = shakeObj.getHash("HEX", { outputLen: 256 });
53
```
54

55
## Architecture
56

57
jsSHA is built around several key components:
58

59
- **Unified API**: Single `jsSHA` class supporting all SHA variants through constructor parameters
60
- **Streaming Interface**: `update()` method for processing data in chunks, supporting chainable calls
61
- **Variant-Specific Classes**: Individual classes (`jsSHA1`, `jsSHA256`, `jsSHA512`, `jsSHA3`) for optimized builds
62
- **Type System**: Complete TypeScript definitions with overloaded constructors for different variant/option combinations
63
- **Format Flexibility**: Support for multiple input/output formats (TEXT, HEX, B64, BYTES, ARRAYBUFFER, UINT8ARRAY)
64
- **HMAC Integration**: Built-in HMAC support for all applicable variants
65
- **Advanced Features**: Support for cSHAKE customization, KMAC keyed hashing, and variable-length output
66

67
## Capabilities
68

69
### Core Hashing
70

71
Universal hashing functionality supporting all SHA variants with streaming input processing and multiple output formats.
72

73
```typescript { .api }
74
class jsSHA {
75
  constructor(variant: FixedLengthVariantType, inputFormat: "TEXT", options?: FixedLengthOptionsEncodingType);
76
  constructor(variant: FixedLengthVariantType, inputFormat: FormatNoTextType, options?: FixedLengthOptionsNoEncodingType);
77
  constructor(variant: "SHAKE128" | "SHAKE256", inputFormat: "TEXT", options?: SHAKEOptionsEncodingType);
78
  constructor(variant: "SHAKE128" | "SHAKE256", inputFormat: FormatNoTextType, options?: SHAKEOptionsNoEncodingType);
79
  constructor(variant: "CSHAKE128" | "CSHAKE256", inputFormat: "TEXT", options?: CSHAKEOptionsEncodingType);
80
  constructor(variant: "CSHAKE128" | "CSHAKE256", inputFormat: FormatNoTextType, options?: CSHAKEOptionsNoEncodingType);
81
  constructor(variant: "KMAC128" | "KMAC256", inputFormat: "TEXT", options: KMACOptionsEncodingType);
82
  constructor(variant: "KMAC128" | "KMAC256", inputFormat: FormatNoTextType, options: KMACOptionsNoEncodingType);
83

84
  update(input: string | ArrayBuffer | Uint8Array): this;
85
  getHash(format: "HEX", options?: { outputUpper?: boolean; outputLen?: number; shakeLen?: number }): string;
86
  getHash(format: "B64", options?: { b64Pad?: string; outputLen?: number; shakeLen?: number }): string;
87
  getHash(format: "BYTES", options?: { outputLen?: number; shakeLen?: number }): string;
88
  getHash(format: "UINT8ARRAY", options?: { outputLen?: number; shakeLen?: number }): Uint8Array;
89
  getHash(format: "ARRAYBUFFER", options?: { outputLen?: number; shakeLen?: number }): ArrayBuffer;
90
}
91

92
type FixedLengthVariantType = "SHA-1" | "SHA-224" | "SHA-256" | "SHA-384" | "SHA-512" | "SHA3-224" | "SHA3-256" | "SHA3-384" | "SHA3-512";
93
type FormatNoTextType = "HEX" | "B64" | "BYTES" | "ARRAYBUFFER" | "UINT8ARRAY";
94
```
95

96
[Core Hashing](./core-hashing.md)
97

98
### HMAC Operations
99

100
Hash-based Message Authentication Code functionality for creating and verifying message authenticity.
101

102
```typescript { .api }
103
interface FixedLengthOptionsEncodingType {
104
  hmacKey?: GenericInputType;
105
  encoding?: EncodingType;
106
} | {
107
  numRounds?: number;
108
  encoding?: EncodingType;
109
}
110

111
interface GenericInputType {
112
  value: string | ArrayBuffer | Uint8Array;
113
  format: "TEXT" | "HEX" | "B64" | "BYTES" | "ARRAYBUFFER" | "UINT8ARRAY";
114
  encoding?: EncodingType;
115
}
116

117
type EncodingType = "UTF8" | "UTF16BE" | "UTF16LE";
118
```
119

120
[HMAC Operations](./hmac-operations.md)
121

122
### Advanced SHA3 Features
123

124
Advanced SHA3 functionality including SHAKE, cSHAKE, and KMAC variants with customization and variable-length output.
125

126
```typescript { .api }
127
interface SHAKEOptionsEncodingType {
128
  numRounds?: number;
129
  encoding?: EncodingType;
130
}
131

132
interface CSHAKEOptionsEncodingType {
133
  customization?: GenericInputType;
134
  funcName?: GenericInputType;
135
  encoding?: EncodingType;
136
}
137

138
interface KMACOptionsEncodingType {
139
  kmacKey: GenericInputType;
140
  customization?: GenericInputType;
141
  encoding?: EncodingType;
142
}
143
```
144

145
[Advanced SHA3 Features](./advanced-sha3.md)
146

147
### Variant-Specific Classes
148

149
Optimized classes for specific SHA variants, useful for smaller bundle sizes when only specific variants are needed.
150

151
```typescript { .api }
152
declare class jsSHA1 {
153
  constructor(variant: "SHA-1", inputFormat: "TEXT", options?: FixedLengthOptionsEncodingType);
154
  constructor(variant: "SHA-1", inputFormat: FormatNoTextType, options?: FixedLengthOptionsNoEncodingType);
155
  update(input: string | ArrayBuffer | Uint8Array): this;
156
  getHash(format: "HEX" | "B64" | "BYTES" | "UINT8ARRAY" | "ARRAYBUFFER", options?: any): any;
157
  setHMACKey(key: any, inputFormat: any, options?: any): void;
158
  getHMAC(format: any, options?: any): any;
159
}
160

161
declare class jsSHA256 {
162
  constructor(variant: "SHA-224" | "SHA-256", inputFormat: "TEXT", options?: FixedLengthOptionsEncodingType);
163
  constructor(variant: "SHA-224" | "SHA-256", inputFormat: FormatNoTextType, options?: FixedLengthOptionsNoEncodingType);
164
  // ... same methods as jsSHA1
165
}
166

167
declare class jsSHA512 {
168
  constructor(variant: "SHA-384" | "SHA-512", inputFormat: "TEXT", options?: FixedLengthOptionsEncodingType);
169
  constructor(variant: "SHA-384" | "SHA-512", inputFormat: FormatNoTextType, options?: FixedLengthOptionsNoEncodingType);
170
  // ... same methods as jsSHA1
171
}
172

173
declare class jsSHA3 {
174
  constructor(variant: "SHA3-224" | "SHA3-256" | "SHA3-384" | "SHA3-512", inputFormat: "TEXT", options?: FixedLengthOptionsEncodingType);
175
  constructor(variant: "SHA3-224" | "SHA3-256" | "SHA3-384" | "SHA3-512", inputFormat: FormatNoTextType, options?: FixedLengthOptionsNoEncodingType);
176
  constructor(variant: "SHAKE128" | "SHAKE256", inputFormat: "TEXT", options?: SHAKEOptionsEncodingType);
177
  constructor(variant: "SHAKE128" | "SHAKE256", inputFormat: FormatNoTextType, options?: SHAKEOptionsNoEncodingType);
178
  constructor(variant: "CSHAKE128" | "CSHAKE256", inputFormat: "TEXT", options?: CSHAKEOptionsEncodingType);
179
  constructor(variant: "CSHAKE128" | "CSHAKE256", inputFormat: FormatNoTextType, options?: CSHAKEOptionsNoEncodingType);
180
  constructor(variant: "KMAC128" | "KMAC256", inputFormat: "TEXT", options: KMACOptionsEncodingType);
181
  constructor(variant: "KMAC128" | "KMAC256", inputFormat: FormatNoTextType, options: KMACOptionsNoEncodingType);
182
  // ... same methods as jsSHA1
183
}
184
```
185

186
[Variant-Specific Classes](./variant-classes.md)
187

188
## Types
189

190
```typescript { .api }
191
type EncodingType = "UTF8" | "UTF16BE" | "UTF16LE";
192
type FormatNoTextType = "HEX" | "B64" | "BYTES" | "ARRAYBUFFER" | "UINT8ARRAY";
193
type FormatType = "TEXT" | FormatNoTextType;
194

195
interface GenericInputType {
196
  value: string;
197
  format: "TEXT";
198
  encoding?: EncodingType;
199
} | {
200
  value: string;
201
  format: "B64" | "HEX" | "BYTES";
202
} | {
203
  value: ArrayBuffer;
204
  format: "ARRAYBUFFER";
205
} | {
206
  value: Uint8Array;
207
  format: "UINT8ARRAY";
208
}
209

210
interface packedValue {
211
  value: number[];
212
  binLen: number;
213
}
214

215
type FixedLengthVariantType = "SHA-1" | "SHA-224" | "SHA-256" | "SHA-384" | "SHA-512" | "SHA3-224" | "SHA3-256" | "SHA3-384" | "SHA3-512";
216
```