Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

mTLS/TLS documentation fixes #5382

Merged
merged 7 commits into from
May 8, 2020
Merged

mTLS/TLS documentation fixes #5382

Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
5668916
doc fixes for mTLS/TLS dgraph live, dgraph cert, curl
darkn3rd May 6, 2020
d17c5a1
update typos, wording in deploy tls docs
darkn3rd May 7, 2020
5e34344
deploy/tls docs - updated table and updates for clarity
darkn3rd May 7, 2020
09c1b96
updated deploy/tls doc table for client auth
darkn3rd May 7, 2020
6ccbed6
deploy tls docs fix
darkn3rd May 7, 2020
f534721
deploy tls docs - reorganized sections for client authentication, upd…
darkn3rd May 7, 2020
0fb7a3a
deploy tls doc changes for correctness
darkn3rd May 8, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 66 additions & 34 deletions wiki/content/deploy/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1526,9 +1526,9 @@ Connections between client and server can be secured with TLS. Password protecte

{{% notice "tip" %}}If you're generating encrypted private keys with `openssl`, be sure to specify encryption algorithm explicitly (like `-aes256`). This will force `openssl` to include `DEK-Info` header in private key, which is required to decrypt the key by Dgraph. When default encryption is used, `openssl` doesn't write that header and key can't be decrypted.{{% /notice %}}

### Self-signed certificates
### Dgraph Certificate Management Tool

The `dgraph cert` program creates and manages self-signed certificates using a generated Dgraph Root CA. The _cert_ command simplifies certificate management for you.
The `dgraph cert` program creates and manages CA-signed certificates and private keys using a generated Dgraph Root CA. The `dgraph cert` command simplifies certificate management for you.

```sh
# To see the available flags.
Expand All @@ -1537,20 +1537,20 @@ $ dgraph cert --help
# Create Dgraph Root CA, used to sign all other certificates.
$ dgraph cert

# Create node certificate (needed for Dgraph Live Loader using TLS)
$ dgraph cert -n live
# Create node certificate and private key
$ dgraph cert -n localhost

# Create client certificate
# Create client certificate and private key for mTLS (mutual TLS)
$ dgraph cert -c dgraphuser

# Combine all in one command
$ dgraph cert -n live -c dgraphuser
$ dgraph cert -n localhost -c dgraphuser

# List all your certificates and keys
$ dgraph cert ls
```

### File naming conventions
#### File naming conventions

To enable TLS you must specify the directory path to find certificates and keys. The default location where the _cert_ command stores certificates (and keys) is `tls` under the Dgraph working directory; where the data files are found. The default dir path can be overridden using the `--dir` option.

Expand Down Expand Up @@ -1583,7 +1583,7 @@ $ dgraph cert -n localhost,104.25.165.23,dgraph.io,2400:cb00:2048:1::6819:a417

{{% notice "note" %}}When using host names for node certificates, including _localhost_, your clients must connect to the matching host name -- such as _localhost_ not 127.0.0.1. If you need to use IP addresses, then add them to the node certificate.{{% /notice %}}

### Certificate inspection
#### Certificate inspection

The command `dgraph cert ls` lists all certificates and keys in the `--dir` directory (default 'tls'), along with details to inspect and validate cert/key pairs.

Expand Down Expand Up @@ -1638,37 +1638,71 @@ The following configuration options are available for Alpha:

