diff --git a/nats-server/configuration/gateways/gateway.md b/nats-server/configuration/gateways/gateway.md index eed5a1e..c05c7b7 100644 --- a/nats-server/configuration/gateways/gateway.md +++ b/nats-server/configuration/gateways/gateway.md @@ -82,7 +82,7 @@ The `gateways` configuration block is a list of gateway entries with the followi | `name` | Gateway name. | | `url` | Hostport `:` 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. diff --git a/nats-server/configuration/securing_nats/tls.md b/nats-server/configuration/securing_nats/tls.md index f30798c..d76ddcb 100644 --- a/nats-server/configuration/securing_nats/tls.md +++ b/nats-server/configuration/securing_nats/tls.md @@ -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.