0
# Hashing Algorithms
1

2
Comprehensive hashing functions including Blake2, Keccak, SHA, and xxHash for cryptographic operations, integrity verification, and data fingerprinting.
3

4
## Capabilities
5

6
### Blake2 Hashing
7

8
Blake2 is a cryptographic hash function optimized for speed and security, commonly used in Polkadot.
9

10
```typescript { .api }
11
/**
12
 * Blake2b hash as hex string
13
 * @param data - Data to hash
14
 * @param bitLength - Output length in bits (64, 128, 256, 512)
15
 * @param key - Optional key for keyed hashing
16
 * @returns Hex-encoded hash string
17
 */
18
function blake2AsHex(data: Uint8Array, bitLength?: 64 | 128 | 256 | 512, key?: Uint8Array): string;
19

20
/**
21
 * Blake2b hash as Uint8Array
22
 * @param data - Data to hash
23
 * @param bitLength - Output length in bits (64, 128, 256, 512)
24
 * @param key - Optional key for keyed hashing
25
 * @returns Hash as byte array
26
 */
27
function blake2AsU8a(data: Uint8Array, bitLength?: 64 | 128 | 256 | 512, key?: Uint8Array): Uint8Array;
28
```
29

30
**Usage Example:**
31

32
```typescript
33
import { blake2AsHex, blake2AsU8a } from "@polkadot/util-crypto";
34

35
const data = new TextEncoder().encode("Hello Polkadot");
36

37
// 256-bit Blake2b hash (default)
38
const hash256 = blake2AsU8a(data);
39
console.log(hash256.length); // 32 bytes
40

41
// 128-bit Blake2b hash as hex
42
const hashHex = blake2AsHex(data, 128);
43
console.log(hashHex); // "0x..." 16 bytes as hex
44

45
// Keyed Blake2b hash
46
const key = new Uint8Array(32);
47
const keyedHash = blake2AsU8a(data, 256, key);
48
```
49

50
### Keccak Hashing
51

52
Keccak hashing family including Keccak-256 and Keccak-512, used in Ethereum.
53

54
```typescript { .api }
55
/**
56
 * Keccak-256 hash as Uint8Array
57
 * @param value - Data to hash
58
 * @returns 32-byte Keccak-256 hash
59
 */
60
function keccak256AsU8a(value: Uint8Array): Uint8Array;
61

62
/**
63
 * Keccak-512 hash as Uint8Array
64
 * @param value - Data to hash
65
 * @returns 64-byte Keccak-512 hash
66
 */
67
function keccak512AsU8a(value: Uint8Array): Uint8Array;
68

69
/**
70
 * Keccak hash as hex string
71
 * @param value - Data to hash
72
 * @param bitLength - Output length (256 or 512)
73
 * @returns Hex-encoded hash
74
 */
75
function keccakAsHex(value: Uint8Array, bitLength?: 256 | 512): string;
76

77
/**
78
 * Keccak hash as Uint8Array
79
 * @param value - Data to hash
80
 * @param bitLength - Output length (256 or 512)
81
 * @returns Hash as byte array
82
 */
83
function keccakAsU8a(value: Uint8Array, bitLength?: 256 | 512): Uint8Array;
84
```
85

86
**Usage Example:**
87

88
```typescript
89
import { keccak256AsU8a, keccakAsHex } from "@polkadot/util-crypto";
90

91
const data = new TextEncoder().encode("Hello Ethereum");
92

93
// Keccak-256 (commonly used in Ethereum)
94
const hash256 = keccak256AsU8a(data);
95
console.log(hash256.length); // 32 bytes
96

97
// Keccak-512 as hex
98
const hash512Hex = keccakAsHex(data, 512);
99
```
100

101
### SHA Hashing
102

103
SHA-2 family hashing including SHA-256 and SHA-512.
104

105
```typescript { .api }
106
/**
107
 * SHA-256 hash as Uint8Array
108
 * @param value - Data to hash
109
 * @returns 32-byte SHA-256 hash
110
 */
111
function sha256AsU8a(value: Uint8Array): Uint8Array;
112

113
/**
114
 * SHA-512 hash as Uint8Array
115
 * @param value - Data to hash
116
 * @returns 64-byte SHA-512 hash
117
 */
118
function sha512AsU8a(value: Uint8Array): Uint8Array;
119

120
/**
121
 * SHA hash as Uint8Array
122
 * @param value - Data to hash
123
 * @param bitLength - Output length (256 or 512)
124
 * @returns Hash as byte array
125
 */
126
function shaAsU8a(value: Uint8Array, bitLength?: 256 | 512): Uint8Array;
127
```
128

129
**Usage Example:**
130

131
```typescript
132
import { sha256AsU8a, sha512AsU8a } from "@polkadot/util-crypto";
133

134
const data = new TextEncoder().encode("Hello SHA");
135

136
// SHA-256
137
const sha256 = sha256AsU8a(data);
138
console.log(sha256.length); // 32 bytes
139

140
// SHA-512
141
const sha512 = sha512AsU8a(data);
142
console.log(sha512.length); // 64 bytes
143
```
144

