0
# Node-forge
1

2
Node-forge is a comprehensive JavaScript cryptographic library providing pure JavaScript implementations of network transports, cryptography ciphers, PKI, message digests, and utilities. It enables cryptographic operations in both Node.js and browser environments without relying on native crypto libraries.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const forge = require('node-forge');
15
```
16

17
ES6 import (with proper module bundling):
18
```javascript
19
import forge from 'node-forge';
20
```
21

22
All functionality is accessed through the main `forge` object with namespaced modules.
23

24
## Basic Usage
25

26
```javascript
27
const forge = require('node-forge');
28

29
// Generate RSA key pair
30
const keypair = forge.pki.rsa.generateKeyPair(2048);
31

32
// Create and sign a certificate
33
const cert = forge.pki.createCertificate();
34
cert.publicKey = keypair.publicKey;
35
cert.serialNumber = '01';
36
cert.validity.notBefore = new Date();
37
cert.validity.notAfter = new Date();
38
cert.validity.notAfter.setFullYear(cert.validity.notBefore.getFullYear() + 1);
39
cert.subject.attributes.push({name: 'commonName', value: 'example.com'});
40
cert.issuer.attributes = cert.subject.attributes;
41
cert.sign(keypair.privateKey, forge.md.sha256.create());
42

43
// Hash data
44
const md = forge.md.sha256.create();
45
md.update('Hello World');
46
const hash = md.digest().toHex();
47

48
// Encrypt data with AES
49
const key = forge.random.getBytesSync(32); // 256-bit key
50
const iv = forge.random.getBytesSync(16);  // 128-bit IV
51
const cipher = forge.cipher.createCipher('AES-CBC', key);
52
cipher.start({iv: iv});
53
cipher.update(forge.util.createBuffer('secret message'));
54
cipher.finish();
55
const encrypted = cipher.output.getBytes();
56
```
57

58
## Architecture
59

60
Node-forge is organized into specialized modules that extend the main `forge` object:
61

62
- **Core Utilities**: Buffer handling, encoding/decoding, type checking (`forge.util`)
63
- **Symmetric Cryptography**: Block ciphers, modes, and implementations (`forge.cipher`, `forge.aes`)
64
- **Asymmetric Cryptography**: RSA, Ed25519 key generation and operations (`forge.pki.rsa`, `forge.ed25519`)
65
- **Hash Functions**: Message digests and HMAC (`forge.md`, `forge.hmac`)
66
- **PKI Framework**: Certificate handling, PEM/DER conversion (`forge.pki`, `forge.asn1`)
67
- **Protocol Support**: TLS implementation, SSH utilities (`forge.tls`, `forge.ssh`)
68
- **Standards Compliance**: PKCS support, OID registry (`forge.pkcs7`, `forge.oids`)
69

70
## Global Configuration
71

72
```javascript { .api }
73
forge.options = {
74
  usePureJavaScript: boolean; // Force pure JS implementations (default: false)
75
}
76
```
77

78
## Capabilities
79

80
### Utilities and Buffer Management
81

82
Core utility functions for data manipulation, encoding/decoding, and buffer operations essential for cryptographic work.
83

84
```javascript { .api }
85
forge.util.createBuffer(input?: string | ArrayBuffer, encoding?: string): ByteStringBuffer;
86
forge.util.encode64(input: string, maxline?: number): string;
87
forge.util.decode64(input: string): string;
88
forge.util.hexToBytes(hex: string): string;
89
forge.util.bytesToHex(bytes: string): string;
90
```
91

92
[Utilities and Buffers](./utilities.md)
93

94
### Symmetric Encryption
95

96
Block cipher implementations including AES, DES, and RC2 with support for various modes (CBC, CFB, OFB, CTR, GCM).
97

98
```javascript { .api }
99
forge.cipher.createCipher(algorithm: string, key: string | ByteStringBuffer): BlockCipher;
100
forge.cipher.createDecipher(algorithm: string, key: string | ByteStringBuffer): BlockCipher;
101

102
interface BlockCipher {
103
  start(options?: {
104
    iv?: string | ByteStringBuffer;
105
    additionalData?: string; // For GCM mode
106
    tagLength?: number;      // For GCM mode
107
    tag?: string;           // For GCM decryption
108
  }): void;
109
  update(input?: ByteStringBuffer): void;
110
  finish(pad?: function): boolean;
111
  output: ByteStringBuffer;
112
}
113
```
114

115
[Symmetric Encryption](./symmetric-encryption.md)
116

117
### Asymmetric Cryptography
118

119
RSA and Ed25519 implementations for key generation, encryption/decryption, and digital signatures.
120

121
```javascript { .api }
122
forge.pki.rsa.generateKeyPair(
123
  bits: number, 
124
  e?: number, 
125
  options?: object, 
126
  callback?: function
127
): {privateKey: PrivateKey, publicKey: PublicKey} | void;
128

129
interface PublicKey {
130
  encrypt(data: string, scheme?: string, schemeOptions?: object): string;
131
  verify(digest: string, signature: string, scheme?: string): boolean;
132
}
133

134
interface PrivateKey {
135
  decrypt(data: string, scheme?: string, schemeOptions?: object): string;
136
  sign(messageDigest: MessageDigest, scheme?: string): string;
137
}
138
```
139

140
[Asymmetric Cryptography](./asymmetric-cryptography.md)
141

142
### Message Digests and HMAC
143

144
Cryptographic hash functions (MD5, SHA-1, SHA-256, SHA-512) and HMAC for message authentication.
145

146
```javascript { .api }
147
forge.md.sha256.create(): MessageDigest;
148
forge.hmac.create(): HMACContext;
149

