First versions of win-ca opened Windows' Trusted Root Certificate Store, fetched certificates, deduplicated them and installed to https.globalAgent.options.ca, so they are automatically used for all requests with Node.js' https module.

But sometimes one needs to get these certificates to do something else. For that case, full featured API was devised. It is the only function with numerous parameters and operation modes, eg:

1const ca = require('win-ca')
2
3rootCAs = []
4// Fetch all certificates in PEM format
5ca({
6  format: ca.der2.pem,
7  ondata: crt => rootCAs.push(crt)
8})

Entry points

win-ca offers three ways of importing:

1. Regular require('win-ca')
2. Fallback require('win-ca/fallback')
3. Pure API require('win-ca/api')

They all export the same API, but differ in initialization:

1. win-ca does fetch certificates from Root store, saves them to disk and makes them available to https module with no effort.

2. win-ca/fallback does the same, but it never uses N-API for fetching certificates, so it should work in all versions of Node.js as well as inside Electron application.

3. win-ca/api does nothing, just exports API, so you decide yourself what to do.

API Parameters

API function may be called with no parameters, but that makes little sense. One should pass it object with some fields, ie:

• format defines representation of certificates to fetch. Available values are:

  Constant	Value	Meaning
  der2.der	0	DER-format (binary, Node's Buffer)
  der2.pem	1	PEM-format (text, Base64-encoded)
  der2.txt	2	PEM-format plus some laconic header
  der2.asn1	3	ASN.1-parsed certificate
  der2.x509	4	Certificate in node-forge format (RSA only!)

  Default value is der.

  See also der2 function below.

• store - which Windows' store to use. Default is Root (ie Trusted Root Certification Authorities).

  Windows has a whole lot of Certificate stores (eg Root, CA, My, TrustedPublisher etc.) One can list certificates from any of them (knowing its name) or several stores at once (using array for store parameter).

  1var list = []
  2require('win-ca/api')({store: ['root', 'ca'], ondata: list})

• unique whether certificates list should be deduplicated. Default is true (no duplicates returned).

  Use {unique: false} to see all certificates in store.

• ondata - callback fired for each certificate found.

  Every certificate will be converted to format and passed as the first (the only) parameter.

  As a syntactic sugar, array can be passed instead of function, it will be populated with certificates.

• onend - callback fired (with no parameters) at the end of retrieval

  Useful for asynchronous invocations, but works in any case.

• fallback - boolean flag, indicating N-API shouldn't be used even if it is available.

  Default value depends on Node.js version (4, 5 and 7 {fallback: true}; modern versions {fallback: false}). It is also true if Electron is detected.

  Finally, if win-ca has been required as win-ca/fallback, default value for this flag is also set to true.

  Note, that one can force N-API by setting {fallback: false}, but if Node.js cannot proceed, exception will be thrown. It can be catched, but Node.js will nevertheless remain in unstable state, so beware.

• async - boolean flag to make retrieval process asynchronous (false by default)

  If true, API call returns immediately, certificates will be fetched later and feed to ondata callback. Finally onend callback will be called.

• generator - boolean flag to emulate ES6 generator (default: false)

  If called with this flag, ES6 iterator object is immediately returned (regular or asynchronous - according to async flag).

  1const ca = require('win-ca/api')
  2
  3// Iterate
  4for (let der of ca({generator: true})) {
  5  // Process(der)
  6}
  7
  8// Or thus (Node.js v>=6)
  9let list = [...ca({generator: true})]
  10
  11// Or even (Node.js v>=10)
  12for await(let der of ca({generator: true, async: true})) {
  13  // await Process(der)
  14}

  Note, that if callbacks are set along with generator flag, they will be also fired.

• inject - how to install certificates (default: false, ie just fetch from store, do not install)

  If set to true, certificated fetched will be also added to https.globalAgent.options.ca (in PEM format, regardless of format parameter), so all subsequent calls to https client methods (https.request, https.get etc.) will silently use them instead of built-in ones.

  If set to '+', new experimental method is used instead: tls.createSecureContext() is patched and fetched certificates are used in addition to built-in ones (and not only for https, but for all secure connections).

  Injection mode can be later changed (or disabled) with .inject() helper function.

• save - how to save certificates to disk (default: false, ie use no I/O at all)

  If set to string, or array of strings, they will be treated as list of candidate folders to save certificates to. First one that exists or can be (recursively) created will be used.

  If no valid folder path found, saving will be silently discarded.

  If {save: true} used, predefined list of folders will be tried:

  • pem folder inside win-ca module itself
  • .local/win-ca/pem folder inside user's profile

  Certificates will be stored into the folder in two formats:

  • Each certificate as separate text file with special file name (mimics behavour of OpenSSL's c_rehash utility) - suitable for SSL_CERT_DIR
  • All certificates in single roots.pem file - suitable for SSL_CERT_FILE

  If win-ca is required not via win-ca/api, it calls itself with {inject: true, save: true} and additionaly sets ca.path field and SSL_CERT_DIR environment variable to the folder with certificates saved.

• onsave - callback called at the end of saving (if save is truthy).

  Path to a folder is passed to callback, or no parameters (undefined) if it has been impossible to save certificates to disk.

Helper functions

Some internal functions are exposed:

der2

1var certificate = ca.der2(format, certificate_in_der_format)

Converts certificate from DER to format specified in first parameter.

Function .der2() is curried:

1var toPEM = ca.der2(ca.der2.pem)
2
3var pem = toPEM(der)

hash

1var hash = ca.hash(version, certificate_in_der_format)

Gives certificate hash (aka X509_NAME_hash), ie 8-character hexadecimal string, derived from certificate subject.

If version (first parameter) is 0, an old algorithm is used (aka X509_NAME_hash_old, used in OpenSSL v0.*), else - the new one (X509_NAME_hash of OpenSSL v1.*).

Function .hash() is also curried:

1var hasher = ca.hash()
2console.log(hasher(der))

inject

1ca.inject(mode)
2// or:
3ca.inject(mode, array_of_certificates)

Manages the way certificates are passed to other modules.

This function is internally called by API when {inject:} parameter used.

First argument (mode) is injection mode:

• false: no injection, built-in certificates are used

• true: put certificates to https.globalAgent.options.ca and use them instead of built-in ones for https module

• '+': new experimental mode: tls.createSecureContext() is patched and certificates are used along with built-in ones. This mode should affect all secure connections, not just https module.

Second parameter (array_of_certificates) is list of certificates to inject. If it is omitted, previous list is used (only inject mode is changed).

For example, simplest way to test new injection mode is:

1const ca = require('win-ca') // Fetch certificates and start injecting (old way)
2
3ca.inject('+') // Switch to new injection mode

Note, that this function should be called before first secure connection is established, since every secure connection populates different caches, that are extremely hard to invalidate. Changing injection mode in the middle of secure communication can lead to unpredictable results.

exe

Applications that use win-ca are sometimes packed / bundled. In this case one should find appropriate place for binary utility roots.exe (used in fallback mode, which is always the case with Electron apps) and then make win-ca to find the binary.

Function .exe() is intended to provide this functionality. You must call it before first invocation of library itself, eg:

1var ca = require('win-ca/api')
2
3ca.exe('/full/path/to/roots.exe')
4ca({fallback: true, inject: true})

.exe() with no parameters switches to default location (inside lib folder). In any case it returns previous path to roots.exe:

console.log(require('win-ca').exe()) // Where is my root.exe?

Legacy API

var ca = require('win-ca')

do.something.with(ca.all(ca.der2.pem))

N-API

Current version uses N-API, so it can be used in Node.js versions with N-API support, i.e. v6 and all versions starting from v8.

Thanks to N-API, it is possible to precompile Windows DLL and save it to package, so no compilation is needed at installation time.

For other Node.js versions (v4, 5 or 7) special fallback utility is called in the background to fetch the list anyway.

If you wish to use this fallback engine (even for modern Node.js), you can

1require('win-ca/fallback')