0
# Security
1

2
Comprehensive security system supporting multiple authentication mechanisms for enterprise SOAP integration, including HTTP authentication, SSL certificates, and WS-Security standards.
3

4
## Capabilities
5

6
### Basic Authentication
7

8
HTTP Basic Authentication using username and password credentials.
9

10
```typescript { .api }
11
/**
12
 * HTTP Basic Authentication security handler
13
 * @param username - Username for authentication
14
 * @param password - Password for authentication  
15
 * @param defaults - Optional default options
16
 */
17
class BasicAuthSecurity implements ISecurity {
18
  constructor(username: string, password: string, defaults?: any);
19
  
20
  addOptions?(options: any): void;
21
  toXML?(): string;
22
  addHeaders?(headers: IHeaders): void;
23
  postProcess?(xml: any, envelopeKey: any): string;
24
}
25
```
26

27
**Usage Examples:**
28

29
```typescript
30
import { createClientAsync, BasicAuthSecurity } from "soap";
31

32
const client = await createClientAsync("http://example.com/service.wsdl");
33

34
// Set Basic Auth security
35
const basicAuth = new BasicAuthSecurity("username", "password");
36
client.setSecurity(basicAuth);
37

38
// All subsequent requests will include Basic Auth header
39
const result = await client.SomeMethodAsync({ param: "value" });
40
```
41

42
### Bearer Token Authentication
43

44
Bearer token authentication for OAuth and API key scenarios.
45

46
```typescript { .api }
47
/**
48
 * Bearer Token authentication security handler
49
 * @param token - Bearer token string
50
 * @param defaults - Optional default options
51
 */
52
class BearerSecurity implements ISecurity {
53
  constructor(token: string, defaults?: any);
54
  
55
  addOptions?(options: any): void;
56
  toXML?(): string;
57
  addHeaders?(headers: IHeaders): void;
58
  postProcess?(xml: any, envelopeKey: any): string;
59
}
60
```
61

62
**Usage Examples:**
63

64
```typescript
65
import { BearerSecurity } from "soap";
66

67
// Using OAuth token
68
const bearerAuth = new BearerSecurity("your-oauth-token-here");
69
client.setSecurity(bearerAuth);
70

71
// Using API key as bearer token
72
const apiKeyAuth = new BearerSecurity("api-key-12345");
73
client.setSecurity(apiKeyAuth);
74
```
75

76
### SSL Client Certificate Authentication
77

78
SSL client certificate authentication using PEM format certificates.
79

80
```typescript { .api }
81
/**
82
 * SSL Client Certificate (PEM) authentication security handler
83
 * @param key - Private key in PEM format
84
 * @param cert - Certificate in PEM format
85
 * @param ca - Certificate Authority certificate (optional)
86
 * @param defaults - Optional default options
87
 */
88
class ClientSSLSecurity implements ISecurity {
89
  constructor(key: string | Buffer, cert: string | Buffer, ca?: string | Buffer | Array<string | Buffer>, defaults?: any);
90
  
91
  addOptions?(options: any): void;
92
  toXML?(): string;
93
  addHeaders?(headers: IHeaders): void;
94
  postProcess?(xml: any, envelopeKey: any): string;
95
}
96
```
97

98
**Usage Examples:**
99

100
```typescript
101
import { ClientSSLSecurity } from "soap";
102
import * as fs from "fs";
103

104
// Load certificate files
105
const key = fs.readFileSync("client-key.pem");
106
const cert = fs.readFileSync("client-cert.pem");
107
const ca = fs.readFileSync("ca-cert.pem");
108

109
const sslSecurity = new ClientSSLSecurity(key, cert, ca);
110
client.setSecurity(sslSecurity);
111
```
112

113
### SSL Client Certificate Authentication (PFX)
114

115
SSL client certificate authentication using PFX/PKCS#12 format certificates.
116

117
```typescript { .api }
118
/**
119
 * SSL Client Certificate (PFX) authentication security handler
120
 * @param pfx - PFX certificate data
121
 * @param passphrase - Passphrase for PFX certificate
122
 * @param defaults - Optional default options
123
 */
124
class ClientSSLSecurityPFX implements ISecurity {
125
  constructor(pfx: string | Buffer, passphrase: string, defaults?: any);
126
  
127
  addOptions?(options: any): void;
128
  toXML?(): string;
129
  addHeaders?(headers: IHeaders): void;
130
  postProcess?(xml: any, envelopeKey: any): string;
131
}
132
```
133

134
**Usage Examples:**
135

136
```typescript
137
import { ClientSSLSecurityPFX } from "soap";
138
import * as fs from "fs";
139

140
const pfxData = fs.readFileSync("client-cert.pfx");
141
const pfxSecurity = new ClientSSLSecurityPFX(pfxData, "certificate-password");
142
client.setSecurity(pfxSecurity);
143
```
144

145
### WS-Security Username Token
146

147
WS-Security Username Token authentication with digest or plaintext password.
148

