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 1 commit
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
59 changes: 46 additions & 13 deletions wiki/content/deploy/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1537,14 +1537,14 @@ $ 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
darkn3rd marked this conversation as resolved.
Show resolved Hide resolved
$ dgraph cert -n localhost

# Create client certificate
# Create client certificate for mTLS
darkn3rd marked this conversation as resolved.
Show resolved Hide resolved
$ 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
Expand Down Expand Up @@ -1641,22 +1641,54 @@ The following configuration options are available for Alpha:
* `--tls_client_auth string` - TLS client authentication used to validate client connection. See [Client authentication](#client-authentication) for details.

```sh
# First, create rootca and node certificates
darkn3rd marked this conversation as resolved.
Show resolved Hide resolved
$ dgraph cert -n localhost
# Default use for enabling TLS server (after generating certificates)
$ 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_cacert ./tls/ca.crt --tls_server_name "localhost" -s 21million.schema -f 21million.rdf.gz
```

### mTLS (Mutual TLS) options
darkn3rd marked this conversation as resolved.
Show resolved Hide resolved

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. mTLS will require either `REQUIREANY` or `REQUIREANDVERIFY` for this setting. See [Client authentication](#client-authentication) for details.
darkn3rd marked this conversation as resolved.
Show resolved Hide resolved

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

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 TLS
$ dgraph live --tls_dir tls -s 21million.schema -f 21million.rdf.gz
$ dgraph live \
--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
Expand Down Expand Up @@ -1706,15 +1738,16 @@ If the `--tls_client_auth` option is set to `REQUEST`or `VERIFYIFGIVEN` (default
use the option `--cacert`. 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):

```
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 \
darkn3rd marked this conversation as resolved.
Show resolved Hide resolved
--key ./tls/client.dgraphuser.key https://localhost:8080/admin/export
```

Refer to the `curl` documentation for further information on its TLS options.
Expand Down Expand Up @@ -1796,10 +1829,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 +2011,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