* `--tls_dir string` - TLS dir path; this enables TLS connections (usually 'tls').
* `--tls_use_system_ca` - Include System CA with Dgraph Root CA.
* `--tls_client_auth string` - TLS client authentication used to validate client connection. See [Client authentication](#client-authentication) for details.

```sh
# Default use for enabling TLS server (after generating certificates)
# First, create rootca and node certificates and private keys
$ dgraph cert -n localhost
# Default use for enabling TLS server (after generating certificates and private keys)
$ dgraph alpha --tls_dir tls
```

Dgraph Live Loader can be configured with following options:

* `--tls_dir string` - TLS dir path; this enables TLS connections (usually 'tls').
* `--tls_cacert string` - Dgraph Root CA, such as `./tls/ca.crt`
* `--tls_use_system_ca` - Include System CA with Dgraph Root CA.
* `--tls_server_name string` - Server name, used for validating the server's TLS host name.

```sh
# First, create a client certificate for live loader. This will create 'tls/client.live.crt'
$ dgraph cert -c live

# Now, connect to server using TLS
$ dgraph live --tls_dir tls -s 21million.schema -f 21million.rdf.gz
$ dgraph live --tls_cacert ./tls/ca.crt --tls_server_name "localhost" -s 21million.schema -f 21million.rdf.gz
```

### Client authentication

The server option `--tls_client_auth` accepts different values that change the security policty of client certificate verification.
#### mTLS (Mutual TLS) options

The following configuration options are available for Alpha:

* `--tls_dir string` - TLS dir path; this enables TLS connections (usually 'tls').
* `--tls_use_system_ca` - Include System CA with Dgraph Root CA.
* `--tls_client_auth string` - TLS client authentication used to validate client connection. See [Client Authentication Options](#client-authentication-options) for details.

```sh
# First, create a rootca, node, and client certificates and private keys
$ dgraph cert -n localhost -c dgraphuser
# Default use for enabling TLS server with client authentication (after generating certificates and private keys)
$ dgraph alpha --tls_dir tls --tls_client_auth="REQUIREANDVERIFY"
```

| Value | Description |
|-------|-------------|
| REQUEST | Server accepts any certificate, invalid and unverified (least secure) |
| REQUIREANY | Server expects any certificate, valid and unverified |
| VERIFYIFGIVEN | Client certificate is verified if provided (default) |
| REQUIREANDVERIFY | Always require a valid certificate (most secure) |
Dgraph Live Loader can be configured with following options:

* `--tls_cacert string` - Dgraph Root CA, such as `./tls/ca.crt`
* `--tls_use_system_ca` - Include System CA with Dgraph Root CA.
* `--tls_cert` - User cert file provided by the client to Alpha
* `--tls_key` - User private key file provided by the client to Alpha
* `--tls_server_name string` - Server name, used for validating the server's TLS host name.

```sh
# Now, connect to server using mTLS (mutual TLS)
$ dgraph live \
--tls_cacert ./tls/ca.crt \
--tls_cert ./tls/client.dgraphuser.crt \
--tls_key ./tls/client.dgraphuser.key \
--tls_server_name "localhost" \
-s 21million.schema \
-f 21million.rdf.gz
```

#### Client Authentication Options

The server will always REQUEST Client Authentication **only** when the `--tls_client_auth` option is specified. There are four different values that change the security policy of the client certificate.

| Value | Client Cert/Key | Client Certificate Verified |
|--------------------|-----------------|--------------------|
| `REQUEST` | optional | Client certificate is not VERIFIED if provided. (least secure) |
| `REQUIREANY` | required | Client certificate is never VERIFIED |
| `VERIFYIFGIVEN` | optional | Client certificate is VERIFIED if provided (default) |
| `REQUIREANDVERIFY` | required | Client certificate is always VERIFIED (most secure) |

{{% notice "note" %}}REQUIREANDVERIFY is the most secure but also the most difficult to configure for remote clients. When using this value, the value of `--tls_server_name` is matched against the certificate SANs values and the connection host.{{% /notice %}}

Expand Down Expand Up @@ -1700,23 +1734,21 @@ succeed.

### Using Curl with Client authentication

When TLS is enabled, `curl` requests to Dgraph will need some specific options to work.

If the `--tls_client_auth` option is set to `REQUEST`or `VERIFYIFGIVEN` (default),
use the option `--cacert`. For instance (for an export request):
When TLS is enabled, `curl` requests to Dgraph will need some specific options to work. For instance (for an export request):

```
curl --cacert ./tls/ca.crt https://localhost:8080/admin/export
curl --silent --cacert ./tls/ca.crt https://localhost:8080/admin/export
darkn3rd marked this conversation as resolved.
Show resolved Hide resolved
```

If the `--tls_client_auth` option is set to `REQUIREANY` or `REQUIREANDVERIFY`,
in addition to the `--cacert` option, also use the `--cert` and `--key` options.
For instance (for an export request):
If you are using `curl` with [Client Authentication](#client-authentication), you will need to provide the client certificate and private key. For instance (for an export request):

```
curl --cacert ./tls/ca.crt --cert ./tls/node.crt --key ./tls/node.key https://localhost:8080/admin/export
curl --silent --cacert ./tls/ca.crt --cert ./tls/client.dgraphuser.crt --key ./tls/client.dgraphuser.key https://localhost:8080/admin/export
```

When the Dgraph alpha is configured with `--tls_client_auth` set to `REQUIREANY` or `REQUIREANDVERIFY`, you are required to provide the client certificate and private key. With `REQUEST`or `VERIFYIFGIVEN`, providing the client certificate and private key is optional. See [Client Authentication Options](#client-authentication-options) for details.


Refer to the `curl` documentation for further information on its TLS options.

### Access Data Using a Client
Expand Down Expand Up @@ -1796,10 +1828,10 @@ $ dgraph live -f <path-to-gzipped-RDf-or-JSON-file> -s <path-to-schema-file> -a

#### Encrypted imports via Live Loader

A new flag keyfile is added to the Live Loader. This option is required to decrypt the encrypted export data and schema files. Once the export files are decrypted, the Live Loader streams the data to a live Alpha instance.
A new flag keyfile is added to the Live Loader. This option is required to decrypt the encrypted export data and schema files. Once the export files are decrypted, the Live Loader streams the data to a live Alpha instance.

{{% notice "note" %}}
If the live Alpha instance has encryption turned on, the `p` directory will be encrypted. Otherwise, the `p` directory is unencrypted.
If the live Alpha instance has encryption turned on, the `p` directory will be encrypted. Otherwise, the `p` directory is unencrypted.
{{% /notice %}}

#### Encrypted RDF/JSON file and schema via Live Loader
Expand Down Expand Up @@ -1978,7 +2010,7 @@ dgraph bulk --encryption_key_file ./enc_key_file -f data.json.gz -s data.schema

#### Encrypting imports via Bulk Loader

The Bulk Loader’s `encryption_key_file` option was previously used to encrypt the output `p ` directory. This same option will also be used to decrypt the encrypted export data and schema files.
The Bulk Loader’s `encryption_key_file` option was previously used to encrypt the output `p ` directory. This same option will also be used to decrypt the encrypted export data and schema files.

Another option, `--encrypted`, indicates whether the input `rdf`/`json` data and schema files are encrypted or not. With this switch, we support the use case of migrating data from unencrypted exports to encrypted import.

Expand Down