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

Provide guidance on TLS ca_file directives

Browse Source
This commit is contained in:
Phil Pennock 2020-10-30 15:30:06 -04:00
parent 1eca5d0c38
commit f5f1ff8718
2 changed files with 35 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
nats-server/configuration/gateways/gateway.md
View File

@ -82,7 +82,7 @@ The `gateways` configuration block is a list of gateway entries with the followi
| `name` | Gateway name. |
| `url` | Hostport `<host>:<port>` describing where the remote gateway can be reached. If multiple IPs are returned, one is randomly selected. |
| `urls` | A list of `url` strings. |
| `tls` | A [`tls` configuration map](../securing_nats/tls.md) for creating a secure gateway connection. If the top-level `gateway{}` tls block contains certificates that have both client and server purposes, it is possible to omit this one and the server will use the certificates from the `gateway{tls{}}` section. |
| `tls` | A [`tls` configuration map](../securing_nats/tls.md) for creating a secure gateway connection. If the top-level `gateway{}` tls block contains certificates that have both client and server purposes, it is possible to omit this one and the server will use the certificates from the `gateway{tls{}}` section. See additional advice below. |
By using `urls` and an array, you can specify a list of endpoints that form part of a cluster as below. A NATS Server will pick one of those addresses randomly and only establish a single outbound gateway connection to one of the members from another cluster:
@ -99,3 +99,18 @@ gateway {
}
```
### TLS Entry
In addition to the normal TLS configuration advice, bear in mind that
TLS keys and certificates for multiple clusters, or servers in different
locations, rarely rotate at the exact same time and that Certificate
Authorities do roll between multiple Intermediate certificates.
If using a certificate bundle which accompanied the issuance of a certificate
then the CA in that bundle will typically be for just that certificate.
Using _only_ that CA as the CA for gateway authentication is ill-advised.
You should ensure that you allow for rolling between Certificate Authorities,
even if only between multiple CAs from the same organization entity,
and use a separate certificate bundle for _verification_ of peers.
This way when DC-B rolls before DC-A, it will not be cut off from your
supercluster.

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

@ -6,7 +6,7 @@ The NATS server uses modern TLS semantics to encrypt client, route, and monitori
| :--- | :--- |
| `cert_file` | TLS certificate file. |
| `key_file` | TLS certificate key file. |
| `ca_file` | TLS certificate authority file. When not present, default to the system trust store. |
| `ca_file` | TLS [certificate authority file](tls.md#certificate-authorities). When not present, default to the system trust store. |
| `cipher_suites` | When set, only the specified TLS cipher suites will be allowed. Values must match the golang version used to build the server. |
| `curve_preferences` | List of TLS cipher curves to use in order. |
| `insecure` | Skip certificate verification. **NOT Recommended** |
@ -59,6 +59,24 @@ tls: {
}
```
## Certificate Authorities
The `ca_file` file should contain one or more Certificate Authorities in PEM
format, in a bundle. This is a common format.
When a certificate is issued, it is often accompanied by a copy of the
intermediate certificate used to issue it. This is useful for validating that
certificate. It is not necessarily a good choice as the only CA suitable for
use in verifying other certificates a server may see.
Do consider though that organizations issuing certificates will change the
intermediate they use. For instance, a CA might issue intermediates in pairs,
with an active and a standby, and reserve the right to switch to the standby
without notice. You probably would want to trust _both_ of those for the
`ca_file` directive, to be prepared for such a day, and then after the first
CA has been compromised you can remove it. This way the roll from one CA to
another will not break your NATS server deployment.
## Self Signed Certificates for Testing
Explaining [Public key infrastructure](https://en.wikipedia.org/wiki/Public_key_infrastructure), [Certificate Authorities \(CA\)](https://en.wikipedia.org/wiki/Certificate_authority) and [x509](https://tools.ietf.org/html/rfc5280) [certificates](https://en.wikipedia.org/wiki/Public_key_certificate) fall well outside the scope of this document. So does an explanation on how to obtain a properly trusted certificates.