win-ca
Version:
Get Windows System Root certificates
649 lines (511 loc) • 16.3 kB
Markdown
# win-ca
[](https://ci.appveyor.com/project/ukoloff/win-ca)
[](http://badge.fury.io/js/win-ca)
[](https://github.com/ukoloff/win-ca/actions)
Get Windows System Root certificates for [Node.js].
## Rationale
Unlike [Ruby][], [Node.js][] on Windows **allows**
HTTPS requests out-of-box.
But it is implemented in a rather bizarre way:
> Node uses a
> [statically compiled, manually updated, hardcoded list][node.pem]
> of certificate authorities,
> rather than relying on the system's trust store...
> [Read more][node/4175]
It's somewhat non-intuitive under any OS,
but Windows differs from most of them
by having its own trust store,
fully incompatible with [OpenSSL].
This package is intended to
fetch Root CAs from Windows' store
(*Trusted Root Certification Authorities*)
and make them available to
[Node.js] application with minimal efforts.
### Advantages
- No internet access is required at all
- Windows store is updated automatically (in most modern environments)
- Manually installed Root certificates are used
- Enterprise trusted certificates (GPO etc.) are made available too
## Usage
For 95% of users:
1. Just say `npm install --save win-ca`
2. Then call `require('win-ca')`.
3. That's it!
If you need more -
proceed to [API](#api)
section below.
By the way,
`win-ca` is safe to be used
under other OSes (not M$ Windows).
It does nothing there.
### Electron
`win-ca` was adapted to run inside Electron applications
with no additional configuration
([asar] supported).
See
[Minimal Electron application using win-ca][electron-win-ca]
for usage example.
### VS Code extension
Special [extension](vscode) for [VS Code]
was created to import `win-ca`
in context of VS Code's Extension Host.
Since all VS Code extensions share the same process,
root certificates imported by one of them
are immediately available to others.
This can allow VS Code extensions to connect to
(properly configured)
intranet sites from Windows machines.
## API
<details>
<summary>
Click to view...
</summary>
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)
})
```
### 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](#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 <abbr title="This is SPARTA!!!">laconic</abbr> 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](#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](#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](#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()](#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
```js
var certificate = ca.der2(format, certificate_in_der_format)
```
Converts certificate from DER
to
[format](#api-parameters)
specified in first parameter.
Function `.der2()` is curried:
```js
var toPEM = ca.der2(ca.der2.pem)
var pem = toPEM(der)
```
### hash
```js
var 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:
```js
var hasher = ca.hash()
console.log(hasher(der))
```
### inject
```js
ca.inject(mode)
// or:
ca.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:
```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.
### 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:
```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
<details>
<summary>
Click to view...
</summary>
`win-ca` v2 had another API,
which is preserved for compatibility,
but discouraged to use.
It consists of three functions:
* Synchronous:
+ `.all()`
+ `.each()`
* Asynchronous:
+ `.each.async()`
```
var ca = require('win-ca')
do.something.with(ca.all(ca.der2.pem))
```
Note:
1. All three yield
certificates
in [node-forge][]'s format
by default
(unlike [modern API](#api),
that returns DER
if unspecified by user).
Unfortunately, `node-forge` at the time of writing is unable to
parse non-RSA certificates
(namely, ECC certificates becoming more popular).
If your *Trusted Root Certification Authorities* store
contains modern certificates,
legacy API calls
will throw exception.
To tackle the problem -
pass them [format](#api-parameters)
as the first parameter.
2. `.all()` deduplicates
certificates (like [regular API](#api)),
while both `.each` calls
may return duplicates
(`{unique: false}` applied)
3. `Root` store always used
(no way for `store:` option)
4. Both `.each` calls require callback
(with optional `format`)
Synchronous `.each()` callback gets single
argument - certificate
(in specified format)
```js
var ca = require('win-ca')
ca.each(ca.der2.x509, crt=>
console.log(crt.serialNumber)
)
```
Asynchronous `.each.async()` callback
gets two parameters:
+ `error` (which is always `undefined` in this version)
+ `result` - certificate in requested `format`
or `undefined` to signal end of retrieval
```js
let ca = require('win-ca')
ca.each.async((error, crt)=> {
if (error) throw error;
if(crt)
console.log(forge.pki.certificateToPem(crt))
else
console.log("That's all folks!")
})
```
</details>
## 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](n-api/crypt32.cpp) 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](n-api/roots.c) 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')
```
</details>
## Caveats
Windows 10 tends to
have only a few certificates in
its *Trusted Root Certification Authorities* store
and [lazily add them to it on first use][win.lazy].
If your OS does so,
`win-ca` will still help to
connect to your own sites
(protected by self-signed certificates,
or by the ones, distributed with GPO),
but will make connection to
well-known sites
(like Google or Twitter) impossible!
The simplest remedy is to
*once* open desired site in
Internet Explorer / Google Chrome
(certificate will be *silently* added
to Root store).
Another option is to switch to new
*experimental* [injection](#inject) method:
```js
require('win-ca').inject('+')
```
### Clear `pem` folder on publish
If you use `win-ca` in some Electron app or VS Code extension,
be warned that
`node_modules/win-ca/pem` folder
is *highly likely* to be packed into your bundle
with all root certificates on development machine.
You had better remove said folder
before publishing
(eg. in `prepack` npm script if it applies).
## Building
- npm install
- npm run pretest
- npm run [nvm$]
- npm publish
This builds both `x86` and `x64` versions with [N-API](#n-api) support.
For older Node.js versions standalone binary utility is built.
## See also
- [OpenSSL::Win::Root][] for Ruby version
- [mac-ca][] for Mac OS version
## Credits
Uses [node-forge][]
and used to use [node-ffi-napi][] (ancestor of [node-ffi][]).
[node-ffi]: https://github.com/node-ffi/node-ffi
[node-ffi-napi]: https://github.com/node-ffi-napi/node-ffi-napi
[node-forge]: https://github.com/digitalbazaar/forge
[OpenSSL::Win::Root]: https://github.com/ukoloff/openssl-win-root
[Node.js]: http://nodejs.org/
[Buffer]: https://nodejs.org/api/buffer.html
[Ruby]: https://www.ruby-lang.org/
[node.pem]: https://github.com/nodejs/node/blob/master/src/node_root_certs.h
[node/4175]: https://github.com/nodejs/node/issues/4175
[OpenSSL]: https://www.openssl.org/
[nvm$]: https://github.com/ukoloff/nvms
[N-API]: https://nodejs.org/api/n-api.html
[N-API-support]: https://github.com/nodejs/node-addon-api/blob/master/index.js#L17
[VS Code]: https://code.visualstudio.com/
[mac-ca]: https://github.com/jfromaniello/mac-ca
[Electron]: https://electronjs.org/
[electron-win-ca]: https://github.com/ukoloff/electron-win-ca
[win.lazy]: https://social.technet.microsoft.com/wiki/contents/articles/3147.pki-certificate-chaining-engine-cce.aspx
[asar]: https://github.com/electron/asar