tls
map, which has the following properties:cert_file
key_file
cipher_suites
curve_preferences
insecure
verify
true
, require and verify client certificates. To support use by Browser, this option does not apply to monitoring.verify_and_map
true
, require and verify client certificates and map certificate values for authentication purposes. Does not apply to monitoring either.verify_cert_and_check_known_urls
verify: true
is the default (cluster/gateway). The incoming connections certificate's X509v3 Subject Alternative Name
DNS
entries will be matched against all urls in the configuration context that contains this tls map. If a match is found, the connection is accepted and rejected otherwise. Meaning for gateways we will match all DNS entries in the certificate against all gateway urls. For cluster, we will match against all route urls. As a consequence of this, dynamic cluster growth may require config changes in other clusters where this flag is true. DNS name checking is performed according to rfc6125. Only the full wildcard *
is supported for the left most label. This would be one way to keep cluster growth flexible.pinned_certs
-D
or -DV
, the logs will show the cipher suite selection for each connected client:tls
section is specified at the root of the configuration, it also affects the monitoring port if https_port
option is specified. Other sections such as cluster
can specify a tls
block.timeout
setting enables you to control the amount of time that a client is allowed to upgrade its connection to tls. If your clients are experiencing disconnects during TLS handshake, you'll want to increase the value, however, if you do be aware that an extended timeout
exposes your server to attacks where a client doesn't upgrade to TLS and thus consumes resources. Conversely, if you reduce the TLS timeout
too much, you are likely to experience handshake errors.ca_file
file should contain one or more Certificate Authorities in PEM format, in a bundle. This is a common format.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.DO NOT USE these certificates in production!!!
verify
, verify_and_map
or verify_cert_and_check_known_urls
you need to specify ca_file
in the server. If you are having a more complex setup involving cluster, gateways or leaf nodes, ca_file
needs to be present in tls
maps used to connect to the server with self-signed certificates. While this works for server and libraries from the NATS ecosystem, you will experience issues when connecting with other tools such as your Browser.127.0.0.1
, the server needs to present a certificate with a SAN containing the IP 127.0.0.1
or the connection will be closed with a handshake error.verify_cert_and_check_known_urls
is specified, Subject Alternative Name (SAN) DNS
records are necessary. In order to successfully connect there must be an overlap between the DNS
records provided as part of the certificate and the urls configured. If you dynamically grow your cluster and use a new certificate, this route or gateway the server connects to will have to be reconfigured to include an url for the new server. Only then can the new server connect. If the DNS
record is a wildcard, matching according to rfc6125 will be performed. Using certificates with a wildcard Subject Alternative Name (SAN) and configuration with url(s) that would match are a way to keep the flexibility of dynamic cluster growth without configuration changes in other clusters.Digital Signature
and Key Encipherment
are an interoperable choice.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
, verify_and_map
or verify_cert_and_check_known_urls
are specified. In these cases, a NATS client will need a certificate with this value.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.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.verify
enabled. Unlike cluster outgoing connections can specify a separate cert. Certificates containing both values are an option that reduce configuration.TLS WWW
authentication fields, as a matter of history those have become embedded as generic options.localhost
and the IP ::1
(-cert-file
and -key-file
overwrite default file names). Then start a NATS server using the generated certificate.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)​verify
and cluster
/gateway
/leaf_nodes
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
.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.
rootCA.pem
into the same folder where the certificates were generated. To obtain the CA certificate's location use this command: