0
# Core Hashing
1

2
Core hashing functionality providing streaming input processing and hash generation for all SHA variants. The jsSHA class serves as the universal interface supporting traditional SHA variants (SHA-1, SHA-2 family) and modern SHA-3 variants.
3

4
## Capabilities
5

6
### jsSHA Constructor
7

8
Creates a new hashing instance for the specified SHA variant and input format.
9

10
```typescript { .api }
11
/**
12
 * Creates a new jsSHA instance for fixed-length SHA variants with TEXT input
13
 * @param variant - SHA variant: SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, SHA3-224, SHA3-256, SHA3-384, SHA3-512
14
 * @param inputFormat - Must be "TEXT" for this overload
15
 * @param options - Optional configuration including encoding and HMAC key
16
 */
17
constructor(variant: FixedLengthVariantType, inputFormat: "TEXT", options?: FixedLengthOptionsEncodingType);
18

19
/**
20
 * Creates a new jsSHA instance for fixed-length SHA variants with binary input formats
21
 * @param variant - SHA variant: SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, SHA3-224, SHA3-256, SHA3-384, SHA3-512
22
 * @param inputFormat - Input format: HEX, B64, BYTES, ARRAYBUFFER, UINT8ARRAY
23
 * @param options - Optional configuration including HMAC key and numRounds
24
 */
25
constructor(variant: FixedLengthVariantType, inputFormat: FormatNoTextType, options?: FixedLengthOptionsNoEncodingType);
26

27
/**
28
 * Creates a new jsSHA instance for SHAKE variants with TEXT input
29
 * @param variant - SHAKE variant: SHAKE128 or SHAKE256
30
 * @param inputFormat - Must be "TEXT" for this overload
31
 * @param options - Optional configuration including encoding and numRounds
32
 */
33
constructor(variant: "SHAKE128" | "SHAKE256", inputFormat: "TEXT", options?: SHAKEOptionsEncodingType);
34

35
/**
36
 * Creates a new jsSHA instance for SHAKE variants with binary input formats
37
 * @param variant - SHAKE variant: SHAKE128 or SHAKE256
38
 * @param inputFormat - Input format: HEX, B64, BYTES, ARRAYBUFFER, UINT8ARRAY
39
 * @param options - Optional configuration including numRounds
40
 */
41
constructor(variant: "SHAKE128" | "SHAKE256", inputFormat: FormatNoTextType, options?: SHAKEOptionsNoEncodingType);
42

43
type FixedLengthVariantType = "SHA-1" | "SHA-224" | "SHA-256" | "SHA-384" | "SHA-512" | "SHA3-224" | "SHA3-256" | "SHA3-384" | "SHA3-512";
44
type FormatNoTextType = "HEX" | "B64" | "BYTES" | "ARRAYBUFFER" | "UINT8ARRAY";
45
```
46

47
**Usage Examples:**
48

49
```typescript
50
import jsSHA from "jssha";
51

52
// Basic SHA-256 with text input
53
const sha256 = new jsSHA("SHA-256", "TEXT", { encoding: "UTF8" });
54

55
// SHA-1 with hex input
56
const sha1 = new jsSHA("SHA-1", "HEX");
57

58
// SHA3-512 with ArrayBuffer input
59
const sha3 = new jsSHA("SHA3-512", "ARRAYBUFFER");
60

61
// SHAKE128 for variable-length output
62
const shake = new jsSHA("SHAKE128", "TEXT");
63
```
64

65
### update Method
66

67
Streams input data for hashing. Can be called multiple times to process data in chunks.
68

69
```typescript { .api }
70
/**
71
 * Takes input and hashes as many blocks as possible. Stores the rest for future update or getHash calls.
72
 * @param input - The input to be hashed (format must match constructor inputFormat)
73
 * @returns Reference to the same object for method chaining
74
 */
75
update(input: string | ArrayBuffer | Uint8Array): this;
76
```
77

78
**Usage Examples:**
79

80
```typescript
81
import jsSHA from "jssha";
82

83
const shaObj = new jsSHA("SHA-256", "TEXT", { encoding: "UTF8" });
84

85
// Single update
86
shaObj.update("Hello, World!");
87

88
// Multiple updates (streaming)
89
shaObj.update("Hello, ");
90
shaObj.update("World!");
91

92
// Chainable updates
93
shaObj.update("First part").update("Second part").update("Third part");
94

95
// Different input types based on constructor format
96
const hexSha = new jsSHA("SHA-256", "HEX");
97
hexSha.update("48656c6c6f"); // Hex string
98

99
const bufferSha = new jsSHA("SHA-256", "ARRAYBUFFER");
100
const buffer = new TextEncoder().encode("Hello").buffer;
101
bufferSha.update(buffer);
102
```
103

104
### getHash Method
105

106
Returns the computed hash in the specified output format.
107

