Skip to content

Commit

Permalink
mTLS/TLS documentation fixes (#5382) (#5870)
Browse files Browse the repository at this point in the history 
* doc: wiki deploy fixes for mTLS/TLS dgraph live, dgraph cert, curl (cherry picked from commit cd454e5)
  • Loading branch information
@darkn3rd
darkn3rd authored Jul 8, 2020
1 parent ddab2a3 commit ceac69f
Showing 1 changed file with 66 additions and 39 deletions.
105 changes: 66 additions & 39 deletions wiki/content/deploy/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1563,9 +1563,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 @@ -1574,20 +1574,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 @@ -1620,7 +1620,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 @@ -1669,43 +1669,75 @@ Important points:
* Node certificates are only valid for the hosts listed.
* Client certificates are only valid for the named client/user.

### TLS options
### 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](#client-authentication) for details.
* `--tls_client_auth string` - TLS client authentication used to validate client connection. See [Client Authentication Options](#client-authentication-options) for details.

Dgraph Live Loader can be configured with the 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.


#### Using TLS without Client Authentication

For TLS without client authentication, you can configure certificates and run Alpha server using the following:

```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:
You can then run Dgraph live loader using the following:

* `--tls_dir string` - TLS dir path; this enables TLS connections (usually 'tls').
* `--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
# Now, connect to server using TLS
$ dgraph live --tls_cacert ./tls/ca.crt --tls_server_name "localhost" -s 21million.schema -f 21million.rdf.gz
```

#### Using TLS with Client Authentication

If you do require Client Authentication (Mutual TLS), you can configure certificates and run Alpha server using the following:

```sh
# First, create a client certificate for live loader. This will create 'tls/client.live.crt'
$ dgraph cert -c live
# 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"
```

# Now, connect to server using TLS
$ dgraph live --tls_dir tls -s 21million.schema -f 21million.rdf.gz
You can then run Dgraph live loader using the following:

```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
#### Client Authentication Options

The server option `--tls_client_auth` accepts different values that change the security policty of client certificate verification.
The server will always **request** Client Authentication. There are four different values for the `--tls_client_auth` option that change the security policy of the client certificate.

| 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) |
| 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 @@ -1737,21 +1769,16 @@ 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
```

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-options) set to `REQUIREANY` or `REQUIREANDVERIFY`, 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
```

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

0 comments on commit ceac69f

Please sign in to comment.