149
```typescript { .api }
150
/**
151
 * WS-Security Username Token authentication security handler
152
 * @param username - Username for authentication
153
 * @param password - Password for authentication
154
 * @param options - WS-Security options (can be string for password type or full options object)
155
 */
156
class WSSecurity implements ISecurity {
157
  constructor(username: string, password: string, options?: string | IWSSecurityOptions);
158
  
159
  toXML(): string;
160
}
161

162
interface IWSSecurityOptions {
163
  /** Password type: 'PasswordDigest' or 'PasswordText' */
164
  passwordType?: string;
165
  /** Whether to add timestamps */
166
  hasTimeStamp?: boolean;
167
  /** Whether to add nonce */
168
  hasNonce?: boolean;
169
  /** Whether to add token creation time */
170
  hasTokenCreated?: boolean;
171
  /** Actor attribute for SOAP 1.1 */
172
  actor?: string;
173
  /** mustUnderstand attribute */
174
  mustUnderstand?: any;
175
  /** Envelope key for SOAP envelope */
176
  envelopeKey?: string;
177
}
178
```
179

180
**Usage Examples:**
181

182
```typescript
183
import { WSSecurity } from "soap";
184

185
// Basic WS-Security with password digest
186
const wsSecurity = new WSSecurity("username", "password", {
187
  passwordType: 'PasswordDigest',
188
  hasTimeStamp: true,
189
  hasNonce: true
190
});
191
client.setSecurity(wsSecurity);
192

193
// WS-Security with plaintext password
194
const wsSecurityPlain = new WSSecurity("username", "password", {
195
  passwordType: 'PasswordText'
196
});
197
client.setSecurity(wsSecurityPlain);
198
```
199

200
### WS-Security with X.509 Certificate
201

202
WS-Security authentication using X.509 certificates for message signing.
203

204
```typescript { .api }
205
/**
206
 * WS-Security with X.509 Certificate authentication security handler
207
 * @param privatePEM - Private key in PEM format
208
 * @param publicP12PEM - Public certificate in PEM format
209
 * @param password - Certificate password
210
 * @param options - Certificate security options
211
 */
212
class WSSecurityCert implements ISecurity {
213
  constructor(privatePEM: any, publicP12PEM: any, password: any, options?: IWSSecurityCertOptions);
214
  
215
  postProcess(xml: string, envelopeKey: string): string;
216
}
217

218
interface IWSSecurityCertOptions {
219
  /** Whether to add timestamps */
220
  hasTimeStamp?: boolean;
221
  /** Signature transformation algorithms */
222
  signatureTransformations?: string[];
223
  /** Signature algorithm */
224
  signatureAlgorithm?: string;
225
  /** Digest algorithm */
226
  digestAlgorithm?: string;
227
  /** Additional references to sign */
228
  additionalReferences?: string[];
229
  /** XML signer options */
230
  signerOptions?: IXmlSignerOptions;
231
  /** References to exclude from signing */
232
  excludeReferencesFromSigning?: string[];
233
}
234

235
interface IXmlSignerOptions {
236
  /** XML signature prefix */
237
  prefix?: string;
238
  /** Additional attributes */
239
  attrs?: { [key: string]: string };
240
  /** Existing namespace prefixes */
241
  existingPrefixes?: { [key: string]: string };
242
  /** ID mode for WS-Security */
243
  idMode?: 'wssecurity';
244
}
245
```
246

247
**Usage Examples:**
248

249
```typescript
250
import { WSSecurityCert } from "soap";
251
import * as fs from "fs";
252

253
const privateKey = fs.readFileSync("private-key.pem");
254
const publicCert = fs.readFileSync("public-cert.pem");
255

256
const certSecurity = new WSSecurityCert(privateKey, publicCert, "cert-password");
257
client.setSecurity(certSecurity);
258
```
259

260
### WS-Security Certificate with Token
261

262
Combined WS-Security implementation with both certificate and username token.
263

264
```typescript { .api }
265
/**
266
 * WS-Security combining certificate and username token
267
 * @param privatePEM - Private key in PEM format
268
 * @param publicP12PEM - Public certificate in PEM format
269
 * @param password - Certificate password
270
 * @param options - Security configuration options
271
 */
272
class WSSecurityCertWithToken implements ISecurity {
273
  constructor(privatePEM: string | Buffer, publicP12PEM: string | Buffer, password: string, options?: any);
274
  
275
  addOptions?(options: any): void;
276
  toXML?(): string;
277
  addHeaders?(headers: IHeaders): void;
278
  postProcess?(xml: any, envelopeKey: any): string;
279
}
280
```
281

282
### Enhanced WS-Security
283

284
Enhanced WS-Security implementation with additional cryptographic features.
285

286
```typescript { .api }
287
/**
288
 * Enhanced WS-Security with advanced certificate handling
289
 * @param privatePEM - Private key in PEM format
290
 * @param publicP12PEM - Public certificate in PEM format
291
 * @param password - Certificate password
292
 * @param options - Advanced security options
293
 */
294
class WSSecurityPlusCert implements ISecurity {
295
  constructor(privatePEM: string | Buffer, publicP12PEM: string | Buffer, password: string, options?: any);
296
  
297
  addOptions?(options: any): void;
298
  toXML?(): string;
299
  addHeaders?(headers: IHeaders): void;
300
  postProcess?(xml: any, envelopeKey: any): string;
301
}
302
```
303

