Skip to content

Commit

Permalink
Merge pull request #417 from nerdoftech/tls-auth
Browse files Browse the repository at this point in the history 
Add documentation for TLS mutual auth
  • Loading branch information
@gcolliso
gcolliso authored Feb 22, 2019
2 parents b044e04 + c41b5db commit d4cfe90
Show file tree
Hide file tree
Showing 2 changed files with 143 additions and 57 deletions.
2 changes: 1 addition & 1 deletion content/documentation/managing_the_server/authentication.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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).
198 changes: 142 additions & 56 deletions content/documentation/managing_the_server/security.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,26 +9,7 @@ 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:
<a href="https://docs.docker.com/engine/articles/https/" target="_blank">https://docs.docker.com/engine/articles/https/</a>

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
Expand All @@ -48,40 +29,10 @@ 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
Note: This TLS configuration is also used for the monitor port if enabled with the `https_port` option.

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 **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:
<a href="https://docs.docker.com/engine/articles/https/" target="_blank">https://docs.docker.com/engine/articles/https/</a>

The server can be run using command line arguments to enable TLS functionality.

Expand All @@ -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
Expand All @@ -104,25 +55,160 @@ Examples using the test certicates which are self signed for localhost and 127.0
[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
[15146] 2015/12/03 12:38:37.751948 [DBG] ::1:63330 - cid:1 - TLS handshake complete
[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

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 in the cipherMap variable](https://github.com/nats-io/gnatsd/blob/master/server/ciphersuites.go#L21).

### Client TLS Mutual Authentication

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 {
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 with OpenSSL:

```ascii
$ openssl x509 -noout -text -in test/configs/certs/client-id-auth-cert.pem
Certificate:
-------------<truncated>-------------
X509v3 extensions:
X509v3 Subject Alternative Name:
DNS:localhost, IP Address:127.0.0.1, email:[email protected]
X509v3 Extended Key Usage:
TLS Web Client Authentication
-------------<truncated>-------------
```

The configuration to authorize this user would be as follows:

```ascii
authorization {
users = [
{user: "[email protected]", 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:
-------------<truncated>-------------
Subject: OU=CNCF, CN=example.com
-------------<truncated>-------------
```

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
Expand Down

0 comments on commit d4cfe90

Please sign in to comment.