@peculiar/x509

• About
• Installation
• Documentation
• Usage
  • Browser
  • Set crypto provider for Node.js
  • Create a self-signed certificate
  • Parse a X509 certificate
  • Create a PKCS#10 certificate request
  • Decoded X509 certificate
  • Build a certificate chain
  • Export a list of X509 certificates to PKCS#7 format

About

@peculiar/x509 is an easy to use TypeScript/Javascript library based on @peculiar/asn1-schema that makes generating X.509 Certificates and Certificate Requests as well as validating certificate chains easy.

Installation

npm install @peculiar/x509

Documentation

https://peculiarventures.github.io/x509/

Usage

Browser

Every release of @peculiar/x509 will have new build of ./build/x509.js for use in the browser. To get access to module classes use x509 global variable.

WARN: We recommend hosting and controlling your own copy for security reasons

1<script src="https://unpkg.com/@peculiar/x509"></script>

A simple web application examples

• Generate X509 certificate
• Generate PKCS#10 certificate request

Set crypto provider for Node.js

In some cases you may want to use a different cryptographic implementation, for example when you want to work with an object that supports a cryptographic algorithm not supported by the platform you are on.

In these cases you can set a custom provider, these providers need to be compatible with the WebCrypto API, for example on NodeJS you can use @peculiar/webcrypto to allow @peculiar/x509 to work the same as it does in browser!

1import * as x509 from "@peculiar/x509";
2import { Crypto } from "@peculiar/webcrypto";
3
4const crypto = new Crypto();
5x509.cryptoProvider.set(crypto);

Create a self-signed certificate

1const alg = {
2  name: "RSASSA-PKCS1-v1_5",
3  hash: "SHA-256",
4  publicExponent: new Uint8Array([1, 0, 1]),
5  modulusLength: 2048,
6};
7const keys = await crypto.subtle.generateKey(alg, false, ["sign", "verify"]);
8const cert = await x509.X509CertificateGenerator.createSelfSigned({
9  serialNumber: "01",
10  name: "CN=Test",
11  notBefore: new Date("2020/01/01"),
12  notAfter: new Date("2020/01/02"),
13  signingAlgorithm: alg,
14  keys,
15  extensions: [
16    new x509.BasicConstraintsExtension(true, 2, true),
17    new x509.ExtendedKeyUsageExtension(["1.2.3.4.5.6.7", "2.3.4.5.6.7.8"], true),
18    new x509.KeyUsagesExtension(x509.KeyUsageFlags.keyCertSign | x509.KeyUsageFlags.cRLSign, true),
19    await x509.SubjectKeyIdentifierExtension.create(keys.publicKey),
20  ]
21});
22
23console.log(cert.toString("pem")); // Certificate in PEM format

Parse a x509 certificate

1const base64 = "MIIDljCCAn6gAwIBAgIOSETcxtRwD...S+kAFXIwugUGYEnTWp0m5bAn5NlD314IEOg4mnS8Q==";
2
3const cert = new x509.X509Certificate(base64);
4console.log(cert.subject); // CN=Test, O=PeculiarVentures LLC

Create a PKCS#10 certificate request

1const alg = {
2  name: "ECDSA",
3  namedCurve: "P-384",
4  hash: "SHA-384",
5}
6const keys = await crypto.subtle.generateKey(alg, false, ["sign", "verify"]);
7const csr = await x509.Pkcs10CertificateRequestGenerator.create({
8  name: "CN=Test",
9  keys,
10  signingAlgorithm: alg,
11  extensions: [
12    new x509.KeyUsagesExtension(x509.KeyUsageFlags.digitalSignature | x509.KeyUsageFlags.keyEncipherment),
13  ],
14  attributes: [
15    new x509.ChallengePasswordAttribute("password"),
16  ]
17});
18
19console.log(csr.toString("base64")); // Certificate request in Base64 format

Decoded X509 certificate

