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:

``js
const ca = require('win-ca')

rootCAs = []
// Fetch all certificates in PEM format
ca({
format: ca.der2.pem,
ondata: crt => rootCAs.push(crt)
})
`

$3

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).

`js
var list = []
require('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).

`js
const ca = require('win-ca/api')

// Iterate
for (let der of ca({generator: true})) {
// Process(der)
}

// Or thus (Node.js v>=6)
let list = [...ca({generator: true})]

// Or even (Node.js v>=10)
for await(let der of ca({generator: true, async: true})) {
// await Process(der)
}
`

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:

$3

`js
var certificate = ca.der2(format, certificate_in_der_format)
`

Converts certificate from DER
to
format
specified in first parameter.

Function .der2() is curried:

`js
var toPEM = ca.der2(ca.der2.pem)

var pem = toPEM(der)
`

$3

Function .hash() is also curried:

`js
var hasher = ca.hash()
console.log(hasher(der))
`

$3

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:
`js
const ca = require('win-ca') // Fetch certificates and start injecting (old way)

ca.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.

$3

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:
`js
var ca = require('win-ca/api')

ca.exe('/full/path/to/roots.exe')
ca({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

N-API

Current version uses [N-API],
so it can be used in [Node.js versions with N-API support][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
`js
require('win-ca/fallback')
`