From 0b85a8a3fd7498466d008468c69babda7f030be5 Mon Sep 17 00:00:00 2001 From: Eric Flores Date: Wed, 20 Feb 2019 15:14:39 -0600 Subject: [PATCH 1/3] First draft --- .../managing_the_server/authentication.md | 2 +- .../managing_the_server/security.md | 189 +++++++++++++----- 2 files changed, 139 insertions(+), 52 deletions(-) diff --git a/content/documentation/managing_the_server/authentication.md b/content/documentation/managing_the_server/authentication.md index 3fb440c6..fc1e32d4 100644 --- a/content/documentation/managing_the_server/authentication.md +++ b/content/documentation/managing_the_server/authentication.md @@ -118,4 +118,4 @@ Using token 'S3Cr3T0k3n!' nats://S3Cr3T0k3n!@localhost:4222 ``` -or use other methods discussed in the [developer doc](/documentation/writing_applications/secure_connection). +The server also supports TLS mutual authentication documented in the [Security/Encryption section](/documentation/managing_the_server/security). Other methods are also discussed in the [developer doc](/documentation/writing_applications/secure_connection). diff --git a/content/documentation/managing_the_server/security.md b/content/documentation/managing_the_server/security.md index afc745f1..b4a7a941 100644 --- a/content/documentation/managing_the_server/security.md +++ b/content/documentation/managing_the_server/security.md @@ -9,21 +9,6 @@ category = "server" parent = "Managing the Server" +++ -As of Release 0.7.0, the server can use modern TLS semantics for client connections, route connections, and the HTTPS monitoring port. -The server requires TLS version 1.2, and sets preferences for modern cipher suites that avoid those known with vulnerabilities. The -server's preferences when building with Go1.5 are as follows. - -```go -func defaultCipherSuites() []uint16 { - return []uint16{ - // The SHA384 versions are only in Go1.5+ - tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, - tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, - tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, - tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, - } -} -``` Generating self signed certs and intermediary certificate authorities is beyond the scope here, but this document can be helpful in addition to Google Search: https://docs.docker.com/engine/articles/https/ @@ -48,40 +33,6 @@ authorization { } ``` -If requiring client certificates as well, simply change the TLS section as follows. - -```ascii -tls { - cert_file: "./configs/certs/server-cert.pem" - key_file: "./configs/certs/server-key.pem" - ca_file: "./configs/certs/ca.pem" - verify: true -} -``` - -When setting up clusters, all servers in the cluster, if using TLS, will both verify the connecting endpoints and the server responses. So certificates are checked in both directions. Certificates can be configured only for the server's cluster identity, keeping client and server certificates separate from cluster formation. - -```ascii -cluster { - listen: 127.0.0.1:4244 - - tls { - # Route cert - cert_file: "./configs/certs/srva-cert.pem" - # Private key - key_file: "./configs/certs/srva-key.pem" - # Optional certificate authority verifying connected routes - # Required when we have self-signed CA, etc. - ca_file: "./configs/certs/ca.pem" - } - # Routes are actively solicited and connected to from this server. - # Other servers can connect to us if they supply the correct credentials - # in their routes definitions from above. - routes = [ - nats-route://127.0.0.1:4246 - ] -} -``` The server can be run using command line arguments to enable TLS functionality. @@ -93,7 +44,7 @@ The server can be run using command line arguments to enable TLS functionality. --tlscacert FILE Client certificate CA for verification ``` -Examples using the test certicates which are self signed for localhost and 127.0.0.1. +Examples using the test certificates which are self signed for localhost and 127.0.0.1. ```sh > ./gnatsd --tls --tlscert=./test/configs/certs/server-cert.pem --tlskey=./test/configs/certs/server-key.pem @@ -112,17 +63,153 @@ Notice that the log indicates that the client connections will be required to u [15146] 2015/12/03 12:38:37.751959 [DBG] ::1:63330 - cid:1 - TLS version 1.2, cipher suite TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 ``` +### TLS Ciphers + +As of Release 0.7.0, the server can use modern TLS semantics for client connections, route connections, and the HTTPS monitoring port. +The server requires TLS version 1.2, and sets preferences for modern cipher suites that avoid those known with vulnerabilities. The +server's default preferences when building with Go1.5 are as follows. + +```go +func defaultCipherSuites() []uint16 { + return []uint16{ + // The SHA384 versions are only in Go1.5+ + tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, + tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, + tls.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305, + tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305, + tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, + tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, + } +} +``` + +Optionally if your organization requires a specific cipher or list of ciphers, you can configure them with the `cipher_suites` option as follows: + +```ascii +tls { + cert_file: "./configs/certs/server.pem" + key_file: "./configs/certs/key.pem" + timeout: 2 + cipher_suites: [ + "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", + "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", + ] +} +``` + +A list of supported cipher suites is located here: https://github.com/nats-io/gnatsd/blob/master/server/ciphersuites.go#L21 + +### Client TLS Mutual Authentication + +If requiring client certificates as well, simply add the option `verify` the TLS section as follows: + +```ascii +tls { + cert_file: "./configs/certs/server-cert.pem" + key_file: "./configs/certs/server-key.pem" + ca_file: "./configs/certs/ca.pem" + verify: true +} +``` + If you want the server to enforce and require client certificates as well via the command line, utilize this example. ```sh > ./gnatsd --tlsverify --tlscert=./test/configs/certs/server-cert.pem --tlskey=./test/configs/certs/server-key.pem --tlscacert=./test/configs/certs/ca.pem ``` +This option simply verifies the client's certificate has been signed by the CA specified in the `ca_file` option. However, it does not map any attribute of the client's certificate to the user's identity. + +To have TLS Mutual Authentication map certificate attributes to the users identity, replace the option `verify` with `verify_and_map` as shown as follows: + +```ascii +tls { + cert_file: "./configs/certs/server-cert.pem" + key_file: "./configs/certs/server-key.pem" + ca_file: "./configs/certs/ca.pem" + # Require a client certificate and map user id from certificate + verify_and_map: true +} +``` + +There are two options for certificate attributes that can be mapped to user names. The first is the email address in the Subject Alternative Name (SAN) field of the certificate. While generating a certificate with this attribute is outside the scope of this document, we will view this it with OpenSSL: + +```ascii +$ openssl x509 -noout -text -in test/configs/certs/client-id-auth-cert.pem +Certificate: + -------------------------- + X509v3 extensions: + X509v3 Subject Alternative Name: + DNS:localhost, IP Address:127.0.0.1, email:derek@nats.io + X509v3 Extended Key Usage: + TLS Web Client Authentication + -------------------------- +``` + +The configuration to authorize this user would be as follows: + +```ascii +authorization { + users = [ + {user: "derek@nats.io", permissions: { publish: "foo" }} + ] +} +``` + +Note: This configuration only works for the first email address if there are multiple emails in the SAN field. + +The second option is to use the RFC 2253 Distinguished Names syntax from the certificate subject as follows: + +```ascii +$ openssl x509 -noout -text -in test/configs/certs/tlsauth/client2.pem +Certificate: + Data: + -------------------------- + Subject: OU=CNCF, CN=example.com + -------------------------- +``` + +The configuration to authorize this user would be as follows: + +```ascii +authorization { + users = [ + {user: "CN=example.com,OU=CNCF", permissions: { publish: "foo" }} + ] +} +``` + +### Cluster TLS Mutual Authentication + +When setting up clusters all servers in the cluster, if using TLS, will both verify the connecting endpoints and the server responses. So certificates are checked in both directions. Certificates can be configured only for the server's cluster identity, keeping client and server certificates separate from cluster formation. + +```ascii +cluster { + listen: 127.0.0.1:4244 + + tls { + # Route cert + cert_file: "./configs/certs/srva-cert.pem" + # Private key + key_file: "./configs/certs/srva-key.pem" + # Optional certificate authority verifying connected routes + # Required when we have self-signed CA, etc. + ca_file: "./configs/certs/ca.pem" + } + # Routes are actively solicited and connected to from this server. + # Other servers can connect to us if they supply the correct credentials + # in their routes definitions from above. + routes = [ + nats-route://127.0.0.1:4246 + ] +} +``` + ### Using bcrypt to Protect Passwords In addition to TLS functionality, the server now also supports hashing of passwords and authentication tokens using `bcrypt`. To take advantage of this, simply replace the plaintext password in the configuration with its `bcrypt` hash, and the server will automatically utilize `bcrypt` as needed. -A utility for creating `bcrypt` hashes is included with the gnatsd distribution (`util/mkpasswd.go`). Running it with no arguments will generate a new secure password along with the associated hash. This can be used for a password or a token in the configuration. +A utility for creating `bcrypt` hashes is included with the gnatsd distribution (`util/mkpasswd.go`). Running it with no arguments will generate a new secure password along with the associated hash. This can be used for a password or a token in the configuration. ``` ~/go/src/github.com/nats-io/gnatsd/util> go get golang.org/x/crypto/ssh/terminal From 3ca3e4d4996d7ccbbdd1c1b0ac23c9ef7c64e4ea Mon Sep 17 00:00:00 2001 From: Eric Flores Date: Wed, 20 Feb 2019 15:46:37 -0600 Subject: [PATCH 2/3] Final cleanup --- .../managing_the_server/security.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/content/documentation/managing_the_server/security.md b/content/documentation/managing_the_server/security.md index b4a7a941..6a8488e6 100644 --- a/content/documentation/managing_the_server/security.md +++ b/content/documentation/managing_the_server/security.md @@ -9,11 +9,7 @@ category = "server" parent = "Managing the Server" +++ - -Generating self signed certs and intermediary certificate authorities is beyond the scope here, but this document can be helpful in addition to Google Search: -https://docs.docker.com/engine/articles/https/ - -The server **requires** a certificate and private key. Optionally the server can require that clients need to present certificates, and the server can be configured with a CA authority to verify the client certificates. +As of Release 0.7.0, the server can use modern TLS semantics for client connections, route connections, and the HTTPS monitoring port. To enable TLS on the client port add the TLS configuration section as follows: ```ascii # Simple TLS config file @@ -33,6 +29,10 @@ authorization { } ``` +Note: This TLS configuration is also used for the monitor port if enabled with the `https_port` option. + +The server **requires** a certificate and private key. Generating self signed certs and intermediary certificate authorities is beyond the scope here, but this document can be helpful in addition to Google Search: +https://docs.docker.com/engine/articles/https/ The server can be run using command line arguments to enable TLS functionality. @@ -55,7 +55,7 @@ Examples using the test certificates which are self signed for localhost and 127 [2935] 2016/04/26 13:34:30.685660 [INF] Server is ready ``` -Notice that the log indicates that the client connections will be required to use TLS. If you run the server in Debug mode with -D or -DV, the logs will show the cipher suite selection for each connected client. +Notice that the log indicates that the client connections will be required to use TLS. If you run the server in Debug mode with -D or -DV, the logs will show the cipher suite selection for each connected client. ```sh [15146] 2015/12/03 12:38:37.733139 [DBG] ::1:63330 - cid:1 - Starting TLS client connection handshake @@ -65,7 +65,6 @@ Notice that the log indicates that the client connections will be required to u ### TLS Ciphers -As of Release 0.7.0, the server can use modern TLS semantics for client connections, route connections, and the HTTPS monitoring port. The server requires TLS version 1.2, and sets preferences for modern cipher suites that avoid those known with vulnerabilities. The server's default preferences when building with Go1.5 are as follows. @@ -97,11 +96,11 @@ tls { } ``` -A list of supported cipher suites is located here: https://github.com/nats-io/gnatsd/blob/master/server/ciphersuites.go#L21 +A list of supported cipher suites is [located here in the cipherMap variable](https://github.com/nats-io/gnatsd/blob/master/server/ciphersuites.go#L21). ### Client TLS Mutual Authentication -If requiring client certificates as well, simply add the option `verify` the TLS section as follows: +Optionally the server can require that clients need to present certificates, and the server can be configured with a CA authority to verify the client certificates. Simply add the option `verify` the TLS configuration section as follows: ```ascii tls { From c41b5db491e60638ec25e30df239ab0e60f5e565 Mon Sep 17 00:00:00 2001 From: Waldemar Quevedo Date: Wed, 20 Feb 2019 17:02:48 -0600 Subject: [PATCH 3/3] Update content/documentation/managing_the_server/security.md Co-Authored-By: nerdoftech --- content/documentation/managing_the_server/security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/documentation/managing_the_server/security.md b/content/documentation/managing_the_server/security.md index 6a8488e6..e0d29888 100644 --- a/content/documentation/managing_the_server/security.md +++ b/content/documentation/managing_the_server/security.md @@ -131,7 +131,7 @@ tls { } ``` -There are two options for certificate attributes that can be mapped to user names. The first is the email address in the Subject Alternative Name (SAN) field of the certificate. While generating a certificate with this attribute is outside the scope of this document, we will view this it with OpenSSL: +There are two options for certificate attributes that can be mapped to user names. The first is the email address in the Subject Alternative Name (SAN) field of the certificate. While generating a certificate with this attribute is outside the scope of this document, we will view this with OpenSSL: ```ascii $ openssl x509 -noout -text -in test/configs/certs/client-id-auth-cert.pem