diff options
author | Bradley Farias <bradley.meck@gmail.com> | 2018-09-13 14:27:12 -0500 |
---|---|---|
committer | Bradley Farias <bradley.meck@gmail.com> | 2019-01-17 09:43:42 -0600 |
commit | 9d5fbeb55fb1927928237e09475d39346d9c3ad9 (patch) | |
tree | ca2f567ff647c9a1706f39e93e54caa03cd98c1d /doc/api/policy.md | |
parent | 7b6e9aedaf8c9aa219ff759bed6b1680910eefe0 (diff) | |
download | android-node-v8-9d5fbeb55fb1927928237e09475d39346d9c3ad9.tar.gz android-node-v8-9d5fbeb55fb1927928237e09475d39346d9c3ad9.tar.bz2 android-node-v8-9d5fbeb55fb1927928237e09475d39346d9c3ad9.zip |
policy: manifest with subresource integrity checks
This enables code loaded via the module system to be checked for
integrity to ensure the code loaded matches expectations.
PR-URL: https://github.com/nodejs/node/pull/23834
Reviewed-By: Guy Bedford <guybedford@gmail.com>
Reviewed-By: Vladimir de Turckheim <vlad2t@hotmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Diffstat (limited to 'doc/api/policy.md')
-rw-r--r-- | doc/api/policy.md | 104 |
1 files changed, 104 insertions, 0 deletions
diff --git a/doc/api/policy.md b/doc/api/policy.md new file mode 100644 index 0000000000..ee8109efd6 --- /dev/null +++ b/doc/api/policy.md @@ -0,0 +1,104 @@ +# Policies + +<!--introduced_in=TODO--> +<!-- type=misc --> + +> Stability: 1 - Experimental + +<!-- name=policy --> + +Node.js contains experimental support for creating policies on loading code. + +Policies are a security feature intended to allow guarantees +about what code Node.js is able to load. The use of policies assumes +safe practices for the policy files such as ensuring that policy +files cannot be overwritten by the Node.js application by using +file permissions. + +A best practice would be to ensure that the policy manifest is read only for +the running Node.js application, and that the file cannot be changed +by the running Node.js application in any way. A typical setup would be to +create the policy file as a different user id than the one running Node.js +and granting read permissions to the user id running Node.js. + +## Enabling + +<!-- type=misc --> + +The `--experimental-policy` flag can be used to enable features for policies +when loading modules. + +Once this has been set, all modules must conform to a policy manifest file +passed to the flag: + +```sh +node --experimental-policy=policy.json app.js +``` + +The policy manifest will be used to enforce constraints on code loaded by +Node.js. + +## Features + +### Error Behavior + +When a policy check fails, Node.js by default will throw an error. +It is possible to change the error behavior to one of a few possibilities +by defining an "onerror" field in a policy manifest. The following values are +available to change the behavior: + +* `"exit"` - will exit the process immediately. + No cleanup code will be allowed to run. +* `"log"` - will log the error at the site of the failure. +* `"throw"` (default) - will throw a JS error at the site of the failure. + +```json +{ + "onerror": "log", + "resources": { + "./app/checked.js": { + "integrity": "sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0" + } + } +} +``` + +### Integrity Checks + +Policy files must use integrity checks with Subresource Integrity strings +compatible with the browser +[integrity attribute](https://www.w3.org/TR/SRI/#the-integrity-attribute) +associated with absolute URLs. + +When using `require()` all resources involved in loading are checked for +integrity if a policy manifest has been specified. If a resource does not match +the integrity listed in the manifest, an error will be thrown. + +An example policy file that would allow loading a file `checked.js`: + +```json +{ + "resources": { + "./app/checked.js": { + "integrity": "sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0" + } + } +} +``` + +Each resource listed in the policy manifest can be of one the following +formats to determine its location: + +1. A [relative url string][] to a resource from the manifest such as `./resource.js`, `../resource.js`, or `/resource.js`. +2. A complete url string to a resource such as `file:///resource.js`. + +When loading resources the entire URL must match including search parameters +and hash fragment. `./a.js?b` will not be used when attempting to load +`./a.js` and vice versa. + +In order to generate integrity strings, a script such as +`printf "sha384-$(cat checked.js | openssl dgst -sha384 -binary | base64)"` +can be used. + + +[relative url string]: https://url.spec.whatwg.org/#relative-url-with-fragment-string |