0
# Certificate Management
1

2
TLS certificate generation and management utilities for HTTPS interception, including CA certificate creation and SPKI fingerprint generation.
3

4
## Capabilities
5

6
### Certificate Generation
7

8
Utilities for generating CA certificates and managing TLS infrastructure.
9

10
```typescript { .api }
11
/**
12
 * Generate a Certificate Authority (CA) certificate and private key.
13
 * Used for creating custom CAs for HTTPS interception and testing.
14
 */
15
function generateCACertificate(options?: CAOptions): Promise<{key: string, cert: string}>;
16

17
/**
18
 * Generate SPKI (Subject Public Key Info) fingerprint from a certificate.
19
 * Used for certificate pinning and verification in tests.
20
 */
21
function generateSPKIFingerprint(certPem: string): Promise<string>;
22

23
interface CAOptions {
24
  /**
25
   * Key length in bits for the generated private key.
26
   * Default: 2048
27
   */
28
  keyLength?: number;
29
  
30
  /**
31
   * Common Name (CN) for the certificate subject.
32
   * Default: "Mockttp CA"
33
   */
34
  commonName?: string;
35
  
36
  /**
37
   * Organization Name (O) for the certificate subject.
38
   * Default: "Mockttp"
39
   */
40
  organizationName?: string;
41
  
42
  /**
43
   * Country Name (C) for the certificate subject.
44
   * Default: "US"
45
   */
46
  countryName?: string;
47
  
48
  /**
49
   * Certificate validity period in days.
50
   * Default: 3650 (10 years)
51
   */
52
  validityDays?: number;
53
}
54
```
55

56
**Usage Examples:**
57

58
```typescript
59
import { generateCACertificate, generateSPKIFingerprint, getLocal } from "mockttp";
60

61
// Generate a custom CA certificate
62
const ca = await generateCACertificate({
63
  keyLength: 4096,
64
  commonName: "Test CA",
65
  organizationName: "My Test Suite",
66
  countryName: "GB",
67
  validityDays: 365
68
});
69

70
console.log("CA Certificate:", ca.cert);
71
console.log("CA Private Key:", ca.key);
72

73
// Generate SPKI fingerprint for certificate pinning
74
const spkiFingerprint = await generateSPKIFingerprint(ca.cert);
75
console.log("SPKI Fingerprint:", spkiFingerprint);
76

77
// Use the generated CA with Mockttp
78
const mockServer = getLocal({
79
  https: {
80
    ca: ca.cert,
81
    key: ca.key
82
  }
83
});
84

85
await mockServer.start();
86
```
87

88
### Certificate Configuration Types
89

90
Types for configuring certificate usage in Mockttp servers.
91

92
```typescript { .api }
93
/**
94
 * Base type for PEM-formatted certificate data.
95
 */
96
type PEM = string;
97

98
/**
99
 * Certificate configuration using string/Buffer data.
100
 */
101
interface CertDataOptions {
102
  /**
103
   * CA certificate in PEM format for signing generated certificates.
104
   */
105
  ca?: string | Buffer;
106
  
107
  /**
108
   * Server certificate in PEM format.
109
   */
110
  cert?: string | Buffer;
111
  
112
  /**
113
   * Private key in PEM format corresponding to the certificate.
114
   */
115
  key?: string | Buffer;
116
}
117

118
/**
119
 * Certificate configuration using file paths.
120
 */
121
interface CertPathOptions {
122
  /**
123
   * Path to CA certificate file.
124
   */
125
  caPath?: string;
126
  
127
  /**
128
   * Path to server certificate file.
129
   */
130
  certPath?: string;
131
  
132
  /**
133
   * Path to private key file.
134
   */
135
  keyPath?: string;
136
}
137

138
/**
139
 * Combined certificate options (used in MockttpHttpsOptions).
140
 */
141
type CertificateOptions = CertDataOptions & CertPathOptions & {
142
  /**
143
   * Key length for auto-generated certificates.
144
   * Default: 2048
145
   */
146
  keyLength?: number;
147
};
148
```
149

150
### HTTPS Configuration
151

152
Complete HTTPS configuration options for Mockttp servers.
153

154
```typescript { .api }
155
interface MockttpHttpsOptions extends CertificateOptions {
156
  /**
157
   * Default domain name for TLS connections without SNI.
158
   * Used when clients don't specify a hostname via Server Name Indication.
159
   */
160
  defaultDomain?: string;
161
  
162
  /**
163
   * Hostnames to pass through without TLS interception.
164
   * These connections will be forwarded directly to the upstream server.
165
   * Wildcards are supported using URLPattern syntax: '*.example.com'
166
   */
167
  tlsPassthrough?: Array<{hostname: string}>;
168
  
169
  /**
170
   * Only intercept TLS for these hostnames, pass through all others.
171
   * Mutually exclusive with tlsPassthrough - setting both will throw an error.
172
   * Wildcards are supported using URLPattern syntax: '*.example.com'
173
   */
174
  tlsInterceptOnly?: Array<{hostname: string}>;
175
  
176
  /**
177
   * TLS server configuration options.
178
   */
179
  tlsServerOptions?: {
180
    /**
181
     * Minimum TLS version to accept.
182
     * Allows tightening or relaxing TLS requirements for testing.
183
     */
184
    minVersion?: 'TLSv1.3' | 'TLSv1.2' | 'TLSv1.1' | 'TLSv1';
185
  };
186
}
187
```
188

189
**Usage Examples:**
190

191
```typescript
192
import { generateCACertificate, getLocal } from "mockttp";
193
import * as fs from "fs";
194

195
// Using generated certificates
196
const ca = await generateCACertificate({
197
  commonName: "Test CA",
198
  keyLength: 2048
199
});
200

201
const mockServer = getLocal({
202
  https: {
203
    ca: ca.cert,
204
    key: ca.key,
205
    defaultDomain: "localhost",
206
    tlsPassthrough: [
207
      { hostname: "*.googleapis.com" },
208
      { hostname: "secure-api.example.com" }
209
    ],
210
    tlsServerOptions: {
211
      minVersion: 'TLSv1.2'
212
    }
213
  }
214
});
215

216
// Using certificate files
217
const mockServerFromFiles = getLocal({
218
  https: {
219
    certPath: "/path/to/server.crt",
220
    keyPath: "/path/to/server.key",
221
    caPath: "/path/to/ca.crt"
222
  }
223
});
224

225
// Mixed configuration
226
const mockServerMixed = getLocal({
227
  https: {
228
    cert: fs.readFileSync("/path/to/server.crt"),
229
    key: fs.readFileSync("/path/to/server.key"),
230
    keyLength: 4096, // For any auto-generated certificates
231
    tlsInterceptOnly: [
232
      { hostname: "api.myapp.com" },
233
      { hostname: "*.internal.myapp.com" }
234
    ]
235
  }
236
});
237
```
238

239
### Certificate Testing Patterns
240

241
Common patterns for testing with certificates:
242

243
**Custom CA Testing**: Generate a custom CA and configure clients to trust it
244
**Certificate Pinning**: Use SPKI fingerprints to test certificate pinning implementations
245
**TLS Version Testing**: Configure minimum TLS versions to test client compatibility
246
**SNI Testing**: Test Server Name Indication handling with multiple hostnames
247
**Certificate Validation**: Test client certificate validation with invalid or expired certificates
248

249
**Example: Testing Certificate Pinning**
250

251
```typescript
252
import { generateCACertificate, generateSPKIFingerprint, getLocal } from "mockttp";
253

254
// Generate a test CA
255
const testCA = await generateCACertificate({
256
  commonName: "Test Certificate Pinning CA"
257
});
258

259
// Get the SPKI fingerprint for pinning
260
const expectedFingerprint = await generateSPKIFingerprint(testCA.cert);
261

262
// Set up mock server with the test CA
263
const mockServer = getLocal({
264
  https: {
265
    ca: testCA.cert,
266
    key: testCA.key
267
  }
268
});
269

270
await mockServer.start();
271

272
// Configure your HTTP client to expect the SPKI fingerprint
273
// and test that it properly validates certificate pins
274
console.log(`Configure client to pin: ${expectedFingerprint}`);
275
```
276

277
**Example: Testing TLS Version Requirements**
278

279
```typescript
280
import { getLocal } from "mockttp";
281

282
// Server that only accepts TLS 1.3
283
const strictServer = getLocal({
284
  https: {
285
    keyLength: 2048,
286
    tlsServerOptions: {
287
      minVersion: 'TLSv1.3'
288
    }
289
  }
290
});
291

292
await strictServer.start();
293

294
// Test that older TLS clients are rejected
295
// while TLS 1.3 clients are accepted
296
```
297

298
**Example: Selective TLS Interception**
299

300
```typescript
301
import { getLocal } from "mockttp";
302

303
// Only intercept specific domains, pass through everything else
304
const selectiveServer = getLocal({
305
  https: {
306
    keyLength: 2048,
307
    tlsInterceptOnly: [
308
      { hostname: "api.myapp.com" },
309
      { hostname: "*.test.myapp.com" }
310
    ]
311
  }
312
});
313

314
await selectiveServer.start();
315

316
// Requests to api.myapp.com and *.test.myapp.com will be intercepted
317
// All other HTTPS traffic will be passed through to real servers
318
await selectiveServer.forGet("https://api.myapp.com/test")
319
  .thenReply(200, "Mocked response");
320

321
// Requests to other domains like google.com will pass through unchanged
322
```
323

324
### Certificate File Formats
325

326
Mockttp supports standard certificate file formats:
327

328
**PEM Format**: Text-based format with BEGIN/END markers, widely supported
329
**Certificate Files**: `.crt`, `.cer`, `.pem` extensions commonly used
330
**Private Key Files**: `.key`, `.pem` extensions commonly used
331
**CA Bundle Files**: Multiple certificates concatenated in PEM format
332

333
All certificate data can be provided as strings, Buffers, or file paths. When using file paths, Mockttp will read the files at server startup time.
334

335
### Certificate Security Notes
336

337
**Testing Only**: Generated certificates are intended for testing and development only
338
**Key Management**: Keep private keys secure and don't commit them to version control
339
**CA Trust**: Only install test CAs in test environments, never in production
340
**Certificate Validation**: Always test both valid and invalid certificate scenarios
341
**Cleanup**: Remove test CAs from system trust stores after testing