1X509Certificate {
2  rawData: ArrayBuffer {
3    [Uint8Contents]: <30 82 02 fc 30 82 01 e4 a0 03 02 01 02 02 01 01 30 0d 06 09 2a 86 48 86 f7 0d 01 01 0b 05 00 30 0f 31 0d 30 0b 06 03 55 04 03 13 04 54 65 73 74 30 1e 17 0d 31 39 31 32 33 31 32 31 30 30 30 30 5a 17 0d 32 30 30 31 30 31 32 31 30 30 30 30 5a 30 0f 31 0d 30 0b 06 03 55 04 03 13 04 54 65 73 74 30 82 01 ... 668 more bytes>,
4    byteLength: 768
5  },
6  tbs: ArrayBuffer {
7    [Uint8Contents]: <30 82 01 e4 a0 03 02 01 02 02 01 01 30 0d 06 09 2a 86 48 86 f7 0d 01 01 0b 05 00 30 0f 31 0d 30 0b 06 03 55 04 03 13 04 54 65 73 74 30 1e 17 0d 31 39 31 32 33 31 32 31 30 30 30 30 5a 17 0d 32 30 30 31 30 31 32 31 30 30 30 30 5a 30 0f 31 0d 30 0b 06 03 55 04 03 13 04 54 65 73 74 30 82 01 22 30 0d 06 ... 388 more bytes>,
8    byteLength: 488
9  },
10  serialNumber: '01',
11  subject: 'CN=Test',
12  issuer: 'CN=Test',
13  signatureAlgorithm: { name: 'RSASSA-PKCS1-v1_5', hash: { name: 'SHA-256' } },
14  signature: ArrayBuffer {
15    [Uint8Contents]: <2e 78 fb 4b f6 c8 a1 9d b4 d1 8b 22 80 20 c1 68 46 39 a6 11 d1 a9 7a 13 03 8d 1e 0e 5e 87 b5 33 2a ba 44 1b 96 6d 91 e7 fd c0 ce b7 93 fe e4 df d3 d0 57 7c 9a eb 7e 3e 8b ed c6 07 ad 80 df fd 8f f7 ce 26 07 db 0e 9f af e6 cb 70 02 2d 17 9f f5 c1 0d ef d6 cf 1d ec 78 a0 dd 5d 46 2a 60 08 71 74 2c 26 ... 156 more bytes>,
16    byteLength: 256
17  },
18  notBefore: 2019-12-31T21:00:00.000Z,
19  notAfter: 2020-01-01T21:00:00.000Z,
20  extensions: Extensions(4) [
21    BasicConstraintsExtension {
22      rawData: [ArrayBuffer],
23      type: '2.5.29.19',
24      critical: true,
25      value: [ArrayBuffer],
26      ca: true,
27      pathLength: 2
28    },
29    ExtendedKeyUsageExtension {
30      rawData: [ArrayBuffer],
31      type: '2.5.29.37',
32      critical: true,
33      value: [ArrayBuffer],
34      usages: [ExtendedKeyUsage]
35    },
36    KeyUsagesExtension {
37      rawData: [ArrayBuffer],
38      type: '2.5.29.15',
39      critical: true,
40      value: [ArrayBuffer],
41      usages: 96
42    },
43    SubjectKeyIdentifierExtension {
44      rawData: [ArrayBuffer],
45      type: '2.5.29.14',
46      critical: false,
47      value: [ArrayBuffer],
48      keyId: 'f525754650a3dee83f8bd777ee3b53ecc2c8d726'
49    }
50  ],
51  publicKey: PublicKey {
52    rawData: ArrayBuffer {
53      [Uint8Contents]: <30 82 01 22 30 0d 06 09 2a 86 48 86 f7 0d 01 01 01 05 00 03 82 01 0f 00 30 82 01 0a 02 82 01 01 00 b6 f4 f1 cf dd 26 a1 23 45 b6 6e 4e ec 3e 20 8a 3f 90 ec 84 46 49 87 a2 05 c5 eb da ac 84 37 eb a3 bf 46 b5 8e 82 75 25 8a 80 19 10 79 13 c0 13 6c 29 df 56 44 1c ec f8 7b 34 0a f2 13 41 b5 53 98 e1 f5 ... 194 more bytes>,
54      byteLength: 294
55    },
56    algorithm: {
57      name: 'RSASSA-PKCS1-v1_5',
58      publicExponent: [Uint8Array],
59      modulusLength: 2048
60    }
61  }
62}

Build a certificate chain

1const chain = new x509.X509ChainBuilder({
2  certificates: [
3    new x509.X509Certificate(raw1),
4    new x509.X509Certificate(raw2),
5    // ...
6    new x509.X509Certificate(rawN),
7  ],
8});
9
10const cert = x509.X509Certificate(raw);
11const items = await chain.build(cert);
12console.log(items); // [ X509Certificate, X509Certificate, X509Certificate ]

Export a list of X509 certificates to PKCS#7 format

1const certs = new x509.X509Certificates([
2  new x509.X509Certificate("MIIDljCCAn6gAwIBAgIOSETcxtRwD...S+kAFXIwugUGYEnTWp0m5bAn5NlD314IEOg4mnS8Q=="),
3  new x509.X509Certificate("MIIDljCCAn6gAwIBAgIOSETcxtRwD...w8Y/o+hk3QzNBVa3ZUvzDhVAmamQflvw3lXMm/JG4U="),
4]);
5
6console.log(certs.export("base64")); // "MIICTAYJKoZIhvcNAQcCoIICPTCCAjkCAQAxADACBgCgggIq...F7EZPNo3pjbfznpIilRMRrmwf5dkgCdSKDdE94xAA==");