taigrr/nats.docs
1
0
Fork 0
mirror of https://github.com/taigrr/nats.docs synced 2025-01-18 04:03:23 -08:00
Code Issues Projects Releases Wiki Activity

Merge pull request #89 from nats-io/matthiashanel-patch-1

Browse Source 
clarifications for mkcert -client
This commit is contained in:
Ginger Collison 2020-04-27 11:38:21 -05:00 committed by GitHub
commit 823ced4ae7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 10 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
nats-server/configuration/securing_nats/tls.md
View File

@ -97,9 +97,9 @@ With respect to NATS the relevant values for extended key usage are:
* `TLS WWW server authentication` - To authenticate as server for incoming connections. A NATS server will need a certificate containing this.
* `TLS WWW client authentication` - To authenticate as client for outgoing connections. Only needed when connecting to a server where `verify` or `verify_and_map` are specified. In these cases, a NATS client will need a certificate with this value.
* [Leaf node](../leafnodes/) connections can be configured with `verify` as well. Then connecting NATS server will have to present a certificate with this value too. Certificates containing both values are an option.
* [Cluster](../clustering/) connections always have `verify` enabled. Which server acts as client and server comes down to timing and therefore can't be individually configured. Certificates containing both values are a must.
* [Gateway](../gateways/) connections always have `verify` enabled. Unlike cluster outgoing connections can specify a separate cert. Certificates containing both values are an option that reduce configuration.
* [Leaf node](../leafnodes/README.md) connections can be configured with `verify` as well. Then the connecting NATS server will have to present a certificate with this value too. Certificates containing both values are an option.
* [Cluster](../clustering/README.md) connections always have `verify` enabled. Which server acts as client and server comes down to timing and therefore can't be individually configured. Certificates containing both values are a must.
* [Gateway](../gateways/README.md) connections always have `verify` enabled. Unlike cluster outgoing connections can specify a separate cert. Certificates containing both values are an option that reduce configuration.
Note that it's common practice for non-web protocols to use the `TLS WWW` authentication fields, as a matter of history those have become embedded as generic options.
@ -107,7 +107,7 @@ Note that it's common practice for non-web protocols to use the `TLS WWW` authen
The simplest way to generate a CA as well as client and server certificates is [mkcert](https://github.com/FiloSottile/mkcert). This zero config tool generates and installs the CA into your **local** system trust store\(s\) and makes providing SAN straight forward. Check it's [documentation](https://github.com/FiloSottile/mkcert/blob/master/README.md) for installation and your system's trust store. Here is a simple example:
Generate a CA as well as a certificate, valid for server authentication by `localhost` and the IP `::1`\(`-cert-file` and `-key-file` overwrite default file names\). Then start a nats server using the generated certificate.
Generate a CA as well as a certificate, valid for server authentication by `localhost` and the IP `::1`\(`-cert-file` and `-key-file` overwrite default file names\). Then start a NATS server using the generated certificate.
```bash
mkcert -install
@ -118,12 +118,16 @@ nats-server --tls --tlscert=server-cert.pem --tlskey=server-key.pem -ms 8222
Now you should be able to access the monitoring endpoint `https://localhost:8222` with your browser.
`https://127.0.0.1:8222` however should result in an error as `127.0.0.1` is not listed as SAN. You will not be able to establish a connection from another computer either. For that to work you have to provide appropriate DNS and/or IP [SAN\(s\)](#missing-subject-alternative-name)
To generate certificates that work with `verify` provide the `-client` option. This will cause it to add an appropriate key usage for client authentication. Please note that client refers to connecting process, not necessarily a NATS client. Also add a SAN email for usage as user name in `verify_and_map`.
To generate certificates that work with `verify`/[`cluster`](../cluster/README.md)/[`gateway`](../gateway/README.md)/[`leaf_nodes`](../leafnodes/README.md) provide the `-client` option. It will cause the appropriate key usage for client authentication to be added. This example also adds a SAN email for usage as user name in `verify_and_map`.
```bash
mkcert -client -cert-file client-cert.pem -key-file client-key.pem localhost ::1 email@localhost
```
> Please note:
> * That client refers to connecting process, not necessarily a NATS client.
> * `mkcert -client` will generate a certificate with key usage suitable for client **and** server authentication.
Examples in this document make use of the certificates generated so far. To simplify examples using the CA certificate, copy `rootCA.pem` into the same folder where the certificates were generated. To obtain the CA certificate's location use this command:
```bash
@ -136,7 +140,7 @@ Once you are done testing, remove the CA from your **local** system trust store\
mkcert -uninstall
```
Alternatively, you can also use [openssl](https://www.openssl.org/) to [generate certificates](https://www.digitalocean.com/community/tutorials/openssl-essentials-working-with-ssl-certificates-private-keys-and-csrs). This tool allows a lot more customization of the generated certificates. It is a lot **more complex** and does **not manage** installation into the system trust store\(s\).
Alternatively, you can also use [openssl](https://www.openssl.org/) to [generate certificates](https://www.digitalocean.com/community/tutorials/openssl-essentials-working-with-ssl-certificates-private-keys-and-csrs). This tool allows a lot more customization of the generated certificates. It is **more complex** and does **not manage** installation into the system trust store\(s\).
However, for inspecting certificates it is quite handy. To inspect the certificates from the above example execute these commands: