mTLS/TLS documentation fixes

[darkn3rd]

mTLS/TLS documentation fixes

The text for using setting up dgraph alpha and using clients of dgraph live or curl are not correct and could compromise security. This PR fixes those specific issues.

Affects:

• TLS doc instructions with curl circumvent security by distributing private key #5363
• TLS Options Documentation Not Working with v20.03.1 #5350
• TLS Self Signed Certificate Docs for Dgraph Live #5349

---

This change is 

Docs Preview:

[danielmai]

Reviewable status: 0 of 1 files reviewed, 5 unresolved discussions (waiting on @danielmai, @darkn3rd, @MichaelJCompton, and @MichelDiz)

---

wiki/content/deploy/index.md, line 1652 at r1 (raw file):

.tls/ca.crt

tls/ca.crt ("tls", not ".tls"). Or, ./tls/ca.crt.

---

wiki/content/deploy/index.md, line 1678 at r1 (raw file):

.tls/ca.crt

tls/ca.crt ("tls", not ".tls"). Or, ./tls/ca.crt.

---

wiki/content/deploy/index.md, line 1680 at r1 (raw file):

 \

Do we need these backslashes at the end? I think they can be removed.

---

wiki/content/deploy/index.md, line 1687 at r1 (raw file):

# Now, connect to server using TLS
$ dgraph live \
   --tls_cert ./tls/client.dgraphuser.crt \

Do we need to use --tls_cacert here? It was covered above.

---

wiki/content/deploy/index.md, line 1749 at r1 (raw file):

--silent 

Why are we adding --silent?

[parasssh]

Got few comments.

[parasssh]

Reviewable status: 0 of 1 files reviewed, 13 unresolved discussions (waiting on @danielmai, @darkn3rd, @MichaelJCompton, and @MichelDiz)

---

wiki/content/deploy/index.md, line 1661 at r2 (raw file):

mTLS (Mutual TLS) options

This section can be folded into the Client Authentication section because Client Authentication really just means mTLS.

---

wiki/content/deploy/index.md, line 1701 at r2 (raw file):

| Value | Description |
|-------|-------------|
| REQUEST | Server accepts any certificate, invalid and unverified (least secure) |

While you are at it, please rephrase this table to say the following:

REQUEST -> Client-Certificate is requested. The client may or may not provide a certificate. The certificate, if provided, is not verified. (least secure)

REQUIREANY -> Client-Certificate is requested. The client must provide a certificate. The certificate is not verified.

VERIFYIFGIVEN -> Client-Certtificate is requested. The client may or may not provide a certificate. The certificate, if provided, is verified. (default)

REQUIREANDVERIFY -> Client-Certtificate is requested. The client must provide a certificate. The certificate, if provided, is verified. (most secure)

[parasssh]

Reviewable status: 0 of 1 files reviewed, 15 unresolved discussions (waiting on @danielmai, @darkn3rd, @MichaelJCompton, and @MichelDiz)

---

wiki/content/deploy/index.md, line 1529 at r2 (raw file):

