win-ca
v3.5.1
Published
Get Windows System Root certificates
Downloads
203,822
Maintainers
Readme
win-ca
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 of certificate authorities, rather than relying on the system's trust store... Read more
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:
- Just say
npm install --save win-ca
- Then call
require('win-ca')
. - That's it!
If you need more - proceed to 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 for usage example.
VS Code extension
Special extension 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
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:
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:
- Regular
require('win-ca')
- Fallback
require('win-ca/fallback')
- Pure API
require('win-ca/api')
They all export the same API, but differ in initialization:
win-ca
does fetch certificates fromRoot
store, saves them to disk and makes them available tohttps
module with no effort.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.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 isRoot
(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 forstore
parameter).var list = [] require('win-ca/api')({store: ['root', 'ca'], ondata: list})
unique
whether certificates list should be deduplicated. Default istrue
(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 retrievalUseful 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 alsotrue
if Electron is detected.Finally, if
win-ca
has been required aswin-ca/fallback
, default value for this flag is also set totrue
.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 toondata
callback. Finallyonend
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).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 tohttps.globalAgent.options.ca
(in PEM format, regardless offormat
parameter), so all subsequent calls tohttps
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 forhttps
, 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 insidewin-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 forSSL_CERT_DIR
- All certificates in single
roots.pem
file - suitable forSSL_CERT_FILE
If
win-ca
is required not viawin-ca/api
, it calls itself with{inject: true, save: true}
and additionaly setsca.path
field andSSL_CERT_DIR
environment variable to the folder with certificates saved.onsave
- callback called at the end of saving (ifsave
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
var certificate = ca.der2(format, certificate_in_der_format)
Converts certificate from DER to format specified in first parameter.
Function .der2()
is curried:
var toPEM = ca.der2(ca.der2.pem)
var pem = toPEM(der)
hash
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:
var hasher = ca.hash()
console.log(hasher(der))
inject
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 usedtrue
: put certificates tohttps.globalAgent.options.ca
and use them instead of built-in ones forhttps
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 justhttps
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:
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:
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
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:
All three yield certificates in node-forge's format by default (unlike modern 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 as the first parameter..all()
deduplicates certificates (like regular API), while both.each
calls may return duplicates ({unique: false}
applied)Root
store always used (no way forstore:
option)Both
.each
calls require callback (with optionalformat
)Synchronous
.each()
callback gets single argument - certificate (in specified format)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 alwaysundefined
in this version)result
- certificate in requestedformat
orundefined
to signal end of retrieval
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!") })
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
require('win-ca/fallback')
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.
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 method:
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 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).