diff --git a/README.md b/README.md index 4d737d9..21d89bf 100644 --- a/README.md +++ b/README.md @@ -19,32 +19,73 @@ Usage ```javascript 'use strict'; - -var https = require('https') - , cas - ; - + // This will add the well-known CAs // to `https.globalAgent.options.ca` -require('ssl-root-cas').inject(); - -cas = https.globalAgent.options.ca; - -cas.push(fs.readFileSync(path.join(__dirname, 'ssl', '01-cheap-ssl-intermediary-a.pem'))); -cas.push(fs.readFileSync(path.join(__dirname, 'ssl', '02-cheap-ssl-intermediary-b.pem'))); -cas.push(fs.readFileSync(path.join(__dirname, 'ssl', '03-cheap-ssl-site.pem'))); +require('ssl-root-cas/latest') + .inject() + .addFile(__dirname + '/ssl/01-cheap-ssl-intermediary-a.pem') + .addFile(__dirname + '/ssl/02-cheap-ssl-intermediary-b.pem') + .addFile(__dirname + '/ssl/03-cheap-ssl-site.pem') + ; ``` For the sake of version consistency this package ships with the CA certs that were -available at the time it was published. +available at the time it was published, +but for the sake of security I recommend you use the latest ones. If you want the latest certificates (downloaded as part of the postinstall process), -you can require those instead like so: +you can require those like so: ``` require('ssl-root-cas/latest').inject(); ``` +You can use the ones that shippped with package like so: + +``` +require('ssl-root-cas').inject(); +``` + +API +--- + +### inject() + +I thought it might be rude to modify `https.globalAgent.options.ca` on `require`, +so I afford you the opportunity to `inject()` the certs at your leisure. + +`inject()` keeps track of whether or not it's been run, so no worries about calling it twice. + +### addFile(filepath) + +This is just a convenience method so that you don't +have to require `fs` and `path` if you don't need them. + +```javascript +require('ssl-root-cas/latest') + .addFile(__dirname + '/ssl/03-cheap-ssl-site.pem') + ; +``` + +is the same as + +```javascript +var https = require('https') + , cas + ; + +cas = https.globalAgent.options.ca || []; +cas.push(fs.readFileSync(path.join(__dirname, 'ssl', '03-cheap-ssl-site.pem'))); +``` + +### rootCas + +If for some reason you just want to look at the array of Root CAs without actually injecting +them, or you just prefer to +`https.globalAgent.options.ca = require('ssl-root-cas').rootCas;` +yourself, well, you can. + BAD IDEAS === diff --git a/ca-store-generator.js b/ca-store-generator.js index 4de3318..457a258 100644 --- a/ca-store-generator.js +++ b/ca-store-generator.js @@ -128,6 +128,7 @@ function dumpCerts(certs) { + 'var cas = module.exports = [\n' + certs.map(function (cert) { return cert.quasiPEM(); }).join(',\n\n') + '\n];\n' + + "module.exports.rootCas = cas;\n" + "module.exports.inject = function () {\n" + " var opts = require('https').globalAgent.options;\n" + " if (!opts.ca || !opts.ca.__injected) { opts.ca = (opts.ca||[]).concat(cas); }\n" @@ -137,7 +138,7 @@ function dumpCerts(certs) { + "module.exports.addFile = function (filepath) {\n" + " var opts = require('https').globalAgent.options;\n" + " opts.ca = opts.ca || [];\n" - + " opts.ca.push(require('fs').readFileSync(require('path').join.apply(null, filepath.split(/\//g))));\n" + + " opts.ca.push(require('fs').readFileSync(require('path').join.apply(null, filepath.split(/\\//g))));\n" + " return module.exports;\n" + "};\n" ); diff --git a/package.json b/package.json index 3c162fb..c400044 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "ssl-root-cas", - "version": "1.0.5", + "version": "1.1.0", "description": "The module you need to solve node's SSL woes when including a custom certificate.", "main": "ssl-root-cas", "scripts": {