{{% 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

This is incorrect heading. The certificate are not Self-Signed.

Rename it to "Dgraph Certificate Management tool"

---

wiki/content/deploy/index.md, line 1531 at r2 (raw file):

### Self-signed certificates

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

replace self-signed certificates -> CA-signed certificates and private-keys

[darkn3rd]

Reviewable status: 0 of 1 files reviewed, 14 unresolved discussions (waiting on @danielmai, @MichaelJCompton, @MichelDiz, and @parasssh)

---

wiki/content/deploy/index.md, line 1540 at r1 (raw file):

Previously, parasssh wrote…

Create node certificate and private key.

Done.

---

wiki/content/deploy/index.md, line 1543 at r1 (raw file):

Previously, parasssh wrote…

Create client certificate and private key for mTLS (mutual TLS)

Done.

---

wiki/content/deploy/index.md, line 1644 at r1 (raw file):

Previously, parasssh wrote…

... and private keys.

Done.

---

wiki/content/deploy/index.md, line 1652 at r1 (raw file):

Previously, danielmai (Daniel Mai) wrote…

.tls/ca.crt

tls/ca.crt ("tls", not ".tls"). Or, ./tls/ca.crt.

Done.

---

wiki/content/deploy/index.md, line 1678 at r1 (raw file):

Previously, danielmai (Daniel Mai) wrote…

.tls/ca.crt

tls/ca.crt ("tls", not ".tls"). Or, ./tls/ca.crt.

Done.

---

wiki/content/deploy/index.md, line 1680 at r1 (raw file):

Previously, danielmai (Daniel Mai) wrote…

 \

Do we need these backslashes at the end? I think they can be removed.

Done.

---

wiki/content/deploy/index.md, line 1687 at r1 (raw file):

Previously, danielmai (Daniel Mai) wrote…

Do we need to use --tls_cacert here? It was covered above.

Done.

---

wiki/content/deploy/index.md, line 1749 at r1 (raw file):

Previously, danielmai (Daniel Mai) wrote…

--silent 

Why are we adding --silent?

Done.

---

wiki/content/deploy/index.md, line 1529 at r2 (raw file):

Previously, parasssh wrote…

This is incorrect heading. The certificate are not Self-Signed.

Rename it to "Dgraph Certificate Management tool"

Done.

---

wiki/content/deploy/index.md, line 1531 at r2 (raw file):

Previously, parasssh wrote…

replace self-signed certificates -> CA-signed certificates and private-keys

Done.

---

wiki/content/deploy/index.md, line 1661 at r2 (raw file):

Previously, parasssh wrote…

This section can be folded into the Client Authentication section because Client Authentication really just means mTLS.

I think I fixed it.

---

wiki/content/deploy/index.md, line 1667 at r2 (raw file):

Previously, darkn3rd (Joaquin Menchaca) wrote…

Thank you for explanation.

Done.

---

wiki/content/deploy/index.md, line 1701 at r2 (raw file):

Previously, parasssh wrote…

While you are at it, please rephrase this table to say the following:

REQUEST -> Client-Certificate is requested. The client may or may not provide a certificate. The certificate, if provided, is not verified. (least secure)

REQUIREANY -> Client-Certificate is requested. The client must provide a certificate. The certificate is not verified.

VERIFYIFGIVEN -> Client-Certtificate is requested. The client may or may not provide a certificate. The certificate, if provided, is verified. (default)

REQUIREANDVERIFY -> Client-Certtificate is requested. The client must provide a certificate. The certificate, if provided, is verified. (most secure)

I chose a different approach, let me know if this works.
I can add another column for Client Verified?, but given word VERIFY in option, seems self-documenting.

---

wiki/content/deploy/index.md, line 1742 at r2 (raw file):

Previously, darkn3rd (Joaquin Menchaca) wrote…

I was getting progress bar for a small query. Do we want users to have progress bar for small queries. Progress bars are fine for downloading tarballs, but for API, not the preferred experience.

Done.

[parasssh]

Reviewable status: 0 of 1 files reviewed, 15 unresolved discussions (waiting on @danielmai, @darkn3rd, @MichaelJCompton, @MichelDiz, and @parasssh)

---

wiki/content/deploy/index.md, line 1661 at r2 (raw file):

Previously, darkn3rd (Joaquin Menchaca) wrote…

I think I fixed it.

I meant move this entire section under Client Authentication

---

wiki/content/deploy/index.md, line 1701 at r2 (raw file):

Previously, darkn3rd (Joaquin Menchaca) wrote…

I chose a different approach, let me know if this works.
I can add another column for Client Verified?, but given word VERIFY in option, seems self-documenting.

Its better to spell it out. As discussed on Slack, we can have 4 columns and 5 rows (4 for the options and 5th for option absent).

[darkn3rd]

Reviewable status: 0 of 1 files reviewed, 15 unresolved discussions (waiting on @danielmai, @darkn3rd, @MichaelJCompton, @MichelDiz, and @parasssh)

---

wiki/content/deploy/index.md, line 1749 at r1 (raw file):

Previously, darkn3rd (Joaquin Menchaca) wrote…

Done.

Progress Bar for API is not intuitive.

---

wiki/content/deploy/index.md, line 1661 at r2 (raw file):

Previously, parasssh wrote…

I meant move this entire section under Client Authentication

Done.

---

wiki/content/deploy/index.md, line 1701 at r2 (raw file):

Previously, parasssh wrote…

Its better to spell it out. As discussed on Slack, we can have 4 columns and 5 rows (4 for the options and 5th for option absent).

Done.

---

wiki/content/deploy/index.md, line 1701 at r3 (raw file):

Previously, parasssh wrote…

Please change all "Description" to what I provided in previous comment.

Done.

[darkn3rd]

These were resolved in a later commit, I am not sure why this UI shows up.

[darkn3rd]

These were resolved in a later commit.

[darkn3rd]

These were all marked resolved and addressed in commit after this point.

[danielmai]

A few comments, and then .

Reviewed 1 of 1 files at r4.
Reviewable status: all files reviewed, 14 unresolved discussions (waiting on @darkn3rd and @parasssh)

---

wiki/content/deploy/index.md, line 1662 at r4 (raw file):

### Client authentication

#### mTLS (Mutual TLS) options

We can remove this header. Keep everything saying "Client authentication".

---

wiki/content/deploy/index.md, line 1664 at r4 (raw file):

The following configuration options are available for Alpha:

Dgraph Alpha can be configured with the following options for client authentication

(This phrasing follows the parallelism with the next paragraph about live loader).

---

wiki/content/deploy/index.md, line 1677 at r4 (raw file):

with following options:

with the following options:

---

wiki/content/deploy/index.md, line 1698 at r4 (raw file):

The server will always REQUEST Client Authentication **only** when the `--tls_client_auth` option is specified. 

We can remove this sentence. --tls_client_auth has a default value of VERIFYIFGIVEN, so this sentence doesn't really make sense.

[darkn3rd]

Reviewable status: 0 of 1 files reviewed, 14 unresolved discussions (waiting on @danielmai and @parasssh)

---

wiki/content/deploy/index.md, line 1661 at r3 (raw file):

Previously, parasssh wrote…

Still think it is a good idea to fold this into Client Authentication section below.

Everything is client authentication.

---

wiki/content/deploy/index.md, line 1662 at r4 (raw file):

Previously, danielmai (Daniel Mai) wrote…

We can remove this header. Keep everything saying "Client authentication".

Done.

---

wiki/content/deploy/index.md, line 1664 at r4 (raw file):

Previously, danielmai (Daniel Mai) wrote…

The following configuration options are available for Alpha:

Dgraph Alpha can be configured with the following options for client authentication

(This phrasing follows the parallelism with the next paragraph about live loader).

This has been revised. Before misunderstanding, so revised to have one common section, and detail commands for with and without client auth.

---

wiki/content/deploy/index.md, line 1677 at r4 (raw file):

Previously, danielmai (Daniel Mai) wrote…

with following options:

with the following options:

Done.

---

wiki/content/deploy/index.md, line 1698 at r4 (raw file):

Previously, danielmai (Daniel Mai) wrote…

The server will always REQUEST Client Authentication **only** when the `--tls_client_auth` option is specified. 

We can remove this sentence. --tls_client_auth has a default value of VERIFYIFGIVEN, so this sentence doesn't really make sense.

This sentence have been revised.

[darkn3rd]

Reviewable status: 0 of 1 files reviewed, 14 unresolved discussions (waiting on @danielmai and @parasssh)

[danielmai]

Reviewable status: 0 of 1 files reviewed, 14 unresolved discussions (waiting on @danielmai and @parasssh)