304
### NTLM Authentication
305

306
NTLM (NT LAN Manager) authentication for Windows-based SOAP services.
307

308
```typescript { .api }
309
/**
310
 * NTLM authentication security handler
311
 * @param username - Windows username
312
 * @param password - Windows password
313
 * @param domain - Windows domain (optional)
314
 * @param workstation - Workstation name (optional)
315
 */
316
class NTLMSecurity implements ISecurity {
317
  constructor(username: string, password: string, domain?: string, workstation?: string);
318
  
319
  addOptions?(options: any): void;
320
  toXML?(): string;
321
  addHeaders?(headers: IHeaders): void;
322
  postProcess?(xml: any, envelopeKey: any): string;
323
}
324
```
325

326
**Usage Examples:**
327

328
```typescript
329
import { NTLMSecurity } from "soap";
330

331
// NTLM with domain
332
const ntlmSecurity = new NTLMSecurity("username", "password", "DOMAIN");
333
client.setSecurity(ntlmSecurity);
334

335
// NTLM without domain
336
const ntlmLocal = new NTLMSecurity("username", "password");
337
client.setSecurity(ntlmLocal);
338
```
339

340
## Security Interface
341

342
All security implementations follow a common interface for consistent integration.
343

344
```typescript { .api }
345
/**
346
 * Common interface for all security handlers
347
 */
348
interface ISecurity {
349
  /** Add security-specific options to HTTP request */
350
  addOptions?(options: any): void;
351
  /** Generate security XML for SOAP header */
352
  toXML?(): string;
353
  /** Add security-specific HTTP headers */
354
  addHeaders?(headers: IHeaders): void;
355
  /** Post-process SOAP envelope with security information */
356
  postProcess?(xml: any, envelopeKey: any): string;
357
}
358

359
interface IHeaders {
360
  [key: string]: any;
361
}
362
```
363

364
## Utility Functions
365

366
### Password Digest Generation
367

368
Generate WS-Security password digests for username token authentication.
369

370
```typescript { .api }
371
/**
372
 * Generate WS-Security password digest
373
 * @param nonce - Random nonce value (base64 encoded)
374
 * @param created - Timestamp when token was created (ISO 8601)
375
 * @param password - Plaintext password
376
 * @returns Base64 encoded password digest
377
 */
378
function passwordDigest(nonce: string, created: string, password: string): string;
379
```
380

381
**Usage Examples:**
382

383
```typescript
384
import { passwordDigest } from "soap";
385

386
const nonce = Buffer.from(Math.random().toString()).toString('base64');
387
const created = new Date().toISOString();
388
const digest = passwordDigest(nonce, created, "mypassword");
389

390
console.log('Password Digest:', digest);
391

392
// Manual digest calculation for custom WS-Security implementations
393
const customNonce = Buffer.from('random-nonce-value').toString('base64');
394
const customCreated = new Date().toISOString();
395
const customDigest = passwordDigest(customNonce, customCreated, "secretpassword");
396

397
// Use in custom security header
398
const customSecurityHeader = {
399
  'wsse:UsernameToken': {
400
    'wsse:Username': 'myuser',
401
    'wsse:Password': {
402
      $: { Type: 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest' },
403
      _: customDigest
404
    },
405
    'wsse:Nonce': { $: { EncodingType: 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary' }, _: customNonce },
406
    'wsu:Created': customCreated
407
  }
408
};
409
```
410

411
## Advanced Security Features
412

413
### Custom Security Handlers
414

415
Create custom security implementations by implementing the ISecurity interface.
416

417
```typescript
418
class CustomSecurity implements ISecurity {
419
  constructor(private apiKey: string) {}
420
  
421
  addHeaders(headers: IHeaders): void {
422
    headers['X-API-Key'] = this.apiKey;
423
    headers['X-Custom-Auth'] = 'custom-token';
424
  }
425
  
426
  addOptions(options: any): void {
427
    // Add custom HTTP options
428
    options.timeout = 30000;
429
  }
430
}
431

432
// Use custom security
433
const customSecurity = new CustomSecurity("api-key-123");
434
client.setSecurity(customSecurity);
435
```
436

437
### Multiple Security Layers
438

439
Combine multiple security mechanisms by chaining security handlers.
440

441
```typescript
442
// Note: Only one security handler can be active at a time per client
443
// For multiple security requirements, implement a composite security handler
444

445
class CompositeSecurity implements ISecurity {
446
  constructor(
447
    private basicAuth: BasicAuthSecurity,
448
    private customHeaders: any
449
  ) {}
450
  
451
  addHeaders(headers: IHeaders): void {
452
    this.basicAuth.addHeaders?.(headers);
453
    Object.assign(headers, this.customHeaders);
454
  }
455
  
456
  addOptions(options: any): void {
457
    this.basicAuth.addOptions?.(options);
458
  }
459
}
460
```