108
```typescript { .api }
109
/**
110
 * Returns the hash in hexadecimal format
111
 * @param format - Must be "HEX"
112
 * @param options - Optional formatting options
113
 * @returns Hash as hexadecimal string
114
 */
115
getHash(format: "HEX", options?: { outputUpper?: boolean; outputLen?: number; shakeLen?: number }): string;
116

117
/**
118
 * Returns the hash in Base64 format
119
 * @param format - Must be "B64"
120
 * @param options - Optional formatting options
121
 * @returns Hash as Base64 string
122
 */
123
getHash(format: "B64", options?: { b64Pad?: string; outputLen?: number; shakeLen?: number }): string;
124

125
/**
126
 * Returns the hash as a byte string
127
 * @param format - Must be "BYTES"
128
 * @param options - Optional length options for variable-length variants
129
 * @returns Hash as byte string
130
 */
131
getHash(format: "BYTES", options?: { outputLen?: number; shakeLen?: number }): string;
132

133
/**
134
 * Returns the hash as a Uint8Array
135
 * @param format - Must be "UINT8ARRAY"
136
 * @param options - Optional length options for variable-length variants
137
 * @returns Hash as Uint8Array
138
 */
139
getHash(format: "UINT8ARRAY", options?: { outputLen?: number; shakeLen?: number }): Uint8Array;
140

141
/**
142
 * Returns the hash as an ArrayBuffer
143
 * @param format - Must be "ARRAYBUFFER"
144
 * @param options - Optional length options for variable-length variants
145
 * @returns Hash as ArrayBuffer
146
 */
147
getHash(format: "ARRAYBUFFER", options?: { outputLen?: number; shakeLen?: number }): ArrayBuffer;
148
```
149

150
**Usage Examples:**
151

152
```typescript
153
import jsSHA from "jssha";
154

155
const shaObj = new jsSHA("SHA-256", "TEXT", { encoding: "UTF8" });
156
shaObj.update("Hello, World!");
157

158
// Different output formats
159
const hexHash = shaObj.getHash("HEX"); // "dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f"
160
const hexUpper = shaObj.getHash("HEX", { outputUpper: true }); // Uppercase hex
161
const b64Hash = shaObj.getHash("B64"); // Base64 encoded
162
const bytesHash = shaObj.getHash("BYTES"); // Byte string
163
const uint8Hash = shaObj.getHash("UINT8ARRAY"); // Uint8Array
164
const bufferHash = shaObj.getHash("ARRAYBUFFER"); // ArrayBuffer
165

166
// Variable-length output (SHAKE variants only)
167
const shakeObj = new jsSHA("SHAKE128", "TEXT");
168
shakeObj.update("Hello, World!");
169
const shake256bits = shakeObj.getHash("HEX", { outputLen: 256 }); // 256-bit output
170
const shake512bits = shakeObj.getHash("HEX", { outputLen: 512 }); // 512-bit output
171
```
172

173
## Supported Hash Variants
174

175
### Traditional SHA Variants
176

177
- **SHA-1**: 160-bit output, legacy algorithm (deprecated for security-critical applications)
178
- **SHA-224**: 224-bit output, part of SHA-2 family
179
- **SHA-256**: 256-bit output, most commonly used SHA-2 variant
180
- **SHA-384**: 384-bit output, part of SHA-2 family
181
- **SHA-512**: 512-bit output, strongest SHA-2 variant
182

183
### SHA-3 Variants
184

185
- **SHA3-224**: 224-bit output using Keccak sponge function
186
- **SHA3-256**: 256-bit output using Keccak sponge function
187
- **SHA3-384**: 384-bit output using Keccak sponge function
188
- **SHA3-512**: 512-bit output using Keccak sponge function
189

190
### Variable-Length Variants
191

192
- **SHAKE128**: Variable-length output based on 128-bit security level
193
- **SHAKE256**: Variable-length output based on 256-bit security level
194

195
Note: Variable-length variants (SHAKE) require the `outputLen` parameter in `getHash()` options to specify the desired output length in bits.
196

197
## Input Formats
198

199
- **TEXT**: String input with encoding options (UTF8, UTF16BE, UTF16LE)
200
- **HEX**: Hexadecimal string representation
201
- **B64**: Base64 encoded string
202
- **BYTES**: Raw byte string
203
- **ARRAYBUFFER**: JavaScript ArrayBuffer object
204
- **UINT8ARRAY**: JavaScript Uint8Array object
205

206
## Output Formats
207

208
- **HEX**: Hexadecimal string (case configurable)
209
- **B64**: Base64 string (padding configurable)
210
- **BYTES**: Raw byte string
211
- **ARRAYBUFFER**: JavaScript ArrayBuffer object
212
- **UINT8ARRAY**: JavaScript Uint8Array object
213

214
## Options Configuration
215

216
```typescript { .api }
217
interface FixedLengthOptionsEncodingType {
218
  hmacKey?: GenericInputType;
219
  encoding?: EncodingType;
220
} | {
221
  numRounds?: number;
222
  encoding?: EncodingType;
223
}
224

225
interface FixedLengthOptionsNoEncodingType {
226
  hmacKey?: GenericInputType;
227
} | {
228
  numRounds?: number;
229
}
230

231
interface SHAKEOptionsEncodingType {
232
  numRounds?: number;
233
  encoding?: EncodingType;
234
}
235

236
interface SHAKEOptionsNoEncodingType {
237
  numRounds?: number;
238
}
239

240
type EncodingType = "UTF8" | "UTF16BE" | "UTF16LE";
241
```
242

243
**Configuration Options:**
244

245
- **encoding**: Text encoding for TEXT input format (defaults to UTF8)
246
- **numRounds**: Number of hashing iterations (defaults to 1, not valid for MAC variants)
247
- **hmacKey**: HMAC key specification for authenticated hashing
248

249
## Error Handling
250

251
The jsSHA constructor will throw an Error if an unsupported variant is specified. All variants are case-sensitive and must match exactly as specified in the type definitions.
252

253
```typescript
254
// This will throw an error
255
try {
256
  const invalid = new jsSHA("sha-256", "TEXT"); // Wrong case
257
} catch (error) {
258
  console.error("Invalid SHA variant specified");
259
}
260

261
// Correct usage
262
const valid = new jsSHA("SHA-256", "TEXT");
263
```