145
### XXHash
146

147
Fast non-cryptographic hash function for checksums and data integrity.
148

149
```typescript { .api }
150
/**
151
 * XXHash as hex string
152
 * @param data - Data to hash
153
 * @param bitLength - Output length (64, 128, 256)
154
 * @returns Hex-encoded hash
155
 */
156
function xxhashAsHex(data: Uint8Array, bitLength?: 64 | 128 | 256): string;
157

158
/**
159
 * XXHash as Uint8Array
160
 * @param data - Data to hash
161
 * @param bitLength - Output length (64, 128, 256)
162
 * @returns Hash as byte array
163
 */
164
function xxhashAsU8a(data: Uint8Array, bitLength?: 64 | 128 | 256): Uint8Array;
165
```
166

167
**Usage Example:**
168

169
```typescript
170
import { xxhashAsU8a, xxhashAsHex } from "@polkadot/util-crypto";
171

172
const data = new TextEncoder().encode("Fast hash");
173

174
// 64-bit XXHash (default)
175
const hash64 = xxhashAsU8a(data);
176
console.log(hash64.length); // 8 bytes
177

178
// 256-bit XXHash as hex
179
const hash256Hex = xxhashAsHex(data, 256);
180
```
181

182
### HMAC (Hash-based Message Authentication Code)
183

184
Keyed hash functions for message authentication and integrity.
185

186
```typescript { .api }
187
/**
188
 * HMAC-SHA256 as Uint8Array
189
 * @param key - Secret key for HMAC
190
 * @param data - Data to authenticate
191
 * @returns 32-byte HMAC-SHA256
192
 */
193
function hmacSha256AsU8a(key: Uint8Array, data: Uint8Array): Uint8Array;
194

195
/**
196
 * HMAC-SHA512 as Uint8Array
197
 * @param key - Secret key for HMAC
198
 * @param data - Data to authenticate
199
 * @returns 64-byte HMAC-SHA512
200
 */
201
function hmacSha512AsU8a(key: Uint8Array, data: Uint8Array): Uint8Array;
202

203
/**
204
 * HMAC-SHA as Uint8Array
205
 * @param key - Secret key for HMAC
206
 * @param data - Data to authenticate
207
 * @param bitLength - Output length (256 or 512)
208
 * @returns HMAC as byte array
209
 */
210
function hmacShaAsU8a(key: Uint8Array, data: Uint8Array, bitLength?: 256 | 512): Uint8Array;
211
```
212

213
**Usage Example:**
214

215
```typescript
216
import { hmacSha256AsU8a, hmacSha512AsU8a } from "@polkadot/util-crypto";
217

218
const key = new Uint8Array(32); // Secret key
219
const data = new TextEncoder().encode("Authenticated message");
220

221
// HMAC-SHA256
222
const hmac256 = hmacSha256AsU8a(key, data);
223
console.log(hmac256.length); // 32 bytes
224

225
// HMAC-SHA512
226
const hmac512 = hmacSha512AsU8a(key, data);
227
console.log(hmac512.length); // 64 bytes
228
```
229

230
## Hash Algorithm Comparison
231

232
| Algorithm | Security | Speed | Use Case |
233
|-----------|----------|-------|----------|
234
| Blake2 | Cryptographic | Very Fast | Polkadot hashing |
235
| Keccak | Cryptographic | Fast | Ethereum compatibility |
236
| SHA-2 | Cryptographic | Moderate | General purpose |
237
| XXHash | Non-cryptographic | Extremely Fast | Checksums, deduplication |
238
239
## Common Use Cases
240

241
### Data Integrity
242
```typescript
243
import { blake2AsU8a } from "@polkadot/util-crypto";
244

245
// Create checksum for data integrity
246
const data = new Uint8Array([1, 2, 3, 4, 5]);
247
const checksum = blake2AsU8a(data, 128); // 16-byte checksum
248
```
249

250
### Password Hashing
251
```typescript
252
import { blake2AsU8a } from "@polkadot/util-crypto";
253

254
// Hash password with salt
255
const password = new TextEncoder().encode("user-password");
256
const salt = new Uint8Array(16); // Random salt
257
const hashedPassword = blake2AsU8a(password, 256, salt);
258
```
259

260
### Message Authentication
261
```typescript
262
import { hmacSha256AsU8a } from "@polkadot/util-crypto";
263

264
// Authenticate message with HMAC
265
const secretKey = new Uint8Array(32); // Shared secret
266
const message = new TextEncoder().encode("Important message");
267
const mac = hmacSha256AsU8a(secretKey, message);
268
```
269

270
## Security Considerations
271

272
- **Blake2**: Suitable for all cryptographic purposes, preferred in Polkadot
273
- **Keccak**: Used in Ethereum, different from SHA-3 standard
274
- **SHA-2**: Widely adopted, slower than Blake2 but highly secure
275
- **XXHash**: Fast but not cryptographically secure, use only for checksums
276
- **HMAC**: Always use with appropriate key management
277
- **Salt Usage**: Always use random salts for password hashing