0
# Cryptographic Operations
1

2
Core cryptographic functionality providing multiple hash algorithms, HMAC generation, and Base64 encoding/decoding with support for URL-safe variants and various input types.
3

4
## Capabilities
5

6
### Hash Function
7

8
Generic hash function supporting multiple algorithms with flexible input types and output formats.
9

10
```typescript { .api }
11
/**
12
 * Hash function supporting multiple algorithms
13
 * @param method - Hash method (md5, sha1, sha256, sha512, etc.)
14
 * @param s - Input value to hash
15
 * @param format - Output format (hex, base64, etc.)
16
 * @returns Hash string in specified format
17
 */
18
function hash(method: string, s: HashInput, format?: BinaryToTextEncoding): string;
19

20
type HashInput = string | Buffer | ArrayBuffer | DataView | object;
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import { hash } from "utility";
27

28
// String input with hex output (default)
29
const hexHash = hash('sha256', 'hello world');
30
// Result: "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
31

32
// Buffer input with base64 output
33
const buffer = Buffer.from('hello world');
34
const base64Hash = hash('md5', buffer, 'base64');
35

36
// Object input (automatically JSON.stringify'd and sorted)
37
const objectHash = hash('sha1', { name: 'test', value: 123 });
38
```
39

40
### MD5 Hash
41

42
MD5 hash function with support for strings, buffers, and objects.
43

44
```typescript { .api }
45
/**
46
 * MD5 hash function
47
 * @param s - Input value to hash
48
 * @param format - Output format (hex or base64), defaults to hex
49
 * @returns MD5 hash string
50
 */
51
function md5(s: HashInput, format?: BinaryToTextEncoding): string;
52
```
53

54
**Usage Examples:**
55

56
```typescript
57
import { md5 } from "utility";
58

59
// Basic string hashing
60
const hash1 = md5("hello world");
61
// Result: "5d41402abc4b2a76b9719d911017c592"
62

63
// Base64 output
64
const hash2 = md5("hello world", "base64");
65
// Result: "XUFAKrxLKna5cZ2REBfFkg=="
66

67
// Buffer input
68
const hash3 = md5(Buffer.from("hello world"));
69

70
// Object input
71
const hash4 = md5({ key: "value", number: 42 });
72
```
73

74
### SHA1 Hash
75

76
SHA1 hash function with support for multiple input types and output formats.
77

78
```typescript { .api }
79
/**
80
 * SHA1 hash function
81
 * @param s - Input value to hash
82
 * @param format - Output format (hex or base64), defaults to hex
83
 * @returns SHA1 hash string
84
 */
85
function sha1(s: HashInput, format?: BinaryToTextEncoding): string;
86
```
87

88
### SHA256 Hash
89

90
SHA256 hash function with support for multiple input types and output formats.
91

92
```typescript { .api }
93
/**
94
 * SHA256 hash function
95
 * @param s - Input value to hash
96
 * @param format - Output format (hex or base64), defaults to hex
97
 * @returns SHA256 hash string
98
 */
99
function sha256(s: HashInput, format?: BinaryToTextEncoding): string;
100
```
101

102
### SHA512 Hash
103

104
SHA512 hash function with support for multiple input types and output formats.
105

106
```typescript { .api }
107
/**
108
 * SHA512 hash function
109
 * @param s - Input value to hash
110
 * @param format - Output format (hex or base64), defaults to hex
111
 * @returns SHA512 hash string
112
 */
113
function sha512(s: HashInput, format?: BinaryToTextEncoding): string;
114
```
115

116
### HMAC Generation
117

118
HMAC (Hash-based Message Authentication Code) generation with configurable algorithms and encoding.
119

120
```typescript { .api }
121
/**
122
 * HMAC algorithm implementation
123
 * @param algorithm - Hash algorithm (sha1, md5, sha256, sha512, etc.)
124
 * @param key - HMAC key to be used
125
 * @param data - Content string or buffer
126
 * @param encoding - Output encoding, defaults to base64
127
 * @returns HMAC digest string
128
 */
129
function hmac(algorithm: string, key: string, data: string | Buffer, encoding?: BinaryToTextEncoding): string;
130
```
131

132
**Usage Examples:**
133

134
```typescript
135
import { hmac } from "utility";
136

137
// Basic HMAC with SHA256
138
const signature = hmac('sha256', 'secret-key', 'message to sign');
139
// Result: base64-encoded HMAC
140

141
// HMAC with hex encoding
142
const hexSignature = hmac('sha1', 'my-key', 'data', 'hex');
143

144
// HMAC with buffer data
145
const bufferSignature = hmac('md5', 'key', Buffer.from('binary data'));
146

147
// Equivalent to bash command:
148
// echo -n "message" | openssl dgst -binary -sha256 -hmac "secret-key" | openssl base64
149
```
150

151
### Base64 Encoding
152

153
Base64 encoding with support for URL-safe variants and multiple input types.
154

155
```typescript { .api }
156
/**
157
 * Base64 encode string or buffer
158
 * @param s - Input string or buffer
159
 * @param urlSafe - Use URL-safe alphabet (- instead of +, _ instead of /)
160
 * @returns Base64 encoded string
161
 */
162
function base64encode(s: string | Buffer, urlSafe?: boolean): string;
163
```
164

165
**Usage Examples:**
166

167
```typescript
168
import { base64encode } from "utility";
169

170
// Basic encoding
171
const encoded = base64encode("hello world");
172
// Result: "aGVsbG8gd29ybGQ="
173

174
// URL-safe encoding
175
const urlSafe = base64encode("hello world", true);
176
// Result: "aGVsbG8gd29ybGQ=" (no difference in this case)
177

178
// Buffer encoding
179
const bufferEncoded = base64encode(Buffer.from("binary data"));
180

181
// URL-safe with special characters
182
const specialChars = base64encode("???", true);
183
// Uses - and _ instead of + and /
184
```
185

186
### Base64 Decoding
187

188
Base64 decoding with support for URL-safe variants and multiple output formats.
189

190
```typescript { .api }
191
/**
192
 * Base64 decode string to string or buffer
193
 * @param encodeStr - Base64 encoded string
194
 * @param urlSafe - Decode URL-safe alphabet
195
 * @param encoding - Output encoding ('utf8', 'buffer', etc.), defaults to utf8
196
 * @returns Decoded string or buffer
197
 */
198
function base64decode(encodeStr: string, urlSafe?: boolean, encoding?: BufferEncoding | 'buffer'): string | Buffer;
199
```
200

201
**Usage Examples:**
202

203
```typescript
204
import { base64decode } from "utility";
205

206
// Basic decoding
207
const decoded = base64decode("aGVsbG8gd29ybGQ=");
208
// Result: "hello world"
209

210
// URL-safe decoding
211
const urlDecoded = base64decode("aGVsbG8gd29ybGQ=", true);
212

213
// Return as buffer
214
const buffer = base64decode("aGVsbG8gd29ybGQ=", false, 'buffer') as Buffer;
215

216
// Specific encoding
217
const latin1 = base64decode("encoded-string", false, 'latin1');
218
```