From ad59a50d0e459b6512fd5bd434776f2e7cf7d68f Mon Sep 17 00:00:00 2001 From: Cedric Staub Date: Fri, 2 Nov 2018 12:35:34 -0700 Subject: [PATCH] Add extra docs for access control flags --- ACCESS-CONTROL.md | 122 ++++++++++++++++++++++++++++++++++++++++++++++ README.md | 18 ++++--- 2 files changed, 132 insertions(+), 8 deletions(-) create mode 100644 ACCESS-CONTROL.md diff --git a/ACCESS-CONTROL.md b/ACCESS-CONTROL.md new file mode 100644 index 00000000000..152b3b2c4bd --- /dev/null +++ b/ACCESS-CONTROL.md @@ -0,0 +1,122 @@ +Access Control +============== + +Ghostunnel uses TLS with mutual authentication for authentication and access +control. This means that both the client and server present a certificate that +can be verified by the other party. + +### Server mode + +There are several flags available to restrict which clients can connect to a +Ghostunnel server, based on checks on the subject of the client certificate. + +Access control flags in server mode are treated as a logical disjunction (OR) +when multiple flags are specified. This means that a client will be allowed to +complete a connection as long as at least one flag matches. + +* `--allow-all` + +Setting this flag allows all clients with a valid certificate, regardless of +the client certificate subject. This flag is mutually exclusive with other +access control flags. + +* `--allow-cn` + +Allow clients with given common name (CN) in the subject. Can be repeated to +allow multiple clients with different CNs to connect. Performs an exact string +comparison on the CN field. + +* `--allow-ou` + +Allow clients with given organizational unit (CN) field in the subject. Can be +repeated to allow multiple clients with different OUs to connect. Performs an +exact string comparison on the OU field. + +* `--allow-dns` + +Allow clients with given DNS subject alternative name (DNS SAN) in the subject. +Can be repeated to allow multiple clients with different DNS SANs to connect. +Note that this performs the access check based on a comparison of the the DNS +SAN value of the client certificate, it does not perform any DNS lookups. + +* `--allow-uri` + +Allow clients with given URI subject alternative name (URI SAN) in the subject. +Can be repeated to allow multiple clients with different URI SANs to connect. +This flag may also contain `*` and `** `wildcards that can be used to match +multiple clients. + +For example, setting `--allow-uri=spiffe://ghostunnel/*` would allow clients +with `spiffe://ghostunnel/client1` or `spiffe://ghostunnel/client2` URI SANs (as +well as other values). See documentation for the [wildcard][wildcard] package +for more information. + +* `--disable-authentication` + +Disables client authentication entirely, no client certificate will be required +from any client. This means that anyone will be able to establish a connection +to the Ghostunnel server. This flag is mutually exclusive with other access +control flags. + +### Client mode + +Ghostunnel in client mode offers various flags that can be used to augment and +perform additional checks on servers it connects to. Regardless of flags passed +to the client, it will always perform standard hostname verification to check +the hostname against the server certificate. + +Access control flags in client mode are treated as a logical disjunction (OR) +when multiple flags are specified. This means that a client will be allowed to +complete a connection as long as at least one flag matches, assuming that +hostname verification was also successful. + +* `--override-server-name` + +If set, overrides the server name used for hostname verification to be +different from the hostname that was passed in `--listen`. This also sets the +hostname passed to the backend for SNI purposes. The logic for hostname +verification is implemented as part of the [crypto/tls][tls] package in Go's +standard library, see the `ServerName` field on the `tls.Config` struct. + +* `--verify-cn` + +Verify the common name (CN) of the server certificate, on top of the hostname. +Can be repeated to check that at least one of a set of CNs is present. This +performs an exact string comparison on the CN field of the certificate. + +* `--verify-ou` + +Verify the organizational unit (OU) of the server certificate, on top of the +hostname. Can be repeated to check that at least one of a set of OUs is +present. This performs an exact string comparison on the OU field of the +certificate. + +* `--verify-dns` + +Verify the presence of a DNS subject alternative name (DNS SAN) on the server +certificate, on top of the hostname. This checks that the given DNS name is +listed as a valid name on the certificate. Can be repeated to require +multiple that at least one of a set of hostnames is present. + +* `--verify-uri` + +Verify the presence of a URI subject alternative name (URI SAN) on the server +certificate, on top of the hostname. This checks that the given URI name is +listed as a valid name on the certificate. This flag may also contain `*` and +`** `wildcards that can be used to match multiple servers. + +For example, setting `--verify-uri=spiffe://ghostunnel/*` would allow servers +with `spiffe://ghostunnel/server1` or `spiffe://ghostunnel/server2` URI SANs (as +well as other values). See documentation for the [wildcard][wildcard] package +for more information. + +[wildcard]: https://godoc.org/github.com/square/ghostunnel/wildcard + +* `--disable-authentication` + +Disable client authentication, no certificate will be provided to the server. +This is useful if you just want to use Ghostunnel to wrap a connection in TLS +but the backend doesn't require mutual authentication. + +[tls]: https://golang.org/pkg/crypto/tls +[wildcard]: https://godoc.org/github.com/square/ghostunnel/wildcard diff --git a/README.md b/README.md index bf4fab09368..52b387f32cf 100644 --- a/README.md +++ b/README.md @@ -44,11 +44,12 @@ can be used to collect metrics and monitor a running instance. Metrics can be fed into Graphite (or other systems) to see number of open connections, rate of new connections, connection lifetimes, timeouts, and other info. -**Emphasis on security**: We have put some thought into making ghostunnel secure -by default and prevent accidental misconfiguration. For example, we always -negotiate TLS v1.2 and only use safe cipher suites. Ghostunnel also supports -PKCS#11 which makes it possible to use Hardware Security Modules (HSMs) to protect -private keys. +**Emphasis on security**: We have put some thought into making ghostunnel +secure by default and prevent accidental misconfiguration. For example, we +always negotiate TLS v1.2 and only use safe cipher suites. Ghostunnel also +supports PKCS#11 which makes it possible to use Hardware Security Modules +(HSMs) to protect private keys. We also have a [BUG-BOUNTY](BUG-BOUNTY.md) that +pays rewards for security findings. Getting Started =============== @@ -74,7 +75,7 @@ Binaries can be built from source as follows (cross-compile requires Docker and make -f Makefile.dist dist Note that ghostunnel requires Go 1.11 or later to build, and CGO is required for -PKCS#11 support. See also [CROSS-COMPILE.md](CROSS-COMPILE.md) for +PKCS#11 support. See also [CROSS-COMPILE](CROSS-COMPILE.md) for instructions on how to cross-compile a custom build with CGO enabled. [rel]: https://github.com/square/ghostunnel/releases @@ -136,8 +137,9 @@ To set allowed clients, you must specify at least one of `--allow-all`, `--allow-cn`, `--allow-ou`, `--allow-dns` or `--allow-uri`. All checks are made against the certificate of the client. Multiple flags are treated as a logical disjunction (OR), meaning clients can connect as long as any of the flags -matches. In this example, we assume that the CN of the client cert we want to -accept connections from is `client`. +matches (see [ACCESS-CONTROL](ACCESS-CONTROL.md) for more information). In this +example, we assume that the CN of the client cert we want to accept connections +from is `client`. Start a backend server: