0
# Selfsigned
1

2
## Overview
3

4
Selfsigned is a Node.js library for generating self-signed X.509 certificates with private and public key pairs. It provides both synchronous and asynchronous certificate generation capabilities, supports various cryptographic algorithms, and includes options for client certificates and PKCS#7 format output.
5

6
## Package Information
7

8
- **Package Name**: selfsigned
9
- **Package Type**: npm
10
- **Language**: JavaScript
11
- **Installation**: `npm install selfsigned`
12

13
## Core Imports
14

15
```javascript
16
const selfsigned = require('selfsigned');
17
```
18

19
ES Modules:
20

21
```javascript
22
import * as selfsigned from 'selfsigned';
23
// or
24
import { generate } from 'selfsigned';
25
```
26

27
## Basic Usage
28

29
```javascript
30
const selfsigned = require('selfsigned');
31

32
// Basic certificate generation with default attributes
33
const attrs = [{ name: 'commonName', value: 'contoso.com' }];
34
const pems = selfsigned.generate(attrs, { days: 365 });
35

36
console.log(pems.private);  // Private key PEM
37
console.log(pems.public);   // Public key PEM  
38
console.log(pems.cert);     // Certificate PEM
39
console.log(pems.fingerprint); // SHA-1 fingerprint
40
```
41

42
## Capabilities
43

44
### Certificate Generation
45

46
Generates self-signed X.509 certificates with private/public key pairs. Supports both synchronous and asynchronous operation modes.
47

48
```javascript { .api }
49
/**
50
 * Generate self-signed certificate with private/public key pair
51
 * @param attrs - Certificate attributes for subject and issuer
52
 * @param options - Configuration options for certificate generation
53
 * @returns Certificate generation result with PEM-encoded keys and certificate
54
 */
55
function generate(attrs?: CertificateField[], options?: SelfsignedOptions): GenerateResult;
56

57
/**
58
 * Generate self-signed certificate asynchronously
59
 * @param attrs - Certificate attributes for subject and issuer  
60
 * @param options - Configuration options for certificate generation
61
 * @param done - Callback function receiving error and result
62
 */
63
function generate(
64
  attrs?: CertificateField[], 
65
  options?: SelfsignedOptions, 
66
  done?: (err: Error | undefined, result: GenerateResult) => void
67
): void;
68

69
/**
70
 * Generate with callback only (using default attributes)
71
 * @param done - Callback function receiving error and result
72
 */
73
function generate(done: (err: Error | undefined, result: GenerateResult) => void): void;
74

75
/**
76
 * Generate with options and callback (using default attributes)
77
 * @param options - Configuration options for certificate generation
78
 * @param done - Callback function receiving error and result
79
 */
80
function generate(
81
  options: SelfsignedOptions, 
82
  done: (err: Error | undefined, result: GenerateResult) => void
83
): void;
84
```
85

86
**Usage Examples:**
87

88
```javascript
89
// Synchronous generation
90
const pems = selfsigned.generate(attrs, { days: 365, keySize: 2048 });
91

92
// Asynchronous generation
93
selfsigned.generate(attrs, { days: 365 }, function (err, pems) {
94
  if (err) throw err;
95
  console.log(pems);
96
});
97

98
// With default attributes
99
const defaultPems = selfsigned.generate();
100

101
// Callback only with defaults
102
selfsigned.generate(function (err, pems) {
103
  if (err) throw err;
104
  console.log(pems);
105
});
106

107
// Advanced options
108
const advancedPems = selfsigned.generate(null, {
109
  keySize: 2048,
110
  days: 30,
111
  algorithm: 'sha256',
112
  extensions: [{ name: 'basicConstraints', cA: true }],
113
  pkcs7: true,
114
  clientCertificate: true,
115
  clientCertificateCN: 'jdoe'
116
});
117
```
118

119
## Types
120