150
interface MessageDigest {
151
  start(): MessageDigest;
152
  update(message: string, encoding?: 'utf8' | 'raw'): MessageDigest;
153
  digest(): ByteStringBuffer;
154
}
155

156
interface HMACContext {
157
  start(md: string | MessageDigest, key: string | ByteStringBuffer): void;
158
  update(bytes: string): void;
159
  getMac(): ByteStringBuffer;
160
}
161
```
162

163
[Message Digests and HMAC](./message-digests.md)
164

165
### Public Key Infrastructure
166

167
Certificate management, PEM/DER conversion, and X.509 certificate creation and validation.
168

169
```javascript { .api }
170
forge.pki.createCertificate(): Certificate;
171
forge.pki.privateKeyFromPem(pem: string): PrivateKey;
172
forge.pki.privateKeyToPem(key: PrivateKey, maxline?: number): string;
173
forge.pki.certificateFromPem(pem: string): Certificate;
174
forge.pki.certificateToPem(certificate: Certificate, maxline?: number): string;
175

176
interface Certificate {
177
  serialNumber: string;
178
  validity: {notBefore: Date; notAfter: Date};
179
  subject: {attributes: Array<{name: string; value: string}>};
180
  issuer: {attributes: Array<{name: string; value: string}>};
181
  publicKey: PublicKey;
182
  sign(privateKey: PrivateKey, md: MessageDigest): void;
183
  verify(caStore: Certificate[]): boolean;
184
}
185
```
186

187
[Public Key Infrastructure](./pki.md)
188

189
### ASN.1 Encoding and Decoding
190

191
ASN.1 DER encoding/decoding for working with cryptographic standards and certificate formats.
192

193
```javascript { .api }
194
forge.asn1.create(
195
  tagClass: number, 
196
  type: number, 
197
  constructed: boolean, 
198
  value: any
199
): ASN1;
200
forge.asn1.fromDer(bytes: string | ByteStringBuffer): ASN1;
201
forge.asn1.toDer(obj: ASN1): ByteStringBuffer;
202

203
interface ASN1 {
204
  tagClass: number;
205
  type: number;
206
  constructed: boolean;
207
  value: any;
208
}
209
```
210

211
[ASN.1 Encoding](./asn1.md)
212

213
### PKCS Standards
214

215
Implementation of PKCS standards including PKCS#1 (RSA), PKCS#7 (CMS), and PKCS#12 (key stores).
216

217
```javascript { .api }
218
forge.pkcs7.createSignedData(): PKCS7SignedData;
219
forge.pkcs7.messageFromPem(pem: string): PKCS7Message;
220
forge.pkcs12.toPkcs12Asn1(key: PrivateKey, cert: Certificate, password: string): ASN1;
221
```
222

223
[PKCS Standards](./pkcs.md)
224

225
### Random Number Generation
226

227
Secure random number generation for cryptographic operations including key generation and IV creation.
228

229
```javascript { .api }
230
forge.random.getBytes(count: number, callback?: function): string;
231
forge.random.getBytesSync(count: number): string;
232
```
233

234
[Random Number Generation](./random.md)
235

236
### TLS Implementation
237

238
Complete TLS client and server implementation for secure network communications.
239

240
```javascript { .api }
241
forge.tls.createConnection(options: {
242
  server?: boolean;
243
  sessionId?: string;
244
  caStore?: Array<Certificate>;
245
  cipherSuites?: Array<object>;
246
  connected?: function;
247
  getCertificate?: function;
248
  getPrivateKey?: function;
249
}): TLSConnection;
250
```
251

252
[TLS Implementation](./tls.md)
253

254
### Logging System
255

256
Cross-browser logging system with configurable log levels and multiple output targets.
257

258
```javascript { .api }
259
forge.log.error(category: string, message: string, ...args: any[]): void;
260
forge.log.warning(category: string, message: string, ...args: any[]): void;
261
forge.log.info(category: string, message: string, ...args: any[]): void;
262
forge.log.debug(category: string, message: string, ...args: any[]): void;
263
forge.log.verbose(category: string, message: string, ...args: any[]): void;
264
forge.log.makeLogger(logFunction: function): Logger;
265
```
266

267
[Logging System](./logging.md)
268

269
### Web Form Utilities
270

271
jQuery-based utilities for manipulating web forms and serializing form data to JSON objects.
272

273
```javascript { .api }
274
forge.form.serialize(input: jQuery, sep?: string, dict?: object): object;
275
```
276

277
[Web Form Utilities](./web-forms.md)
278

279
### Network and HTTP Client
280

281
HTTP client implementation with TLS support, cookie management, and XMLHttpRequest interface.
282

283
```javascript { .api }
284
forge.http.createClient(options: object): HTTPClient;
285
forge.xhr.create(options?: object): XMLHttpRequest;
286
forge.xhr.init(options: object): void;
287
```
288

289
[Network and HTTP](./network-http.md)
290

291
## Common Types
292

293
```javascript { .api }
294
interface ByteStringBuffer {
295
  putByte(byte: number): ByteStringBuffer;
296
  putBytes(bytes: string): ByteStringBuffer;
297
  putString(str: string): ByteStringBuffer;
298
  getByte(): number;
299
  getBytes(count?: number): string;
300
  length(): number;
301
  isEmpty(): boolean;
302
  toHex(): string;
303
  toString(): string;
304
}
305

306
interface MessageDigest {
307
  algorithm: string;
308
  blockLength: number;
309
  digestLength: number;
310
  start(): MessageDigest;
311
  update(message: string, encoding?: string): MessageDigest;
312
  digest(): ByteStringBuffer;
313
}
314
```