|
1 | | -To enable https://web-platform.test:8443/, add cacert.pem to your browser as Certificate Authority. |
| 1 | +# WPT Test Certificates |
| 2 | + |
| 3 | +The web-platform-tests project maintains a set of SSL certificates to allow |
| 4 | +contributors to execute tests requiring HTTPS locally. |
| 5 | + |
| 6 | +## Trusting Root CA |
| 7 | + |
| 8 | +To prevent browser SSL warnings when running HTTPS tests locally, the |
| 9 | +web-platform-tests Root CA file `cacert.pem` in the `tools/certs/` directory |
| 10 | +must be added as a trusted certificate in your OS/browser. |
2 | 11 |
|
3 | 12 | For Firefox, go to about:preferences and search for "certificates". |
4 | 13 |
|
5 | | -For browsers that use the Certificate Authorities of the underlying OS, such as Chrome and Safari, |
6 | | -you need to adjust the OS. For macOS, go to Keychain Access and add the certificate under |
7 | | -**login**. |
| 14 | +For browsers that use the Certificate Authorities of the underlying OS, such as |
| 15 | +Chrome and Safari, you need to adjust the OS. For macOS, go to Keychain Access |
| 16 | +and add the certificate under **login**. |
| 17 | + |
| 18 | +**NOTE**: The CA should not be installed in any browser profile used |
| 19 | +outside of tests, since it may be used to generate fake |
| 20 | +certificates. For browsers that use the OS certificate store, tests |
| 21 | +should therefore not be run manually outside a dedicated OS instance |
| 22 | +(e.g. a VM). To avoid this problem when running tests in Chrome or |
| 23 | +Firefox use `wpt run`, which disables certificate checks and therefore |
| 24 | +doesn't require the root CA to be trusted. |
| 25 | + |
| 26 | +## Regenerating certificates |
| 27 | + |
| 28 | +If you wish to generate new certificates for any reason it's possible to use |
| 29 | +OpenSSL when starting the server, or starting a test run, by providing the |
| 30 | +`--ssl-type=openssl` argument to the `wpt serve` or `wpt run` commands. |
| 31 | + |
| 32 | +If you installed OpenSSL in such a way that running `openssl` at a |
| 33 | +command line doesn't work, you also need to adjust the path to the |
| 34 | +OpenSSL binary. This can be done by adding a section to `config.json` |
| 35 | +like: |
| 36 | + |
| 37 | +``` |
| 38 | +"ssl": {"openssl": {"binary": "/path/to/openssl"}} |
| 39 | +``` |
| 40 | + |
| 41 | +On Windows using OpenSSL typically requires installing an OpenSSL distribution. |
| 42 | +[Shining Light](https://slproweb.com/products/Win32OpenSSL.html) |
| 43 | +provide a convenient installer that is known to work, but requires a |
| 44 | +little extra setup, i.e.: |
| 45 | + |
| 46 | +Run the installer for Win32_OpenSSL_v1.1.0b (30MB). During installation, |
| 47 | +change the default location for where to Copy OpenSSL Dlls from the |
| 48 | +System directory to the /bin directory. |
| 49 | + |
| 50 | +After installation, ensure that the path to OpenSSL (typically, |
| 51 | +this will be `C:\OpenSSL-Win32\bin`) is in your `%Path%` |
| 52 | +[Environment Variable](http://www.computerhope.com/issues/ch000549.htm). |
| 53 | +If you forget to do this part, you will most likely see a 'File Not Found' |
| 54 | +error when you start wptserve. |
8 | 55 |
|
9 | | -### Updating these certs |
| 56 | +Finally, set the path value in the server configuration file to the |
| 57 | +default OpenSSL configuration file location. To do this create a file |
| 58 | +called `config.json`. Then add the OpenSSL configuration below, |
| 59 | +ensuring that the key `ssl/openssl/base_conf_path` has a value that is |
| 60 | +the path to the OpenSSL config file (typically this will be |
| 61 | +`C:\\OpenSSL-Win32\\bin\\openssl.cfg`): |
10 | 62 |
|
11 | | -From the root, run `./wpt serve --config tools/certs/config.json` and terminate it after it has started up. |
| 63 | +``` |
| 64 | +{ |
| 65 | + "ssl": { |
| 66 | + "type": "openssl", |
| 67 | + "encrypt_after_connect": false, |
| 68 | + "openssl": { |
| 69 | + "openssl_binary": "openssl", |
| 70 | + "base_path: "_certs", |
| 71 | + "force_regenerate": false, |
| 72 | + "base_conf_path": "C:\\OpenSSL-Win32\\bin\\openssl.cfg" |
| 73 | + }, |
| 74 | + }, |
| 75 | +} |
| 76 | +``` |
0 commit comments