121
```javascript { .api }
122
/**
123
 * ASN.1 class identifiers for certificate fields
124
 */
125
enum ASN1Class {
126
  UNIVERSAL = 0x00,
127
  APPLICATION = 0x40, 
128
  CONTEXT_SPECIFIC = 0x80,
129
  PRIVATE = 0xc0
130
}
131

132
/**
133
 * Base options for certificate field configuration
134
 */
135
interface CertificateFieldOptions {
136
  /** Field name identifier */
137
  name?: string;
138
  /** Field type */
139
  type?: string;
140
  /** Short name for the field */
141
  shortName?: string;
142
}
143

144
/**
145
 * Certificate attribute field for subject and issuer information
146
 */
147
interface CertificateField extends CertificateFieldOptions {
148
  /** Whether the value is constructed */
149
  valueConstructed?: boolean;
150
  /** ASN.1 value tag class */
151
  valueTagClass?: ASN1Class;
152
  /** Field value (array, string, or other types) */
153
  value?: any[] | string;
154
  /** Certificate extensions */
155
  extensions?: any[];
156
}
157

158
/**
159
 * Configuration options for certificate generation
160
 */
161
interface SelfsignedOptions {
162
  /** Number of days before certificate expiration (default: 365) */
163
  days?: number;
164
  /** Date before which certificate should not be valid (default: now) */
165
  notBeforeDate?: Date;
166
  /** Private key size in bits (default: 1024) */
167
  keySize?: number;
168
  /** Additional certificate extensions */
169
  extensions?: any[];
170
  /** Signature algorithm: 'sha256' or 'sha1' (default: 'sha1') */
171
  algorithm?: string;
172
  /** Include PKCS#7 in output (default: false) */
173
  pkcs7?: boolean;
174
  /** Generate client certificate signed by original key (default: false) */
175
  clientCertificate?: boolean;
176
  /** Client certificate common name (default: 'John Doe jdoe123') */
177
  clientCertificateCN?: string;
178
  /** Client private key size in bits (default: 1024) */
179
  clientCertificateKeySize?: number;
180
  /** Pre-existing key pair to use instead of generating new keys */
181
  keyPair?: {
182
    /** PEM-encoded private key */
183
    privateKey: string;
184
    /** PEM-encoded public key */
185
    publicKey: string;
186
  };
187
}
188

189
/**
190
 * Certificate generation result containing PEM-encoded keys and certificate
191
 */
192
interface GenerateResult {
193
  /** PEM-encoded private key */
194
  private: string;
195
  /** PEM-encoded public key */
196
  public: string;
197
  /** PEM-encoded X.509 certificate */
198
  cert: string;
199
  /** SHA-1 fingerprint of the certificate */
200
  fingerprint: string;
201
  /** Client private key (when clientCertificate: true) */
202
  clientprivate?: string;
203
  /** Client public key (when clientCertificate: true) */
204
  clientpublic?: string;
205
  /** Client certificate (when clientCertificate: true) */
206
  clientcert?: string;
207
  /** PKCS#7 format output (when pkcs7: true) */
208
  pkcs7?: string;
209
  /** Client PKCS#7 format (when both clientCertificate and pkcs7: true) */
210
  clientpkcs7?: string;
211
}
212
```
213

214
## Common Usage Patterns
215

216
### Default Certificate Generation
217

218
```javascript
219
// Generate with minimal configuration
220
const pems = selfsigned.generate();
221
// Uses default attributes: commonName: 'example.org', countryName: 'US', etc.
222
```
223

224
### Custom Certificate Attributes
225

226
```javascript
227
const attrs = [
228
  { name: 'commonName', value: 'localhost' },
229
  { name: 'countryName', value: 'US' },
230
  { name: 'stateOrProvinceName', value: 'California' },
231
  { name: 'localityName', value: 'San Francisco' },
232
  { name: 'organizationName', value: 'My Company' }
233
];
234

235
const pems = selfsigned.generate(attrs, { days: 365 });
236
```
237

238
### Client Certificate Generation
239

240
```javascript
241
const pems = selfsigned.generate(null, { 
242
  clientCertificate: true,
243
  clientCertificateCN: 'client-user',
244
  clientCertificateKeySize: 2048
245
});
246

247
// Result includes: clientprivate, clientpublic, clientcert
248
console.log(pems.clientcert);
249
```
250

251
### High Security Configuration
252

253
```javascript  
254
const pems = selfsigned.generate(attrs, {
255
  keySize: 4096,
256
  algorithm: 'sha256',
257
  days: 30,
258
  extensions: [
259
    { name: 'basicConstraints', cA: false },
260
    { name: 'keyUsage', digitalSignature: true, keyEncipherment: true }
261
  ]
262
});
263
```
264

265
### PKCS#7 Output Format
266

267
```javascript
268
const pems = selfsigned.generate(attrs, { 
269
  pkcs7: true,
270
  clientCertificate: true 
271
});
272

273
// Result includes: pkcs7, clientpkcs7
274
console.log(pems.pkcs7);
275
```
276

277
### Using Pre-existing Key Pairs
278

279
```javascript
280
const existingKeyPair = {
281
  privateKey: '-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----\n',
282
  publicKey: '-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n'
283
};
284

285
const pems = selfsigned.generate(attrs, { 
286
  keyPair: existingKeyPair,
287
  days: 365 
288
});
289

290
// Uses the provided keys instead of generating new ones
291
```