From 33ca546f67f13ba4ae4f74011a9e38c4bd6e081f Mon Sep 17 00:00:00 2001
From: Amruta <amruta@cockroachlabs.com>
Date: Wed, 8 Apr 2020 19:31:46 -0400
Subject: [PATCH 01/12] Updated the openssl doc

---
 v20.1/create-security-certificates-openssl.md | 92 +++++++++++--------
 1 file changed, 55 insertions(+), 37 deletions(-)

diff --git a/v20.1/create-security-certificates-openssl.md b/v20.1/create-security-certificates-openssl.md
index a566a46adbd..abf4ef4742e 100644
--- a/v20.1/create-security-certificates-openssl.md
+++ b/v20.1/create-security-certificates-openssl.md
@@ -68,20 +68,16 @@ Note the following:
 
 ## Examples
 
-### Create the CA key and certificate pair
+### Step 1. Create the CA key and certificate pair
 
-1. Create two directories:
+1. Create three directories:
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ mkdir certs
+    $ mkdir node-certs client-certs my-safe-directory
     ~~~
-
-    {% include copy-clipboard.html %}
-    ~~~ shell
-    $ mkdir my-safe-directory
-    ~~~
-    - `certs`: Create your CA certificate and all node and client certificates and keys in this directory and then upload the relevant files to the nodes and clients.
+    - `node-certs`: Create your CA certificate and all node certificates and keys in this directory and then upload the relevant files to the nodes.
+    - `client-certs`: Copy your CA certificate to this folder and create all client certificates and keys in this directory and then upload the relevant files to the clients.
     - `my-safe-directory`: Create your CA key in this directory and then reference the key when generating node and client certificates. After that, keep the key safe and secret; do not upload it to your nodes or clients.
 
 2. Create the `ca.cnf` file and copy the following configuration into it.
@@ -154,7 +150,7 @@ Note the following:
     -x509 \
     -config ca.cnf \
     -key my-safe-directory/ca.key \
-    -out certs/ca.crt \
+    -out node-certs/ca.crt \
     -days 3660 \
     -batch
     ~~~
@@ -174,7 +170,7 @@ Note the following:
     $ echo '01' > serial.txt
     ~~~
 
-### Create the certificate and key pairs for nodes
+### Step 2. Create the certificate and key pairs for nodes
 
 In the following steps, replace the placeholder text in the code with the actual username and node address.
 
@@ -190,24 +186,23 @@ In the following steps, replace the placeholder text in the code with the actual
 
     [ distinguished_name ]
     organizationName = Cockroach
-    # Required value for commonName, do not change.
-    commonName = node
+    commonName = DNS:<node-hostname>,DNS:<node-domain>,IP:<IP Address>
 
     [ extensions ]
     subjectAltName = DNS:<node-hostname>,DNS:<node-domain>,IP:<IP Address>
     ~~~
 
-    {{site.data.alerts.callout_danger}}The <code>commonName</code> and <code>subjectAltName</code> parameters are vital for CockroachDB functions. It is also required that <code>commonName</code> be set to <code>node</code>. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the <code>commonName</code> and <code>subjectAltName</code> parameters.  {{site.data.alerts.end}}
+    {{site.data.alerts.callout_danger}}The <code>commonName</code> and <code>subjectAltName</code> parameters are vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the <code>commonName</code> and <code>subjectAltName</code> parameters.  {{site.data.alerts.end}}
 
 2. Create the key for the first node using the [`openssl genrsa`](https://www.openssl.org/docs/manmaster/man1/genrsa.html) command:
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ openssl genrsa -out certs/node.key 2048
+    $ openssl genrsa -out node-certs/node.key 2048
     ~~~
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ chmod 400 certs/node.key
+    $ chmod 400 node-certs/node.key
     ~~~
 
 3. Create the CSR for the first node using the [`openssl req`](https://www.openssl.org/docs/manmaster/man1/req.html) command:
@@ -217,7 +212,7 @@ In the following steps, replace the placeholder text in the code with the actual
     $ openssl req \
     -new \
     -config node.cnf \
-    -key certs/node.key \
+    -key node-certs/node.key \
     -out node.csr \
     -batch
     ~~~
@@ -231,11 +226,11 @@ In the following steps, replace the placeholder text in the code with the actual
     $ openssl ca \
     -config ca.cnf \
     -keyfile my-safe-directory/ca.key \
-    -cert certs/ca.crt \
+    -cert node-certs/ca.crt \
     -policy signing_policy \
     -extensions signing_node_req \
-    -out certs/node.crt \
-    -outdir certs/ \
+    -out node-certs/node.crt \
+    -outdir node-certs/ \
     -in node.csr \
     -days 1830 \
     -batch
@@ -245,35 +240,42 @@ In the following steps, replace the placeholder text in the code with the actual
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ ssh <username>@<node1 address> "mkdir certs"
+    $ ssh <username>@<node1 address> "mkdir node-certs"
     ~~~
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ scp certs/ca.crt \
-    certs/node.crt \
-    certs/node.key \
-    <username>@<node1 address>:~/certs
+    $ scp node-certs/ca.crt \
+    node-certs/node.crt \
+    Node-certs/node.key \
+    <username>@<node1 address>:~/node-certs
     ~~~
 
 6. Delete the local copy of the first node's certificate and key:
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ rm certs/node.crt certs/node.key
+    $ rm node-certs/node.crt node-certs/node.key
     ~~~
 
     {{site.data.alerts.callout_info}}This is necessary because the certificates and keys for additional nodes will also be named <code>node.crt</code> and <code>node.key</code>.{{site.data.alerts.end}}
 
 7. Repeat steps 1 - 6 for each additional node.
 
-8. Remove the `.pem` files in the `certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
+8. Remove the `.pem` files in the `node-certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
 
-### Create the certificate and key pair for a client
+### Step 3. Create the certificate and key pair for a client
 
 In the following steps, replace the placeholder text in the code with the actual username.
 
-1. Create the `client.cnf` file for the first client and copy the following configuration into it:
+1. Copy the `ca.crt` from the `node-certs` directory to the `client-certs` directory
+
+    {% include copy-clipboard.html %}
+    ~~~ shell
+    $ cp node-certs/ca.crt client-certs
+    ~~~
+
+2. Create the `client.cnf` file for the first client and copy the following configuration into it:
 
     {% include copy-clipboard.html %}
     ~~~
@@ -286,17 +288,17 @@ In the following steps, replace the placeholder text in the code with the actual
     commonName = <username>
     ~~~
 
-    {{site.data.alerts.callout_info}}The <code>commonName</code> parameter is vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the <code>commonName</code> parameter.  {{site.data.alerts.end}}
+    {{site.data.alerts.callout_danger}}The <code>commonName</code> parameter is vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the <code>commonName</code> parameter.  {{site.data.alerts.end}}
 
 2. Create the key for the first client using the [`openssl genrsa`](https://www.openssl.org/docs/manmaster/man1/genrsa.html) command:
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ openssl genrsa -out certs/client.<username>.key 2048
+    $ openssl genrsa -out client-certs/client.<username>.key 2048
     ~~~
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ chmod 400 certs/client.<username>.key
+    $ chmod 400 client-certs/client.<username>.key
     ~~~
 
 3. Create the CSR for the first client using the [`openssl req`](https://www.openssl.org/docs/manmaster/man1/req.html) command:
@@ -306,7 +308,7 @@ In the following steps, replace the placeholder text in the code with the actual
     $ openssl req \
     -new \
     -config client.cnf \
-    -key certs/client.<username>.key \
+    -key client-certs/client.<username>.key \
     -out client.<username>.csr \
     -batch
     ~~~
@@ -318,11 +320,11 @@ In the following steps, replace the placeholder text in the code with the actual
     $ openssl ca \
     -config ca.cnf \
     -keyfile my-safe-directory/ca.key \
-    -cert certs/ca.crt \
+    -cert client-certs/ca.crt \
     -policy signing_policy \
     -extensions signing_client_req \
-    -out certs/client.<username>.crt \
-    -outdir certs/ \
+    -out client-certs/client.<username>.crt \
+    -outdir client-certs/ \
     -in client.<username>.csr \
     -days 1830 \
     -batch
@@ -332,7 +334,23 @@ In the following steps, replace the placeholder text in the code with the actual
 
 6. Repeat steps 1 - 5 for each additional client.
 
-7. Remove the `.pem` files in the `certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
+7. Remove the `.pem` files in the `client-certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
+
+### Step 4. Start a local cluster and connect using the SQL client
+
+1. Start a single-node cluster:
+
+    {% include copy-clipboard.html %}
+    ~~~ shell
+    $ cockroach start-single-node --certs-dir=node-certs --cert-principal-map=node.crdb.io:node --background
+    ~~~
+
+2. Connect to the cluster using the built-in SQL client:
+
+    {% include copy-clipboard.html %}
+    ~~~ shell
+    $ cockroach sql --certs-dir=client-certs
+    ~~~
 
 ## See also
 

From 951e3db58504cc0b1680b93d5007d008a74052ad Mon Sep 17 00:00:00 2001
From: Amruta <amruta@cockroachlabs.com>
Date: Wed, 8 Apr 2020 20:42:52 -0400
Subject: [PATCH 02/12] Working on Peter's comments + updated cockroach start
 doc

---
 v20.1/cockroach-start.md                      | 1 +
 v20.1/create-security-certificates-openssl.md | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/v20.1/cockroach-start.md b/v20.1/cockroach-start.md
index 8ee0a9735ef..30fceba413f 100644
--- a/v20.1/cockroach-start.md
+++ b/v20.1/cockroach-start.md
@@ -86,6 +86,7 @@ Flag | Description
 -----|-----------
 `--certs-dir` | The path to the [certificate directory](cockroach-cert.html). The directory must contain valid certificates if running in secure mode.<br><br>**Default:** `${HOME}/.cockroach-certs/`
 `--insecure` | Run in insecure mode. If this flag is not set, the `--certs-dir` flag must point to valid certificates.<br><br><strong>Note the following risks:</strong> An insecure cluster is open to any client that can access any node's IP addresses; any user, even `root`, can log in without providing a password; any user, connecting as `root`, can read or write any data in your cluster; and there is no network encryption or authentication, and thus no confidentiality.<br><br>**Default:** `false`
+`--cert-principal-map` | A comma-separated list of `cert-principal:db-principal` mappings used to map the certificate principals to IP addresses, DNS names, and SQL users. This allows the use of certificates generated by Certificate Authorities that place restrictions on the contents of the `commonName` field. For usage information, see [Create Security Certificates using Openssl](create-security-certificates-openssl.html#examples)
 `--enterprise-encryption` | This optional flag specifies the encryption options for one of the stores on the node. If multiple stores exist, the flag must be specified for each store. <br /><br /> This flag takes a number of options.  For a complete list of options, and usage instructions, see [Encryption at Rest](encryption.html). <br /><br /> Note that this is an [enterprise feature](enterprise-licensing.html).
 
 ### Locality
diff --git a/v20.1/create-security-certificates-openssl.md b/v20.1/create-security-certificates-openssl.md
index abf4ef4742e..c9f5e69b555 100644
--- a/v20.1/create-security-certificates-openssl.md
+++ b/v20.1/create-security-certificates-openssl.md
@@ -342,7 +342,7 @@ In the following steps, replace the placeholder text in the code with the actual
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ cockroach start-single-node --certs-dir=node-certs --cert-principal-map=node.crdb.io:node --background
+    $ cockroach start-single-node --certs-dir=node-certs --cert-principal-map=<node-domain>:node --background
     ~~~
 
 2. Connect to the cluster using the built-in SQL client:

From 3086c5e5dd73a313d4248d6832ad258014d0e5b5 Mon Sep 17 00:00:00 2001
From: Amruta <amruta@cockroachlabs.com>
Date: Thu, 9 Apr 2020 16:36:23 -0400
Subject: [PATCH 03/12] Worked on Aaron and Artem's review comments

---
 v20.1/create-security-certificates-openssl.md | 104 +++++++++++++++---
 1 file changed, 89 insertions(+), 15 deletions(-)

diff --git a/v20.1/create-security-certificates-openssl.md b/v20.1/create-security-certificates-openssl.md
index c9f5e69b555..49e70bc8de5 100644
--- a/v20.1/create-security-certificates-openssl.md
+++ b/v20.1/create-security-certificates-openssl.md
@@ -115,7 +115,7 @@ Note the following:
     # Common policy for nodes and users.
     [ signing_policy ]
     organizationName = supplied
-    commonName = supplied
+    commonName = optional
 
     # Used to sign node certificates.
     [ signing_node_req ]
@@ -186,13 +186,12 @@ In the following steps, replace the placeholder text in the code with the actual
 
     [ distinguished_name ]
     organizationName = Cockroach
-    commonName = DNS:<node-hostname>,DNS:<node-domain>,IP:<IP Address>
 
     [ extensions ]
-    subjectAltName = DNS:<node-hostname>,DNS:<node-domain>,IP:<IP Address>
+    subjectAltName = critical,DNS:<node-hostname>,DNS:<node-domain>,IP:<IP Address>
     ~~~
 
-    {{site.data.alerts.callout_danger}}The <code>commonName</code> and <code>subjectAltName</code> parameters are vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the <code>commonName</code> and <code>subjectAltName</code> parameters.  {{site.data.alerts.end}}
+    {{site.data.alerts.callout_danger}}The <code>subjectAltName</code> parameter is vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the <code>subjectAltName</code> parameter.  {{site.data.alerts.end}}
 
 2. Create the key for the first node using the [`openssl genrsa`](https://www.openssl.org/docs/manmaster/man1/genrsa.html) command:
 
@@ -264,9 +263,7 @@ In the following steps, replace the placeholder text in the code with the actual
 
 8. Remove the `.pem` files in the `node-certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
 
-### Step 3. Create the certificate and key pair for a client
-
-In the following steps, replace the placeholder text in the code with the actual username.
+### Step 3. Create the certificate and key pair for the `root` user
 
 1. Copy the `ca.crt` from the `node-certs` directory to the `client-certs` directory
 
@@ -275,7 +272,7 @@ In the following steps, replace the placeholder text in the code with the actual
     $ cp node-certs/ca.crt client-certs
     ~~~
 
-2. Create the `client.cnf` file for the first client and copy the following configuration into it:
+2. Create the `client.cnf` file for the `root` user and copy the following configuration into it:
 
     {% include copy-clipboard.html %}
     ~~~
@@ -285,7 +282,7 @@ In the following steps, replace the placeholder text in the code with the actual
 
     [ distinguished_name ]
     organizationName = Cockroach
-    commonName = <username>
+    commonName = root
     ~~~
 
     {{site.data.alerts.callout_danger}}The <code>commonName</code> parameter is vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the <code>commonName</code> parameter.  {{site.data.alerts.end}}
@@ -294,11 +291,11 @@ In the following steps, replace the placeholder text in the code with the actual
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ openssl genrsa -out client-certs/client.<username>.key 2048
+    $ openssl genrsa -out client-certs/client.root.key 2048
     ~~~
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ chmod 400 client-certs/client.<username>.key
+    $ chmod 400 client-certs/client.root.key
     ~~~
 
 3. Create the CSR for the first client using the [`openssl req`](https://www.openssl.org/docs/manmaster/man1/req.html) command:
@@ -308,8 +305,8 @@ In the following steps, replace the placeholder text in the code with the actual
     $ openssl req \
     -new \
     -config client.cnf \
-    -key client-certs/client.<username>.key \
-    -out client.<username>.csr \
+    -key client-certs/client.root.key \
+    -out client.root.csr \
     -batch
     ~~~
 
@@ -323,9 +320,9 @@ In the following steps, replace the placeholder text in the code with the actual
     -cert client-certs/ca.crt \
     -policy signing_policy \
     -extensions signing_client_req \
-    -out client-certs/client.<username>.crt \
+    -out client-certs/client.root.crt \
     -outdir client-certs/ \
-    -in client.<username>.csr \
+    -in client.root.csr \
     -days 1830 \
     -batch
     ~~~    
@@ -352,6 +349,83 @@ In the following steps, replace the placeholder text in the code with the actual
     $ cockroach sql --certs-dir=client-certs
     ~~~
 
+3. Create a SQL user:
+
+    {% include copy-clipboard.html %}
+    ~~~ sql
+    > create user <username>;
+    ~~~
+
+    {% include copy-clipboard.html %}
+    ~~~ sql
+    > \q
+    ~~~
+
+### Step 5. Create the certificate and key pair for a client
+
+In the following steps, replace the placeholder text in the code with the actual username.
+
+1. Create the `client.cnf` file for the client and copy the following configuration into it:
+
+    {% include copy-clipboard.html %}
+    ~~~
+    [ req ]
+    prompt=no
+    distinguished_name = distinguished_name
+
+    [ distinguished_name ]
+    organizationName = Cockroach
+    commonName = <username>
+    ~~~
+
+    {{site.data.alerts.callout_danger}}The <code>commonName</code> parameter is vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the <code>commonName</code> parameter.  {{site.data.alerts.end}}
+
+2. Create the key for the first client using the [`openssl genrsa`](https://www.openssl.org/docs/manmaster/man1/genrsa.html) command:
+
+    {% include copy-clipboard.html %}
+    ~~~ shell
+    $ openssl genrsa -out client-certs/client.<username>.key 2048
+    ~~~
+    {% include copy-clipboard.html %}
+    ~~~ shell
+    $ chmod 400 client-certs/client.<username>.key
+    ~~~
+
+3. Create the CSR for the first client using the [`openssl req`](https://www.openssl.org/docs/manmaster/man1/req.html) command:
+
+    {% include copy-clipboard.html %}
+    ~~~ shell
+    $ openssl req \
+    -new \
+    -config client.cnf \
+    -key client-certs/client.<username>.key \
+    -out client.<username>.csr \
+    -batch
+    ~~~
+
+4. Sign the client CSR to create the client certificate for the first client using the [`openssl ca`](https://www.openssl.org/docs/manmaster/man1/ca.html) command. You can set the client certificate expiration period using the `days` flag. We recommend using the CockroachDB default value of the client certificate expiration period, which is 1830 days.
+
+    {% include copy-clipboard.html %}
+    ~~~ shell
+    $ openssl ca \
+    -config ca.cnf \
+    -keyfile my-safe-directory/ca.key \
+    -cert client-certs/ca.crt \
+    -policy signing_policy \
+    -extensions signing_client_req \
+    -out client-certs/client.<username>.crt \
+    -outdir client-certs/ \
+    -in client.<username>.csr \
+    -days 1830 \
+    -batch
+    ~~~    
+
+5. Upload certificates to the first client using your preferred method.
+
+6. Repeat steps 1 - 5 for each additional client.
+
+7. Remove the `.pem` files in the `client-certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
+
 ## See also
 
 - [Manual Deployment](manual-deployment.html): Learn about starting a multi-node secure cluster and accessing it from a client.

From 5f35157a2d108b867dcba808e5e778071132df8d Mon Sep 17 00:00:00 2001
From: Amruta <amruta@cockroachlabs.com>
Date: Fri, 10 Apr 2020 12:55:50 -0400
Subject: [PATCH 04/12] Worked on Artem's comments

---
 v20.1/create-security-certificates-openssl.md | 74 +++++++++++++++----
 1 file changed, 59 insertions(+), 15 deletions(-)

diff --git a/v20.1/create-security-certificates-openssl.md b/v20.1/create-security-certificates-openssl.md
index 49e70bc8de5..05194395fed 100644
--- a/v20.1/create-security-certificates-openssl.md
+++ b/v20.1/create-security-certificates-openssl.md
@@ -155,7 +155,7 @@ Note the following:
     -batch
     ~~~
 
-5. Reset database and index files.
+6. Reset database and index files.
 
     {% include copy-clipboard.html %}
     ~~~ shell
@@ -235,7 +235,20 @@ In the following steps, replace the placeholder text in the code with the actual
     -batch
     ~~~
 
-5. Upload certificates to the first node:
+5. Verify the values in the `Subject Alternative Name` field in the certificate:
+
+    {% include copy-clipboard.html %}
+    ~~~ shell
+    $ openssl x509 -in node-certs/node.crt -text | grep "X509v3 Subject Alternative Name" -A 1
+    ~~~
+
+    Example output:
+    ~~~
+    X509v3 Subject Alternative Name: critical
+                DNS:localhost, DNS:node.example.io, IP Address:127.0.0.1
+    ~~~
+
+6. Upload certificates to the first node:
 
     {% include copy-clipboard.html %}
     ~~~ shell
@@ -250,7 +263,7 @@ In the following steps, replace the placeholder text in the code with the actual
     <username>@<node1 address>:~/node-certs
     ~~~
 
-6. Delete the local copy of the first node's certificate and key:
+7. Delete the local copy of the first node's certificate and key:
 
     {% include copy-clipboard.html %}
     ~~~ shell
@@ -259,9 +272,9 @@ In the following steps, replace the placeholder text in the code with the actual
 
     {{site.data.alerts.callout_info}}This is necessary because the certificates and keys for additional nodes will also be named <code>node.crt</code> and <code>node.key</code>.{{site.data.alerts.end}}
 
-7. Repeat steps 1 - 6 for each additional node.
+8. Repeat steps 1 - 6 for each additional node.
 
-8. Remove the `.pem` files in the `node-certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
+9. Remove the `.pem` files in the `node-certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
 
 ### Step 3. Create the certificate and key pair for the `root` user
 
@@ -287,7 +300,7 @@ In the following steps, replace the placeholder text in the code with the actual
 
     {{site.data.alerts.callout_danger}}The <code>commonName</code> parameter is vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the <code>commonName</code> parameter.  {{site.data.alerts.end}}
 
-2. Create the key for the first client using the [`openssl genrsa`](https://www.openssl.org/docs/manmaster/man1/genrsa.html) command:
+3. Create the key for the first client using the [`openssl genrsa`](https://www.openssl.org/docs/manmaster/man1/genrsa.html) command:
 
     {% include copy-clipboard.html %}
     ~~~ shell
@@ -298,7 +311,7 @@ In the following steps, replace the placeholder text in the code with the actual
     $ chmod 400 client-certs/client.root.key
     ~~~
 
-3. Create the CSR for the first client using the [`openssl req`](https://www.openssl.org/docs/manmaster/man1/req.html) command:
+4. Create the CSR for the first client using the [`openssl req`](https://www.openssl.org/docs/manmaster/man1/req.html) command:
 
     {% include copy-clipboard.html %}
     ~~~ shell
@@ -310,7 +323,7 @@ In the following steps, replace the placeholder text in the code with the actual
     -batch
     ~~~
 
-4. Sign the client CSR to create the client certificate for the first client using the [`openssl ca`](https://www.openssl.org/docs/manmaster/man1/ca.html) command. You can set the client certificate expiration period using the `days` flag. We recommend using the CockroachDB default value of the client certificate expiration period, which is 1830 days.
+5. Sign the client CSR to create the client certificate for the first client using the [`openssl ca`](https://www.openssl.org/docs/manmaster/man1/ca.html) command. You can set the client certificate expiration period using the `days` flag. We recommend using the CockroachDB default value of the client certificate expiration period, which is 1830 days.
 
     {% include copy-clipboard.html %}
     ~~~ shell
@@ -327,9 +340,19 @@ In the following steps, replace the placeholder text in the code with the actual
     -batch
     ~~~    
 
-5. Upload certificates to the first client using your preferred method.
+6. Verify the values in the `CN` field in the certificate:
+
+    {% include copy-clipboard.html %}
+    ~~~ shell
+    $ openssl x509 -in client-certs/client.root.crt -text | grep CN=
+    ~~~
 
-6. Repeat steps 1 - 5 for each additional client.
+    Output:
+
+    ~~~
+    Issuer: O=Cockroach, CN=Cockroach CA
+        Subject: O=Cockroach, CN=root
+    ~~~
 
 7. Remove the `.pem` files in the `client-certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
 
@@ -361,11 +384,11 @@ In the following steps, replace the placeholder text in the code with the actual
     > \q
     ~~~
 
-### Step 5. Create the certificate and key pair for a client
+### Step 5. Create the certificate and key pair for a non-`root` client
 
 In the following steps, replace the placeholder text in the code with the actual username.
 
-1. Create the `client.cnf` file for the client and copy the following configuration into it:
+1. Edit the `client.cnf` file for the client and copy the following configuration into it:
 
     {% include copy-clipboard.html %}
     ~~~
@@ -420,11 +443,32 @@ In the following steps, replace the placeholder text in the code with the actual
     -batch
     ~~~    
 
-5. Upload certificates to the first client using your preferred method.
+5. Verify the values in the `CN` field in the certificate:
+
+    {% include copy-clipboard.html %}
+    ~~~ shell
+    $ openssl x509 -in client-certs/client.<username>.crt -text | grep CN=
+    ~~~
 
-6. Repeat steps 1 - 5 for each additional client.
+    Example output:
 
-7. Remove the `.pem` files in the `client-certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
+    ~~~
+    Issuer: O=Cockroach, CN=Cockroach CA
+        Subject: O=Cockroach, CN=roach
+    ~~~
+
+6. Upload certificates to the client using your preferred method.
+
+7. Connect to the SQL client using the client certificate:
+
+    {% include copy-clipboard.html %}
+    ~~~ shell
+    $ cockroach sql --certs-dir=client-certs --user=roach
+    ~~~
+
+8. Repeat steps 1 - 7 for each additional client.
+
+9. Remove the `.pem` files in the `client-certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
 
 ## See also
 

From cbc5f56cea296d17239ff2dff99e7e1456a49c41 Mon Sep 17 00:00:00 2001
From: Amruta <amruta@cockroachlabs.com>
Date: Fri, 10 Apr 2020 13:03:40 -0400
Subject: [PATCH 05/12] nit

---
 v20.1/create-security-certificates-openssl.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/v20.1/create-security-certificates-openssl.md b/v20.1/create-security-certificates-openssl.md
index 05194395fed..b1db34112c5 100644
--- a/v20.1/create-security-certificates-openssl.md
+++ b/v20.1/create-security-certificates-openssl.md
@@ -463,7 +463,7 @@ In the following steps, replace the placeholder text in the code with the actual
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ cockroach sql --certs-dir=client-certs --user=roach
+    $ cockroach sql --certs-dir=client-certs --user=<username>
     ~~~
 
 8. Repeat steps 1 - 7 for each additional client.

From 9dc5d68d52159059083bddc219a79a74c6a12fc5 Mon Sep 17 00:00:00 2001
From: Amruta <amruta@cockroachlabs.com>
Date: Mon, 13 Apr 2020 14:36:07 -0400
Subject: [PATCH 06/12] trying mapping the root to a user

---
 v20.1/create-security-certificates-openssl.md | 70 +++++++++----------
 1 file changed, 34 insertions(+), 36 deletions(-)

diff --git a/v20.1/create-security-certificates-openssl.md b/v20.1/create-security-certificates-openssl.md
index b1db34112c5..939832a754d 100644
--- a/v20.1/create-security-certificates-openssl.md
+++ b/v20.1/create-security-certificates-openssl.md
@@ -82,7 +82,7 @@ Note the following:
 
 2. Create the `ca.cnf` file and copy the following configuration into it.
 
-    You can set the CA certificate expiration period using the `default_days` parameter. We recommend using the CockroachDB default value of the CA certificate expiration period, which is 3660 days.
+    You can set the CA certificate expiration period using the `default_days` parameter. We recommend using the CockroachDB default value of the CA certificate expiration period, which is 365 days.
 
     {% include copy-clipboard.html %}
     ~~~
@@ -91,7 +91,7 @@ Note the following:
     default_ca = CA_default
 
     [ CA_default ]
-    default_days = 3660
+    default_days = 365
     database = index.txt
     serial = serial.txt
     default_md = sha256
@@ -151,7 +151,7 @@ Note the following:
     -config ca.cnf \
     -key my-safe-directory/ca.key \
     -out node-certs/ca.crt \
-    -days 3660 \
+    -days 365 \
     -batch
     ~~~
 
@@ -218,8 +218,6 @@ In the following steps, replace the placeholder text in the code with the actual
 
 4. Sign the node CSR to create the node certificate for the first node using the [`openssl ca`](https://www.openssl.org/docs/manmaster/man1/ca.html) command.
 
-    You can set the node certificate expiration period using the `days` flag. We recommend using the CockroachDB default value of the node certificate expiration period, which is 1830 days.
-
     {% include copy-clipboard.html %}
     ~~~ shell
     $ openssl ca \
@@ -231,7 +229,6 @@ In the following steps, replace the placeholder text in the code with the actual
     -out node-certs/node.crt \
     -outdir node-certs/ \
     -in node.csr \
-    -days 1830 \
     -batch
     ~~~
 
@@ -259,7 +256,7 @@ In the following steps, replace the placeholder text in the code with the actual
     ~~~ shell
     $ scp node-certs/ca.crt \
     node-certs/node.crt \
-    Node-certs/node.key \
+    node-certs/node.key \
     <username>@<node1 address>:~/node-certs
     ~~~
 
@@ -276,7 +273,7 @@ In the following steps, replace the placeholder text in the code with the actual
 
 9. Remove the `.pem` files in the `node-certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
 
-### Step 3. Create the certificate and key pair for the `root` user
+### Step 3. Create the certificate and key pair for the first user
 
 1. Copy the `ca.crt` from the `node-certs` directory to the `client-certs` directory
 
@@ -285,7 +282,7 @@ In the following steps, replace the placeholder text in the code with the actual
     $ cp node-certs/ca.crt client-certs
     ~~~
 
-2. Create the `client.cnf` file for the `root` user and copy the following configuration into it:
+2. Create the `client.cnf` file for the first user and copy the following configuration into it:
 
     {% include copy-clipboard.html %}
     ~~~
@@ -295,20 +292,23 @@ In the following steps, replace the placeholder text in the code with the actual
 
     [ distinguished_name ]
     organizationName = Cockroach
-    commonName = root
+    commonName = <username_1>
+
+    [ extensions ]
+    subjectAltName = DNS:root
     ~~~
 
-    {{site.data.alerts.callout_danger}}The <code>commonName</code> parameter is vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the <code>commonName</code> parameter.  {{site.data.alerts.end}}
+    {{site.data.alerts.callout_danger}}The <code>commonName</code> and <code>subjectAltName</code> parameters are vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the <code>commonName</code> or modify the <code>subjectAltName</code> parameters. {{site.data.alerts.end}}
 
 3. Create the key for the first client using the [`openssl genrsa`](https://www.openssl.org/docs/manmaster/man1/genrsa.html) command:
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ openssl genrsa -out client-certs/client.root.key 2048
+    $ openssl genrsa -out client-certs/client.<username_1>.key 2048
     ~~~
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ chmod 400 client-certs/client.root.key
+    $ chmod 400 client-certs/client.<username_1>.key
     ~~~
 
 4. Create the CSR for the first client using the [`openssl req`](https://www.openssl.org/docs/manmaster/man1/req.html) command:
@@ -318,12 +318,12 @@ In the following steps, replace the placeholder text in the code with the actual
     $ openssl req \
     -new \
     -config client.cnf \
-    -key client-certs/client.root.key \
-    -out client.root.csr \
+    -key client-certs/client.<username_1>.key \
+    -out client.<username_1>.csr \
     -batch
     ~~~
 
-5. Sign the client CSR to create the client certificate for the first client using the [`openssl ca`](https://www.openssl.org/docs/manmaster/man1/ca.html) command. You can set the client certificate expiration period using the `days` flag. We recommend using the CockroachDB default value of the client certificate expiration period, which is 1830 days.
+5. Sign the client CSR to create the client certificate for the first client using the [`openssl ca`](https://www.openssl.org/docs/manmaster/man1/ca.html) command.
 
     {% include copy-clipboard.html %}
     ~~~ shell
@@ -333,10 +333,9 @@ In the following steps, replace the placeholder text in the code with the actual
     -cert client-certs/ca.crt \
     -policy signing_policy \
     -extensions signing_client_req \
-    -out client-certs/client.root.crt \
+    -out client-certs/client.<username_1>.crt \
     -outdir client-certs/ \
-    -in client.root.csr \
-    -days 1830 \
+    -in client.<username_1>.csr \
     -batch
     ~~~    
 
@@ -344,19 +343,19 @@ In the following steps, replace the placeholder text in the code with the actual
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ openssl x509 -in client-certs/client.root.crt -text | grep CN=
+    $ openssl x509 -in client-certs/client.<username_1>.crt -text | grep CN=
     ~~~
 
     Output:
 
     ~~~
     Issuer: O=Cockroach, CN=Cockroach CA
-        Subject: O=Cockroach, CN=root
+        Subject: O=Cockroach, CN=<username_1>
     ~~~
 
 7. Remove the `.pem` files in the `client-certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
 
-### Step 4. Start a local cluster and connect using the SQL client
+### Step 4. Start a local cluster and connect using the built-in SQL client
 
 1. Start a single-node cluster:
 
@@ -372,11 +371,11 @@ In the following steps, replace the placeholder text in the code with the actual
     $ cockroach sql --certs-dir=client-certs
     ~~~
 
-3. Create a SQL user:
+3. Create a new SQL user:
 
     {% include copy-clipboard.html %}
     ~~~ sql
-    > create user <username>;
+    > create user <username_2>;
     ~~~
 
     {% include copy-clipboard.html %}
@@ -384,7 +383,7 @@ In the following steps, replace the placeholder text in the code with the actual
     > \q
     ~~~
 
-### Step 5. Create the certificate and key pair for a non-`root` client
+### Step 5. Create the certificate and key pair for a client
 
 In the following steps, replace the placeholder text in the code with the actual username.
 
@@ -398,7 +397,7 @@ In the following steps, replace the placeholder text in the code with the actual
 
     [ distinguished_name ]
     organizationName = Cockroach
-    commonName = <username>
+    commonName = <username_2>
     ~~~
 
     {{site.data.alerts.callout_danger}}The <code>commonName</code> parameter is vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the <code>commonName</code> parameter.  {{site.data.alerts.end}}
@@ -407,11 +406,11 @@ In the following steps, replace the placeholder text in the code with the actual
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ openssl genrsa -out client-certs/client.<username>.key 2048
+    $ openssl genrsa -out client-certs/client.<username_2>.key 2048
     ~~~
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ chmod 400 client-certs/client.<username>.key
+    $ chmod 400 client-certs/client.<username_2>.key
     ~~~
 
 3. Create the CSR for the first client using the [`openssl req`](https://www.openssl.org/docs/manmaster/man1/req.html) command:
@@ -421,12 +420,12 @@ In the following steps, replace the placeholder text in the code with the actual
     $ openssl req \
     -new \
     -config client.cnf \
-    -key client-certs/client.<username>.key \
-    -out client.<username>.csr \
+    -key client-certs/client.<username_2>.key \
+    -out client.<username_2>.csr \
     -batch
     ~~~
 
-4. Sign the client CSR to create the client certificate for the first client using the [`openssl ca`](https://www.openssl.org/docs/manmaster/man1/ca.html) command. You can set the client certificate expiration period using the `days` flag. We recommend using the CockroachDB default value of the client certificate expiration period, which is 1830 days.
+4. Sign the client CSR to create the client certificate for the first client using the [`openssl ca`](https://www.openssl.org/docs/manmaster/man1/ca.html) command.
 
     {% include copy-clipboard.html %}
     ~~~ shell
@@ -436,10 +435,9 @@ In the following steps, replace the placeholder text in the code with the actual
     -cert client-certs/ca.crt \
     -policy signing_policy \
     -extensions signing_client_req \
-    -out client-certs/client.<username>.crt \
+    -out client-certs/client.<username_2>.crt \
     -outdir client-certs/ \
-    -in client.<username>.csr \
-    -days 1830 \
+    -in client.<username_2>.csr \
     -batch
     ~~~    
 
@@ -447,7 +445,7 @@ In the following steps, replace the placeholder text in the code with the actual
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ openssl x509 -in client-certs/client.<username>.crt -text | grep CN=
+    $ openssl x509 -in client-certs/client.<username_2>.crt -text | grep CN=
     ~~~
 
     Example output:
@@ -463,7 +461,7 @@ In the following steps, replace the placeholder text in the code with the actual
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ cockroach sql --certs-dir=client-certs --user=<username>
+    $ cockroach sql --certs-dir=client-certs --user=<username_2>
     ~~~
 
 8. Repeat steps 1 - 7 for each additional client.

From f2c68eda23e842108d08d735aa9246a77ab79f84 Mon Sep 17 00:00:00 2001
From: Amruta <amruta@cockroachlabs.com>
Date: Mon, 13 Apr 2020 14:41:51 -0400
Subject: [PATCH 07/12] nits

---
 v20.1/create-security-certificates-openssl.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/v20.1/create-security-certificates-openssl.md b/v20.1/create-security-certificates-openssl.md
index 939832a754d..7439bfbaabf 100644
--- a/v20.1/create-security-certificates-openssl.md
+++ b/v20.1/create-security-certificates-openssl.md
@@ -298,7 +298,7 @@ In the following steps, replace the placeholder text in the code with the actual
     subjectAltName = DNS:root
     ~~~
 
-    {{site.data.alerts.callout_danger}}The <code>commonName</code> and <code>subjectAltName</code> parameters are vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the <code>commonName</code> or modify the <code>subjectAltName</code> parameters. {{site.data.alerts.end}}
+    {{site.data.alerts.callout_danger}}The <code>commonName</code> and <code>subjectAltName</code> parameters are vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the <code>commonName</code> parameter or modify the <code>subjectAltName</code> parameter. {{site.data.alerts.end}}
 
 3. Create the key for the first client using the [`openssl genrsa`](https://www.openssl.org/docs/manmaster/man1/genrsa.html) command:
 
@@ -361,7 +361,7 @@ In the following steps, replace the placeholder text in the code with the actual
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ cockroach start-single-node --certs-dir=node-certs --cert-principal-map=<node-domain>:node --background
+    $ cockroach start-single-node --certs-dir=node-certs --cert-principal-map=<node-domain>:node,<username_1>:root --background
     ~~~
 
 2. Connect to the cluster using the built-in SQL client:

From b9c709f1474fc3c38591b8b99a196031aeb74571 Mon Sep 17 00:00:00 2001
From: Amruta <amruta@cockroachlabs.com>
Date: Mon, 13 Apr 2020 16:23:32 -0400
Subject: [PATCH 08/12] missing field

---
 v20.1/create-security-certificates-openssl.md | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/v20.1/create-security-certificates-openssl.md b/v20.1/create-security-certificates-openssl.md
index 7439bfbaabf..6544054fdfb 100644
--- a/v20.1/create-security-certificates-openssl.md
+++ b/v20.1/create-security-certificates-openssl.md
@@ -239,7 +239,8 @@ In the following steps, replace the placeholder text in the code with the actual
     $ openssl x509 -in node-certs/node.crt -text | grep "X509v3 Subject Alternative Name" -A 1
     ~~~
 
-    Example output:
+    Sample output:
+
     ~~~
     X509v3 Subject Alternative Name: critical
                 DNS:localhost, DNS:node.example.io, IP Address:127.0.0.1
@@ -289,6 +290,7 @@ In the following steps, replace the placeholder text in the code with the actual
     [ req ]
     prompt=no
     distinguished_name = distinguished_name
+    req_extensions = extensions
 
     [ distinguished_name ]
     organizationName = Cockroach
@@ -346,11 +348,11 @@ In the following steps, replace the placeholder text in the code with the actual
     $ openssl x509 -in client-certs/client.<username_1>.crt -text | grep CN=
     ~~~
 
-    Output:
+    Sample Output:
 
     ~~~
     Issuer: O=Cockroach, CN=Cockroach CA
-        Subject: O=Cockroach, CN=<username_1>
+        Subject: O=Cockroach, CN=maxroach
     ~~~
 
 7. Remove the `.pem` files in the `client-certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
@@ -448,7 +450,7 @@ In the following steps, replace the placeholder text in the code with the actual
     $ openssl x509 -in client-certs/client.<username_2>.crt -text | grep CN=
     ~~~
 
-    Example output:
+    Sample output:
 
     ~~~
     Issuer: O=Cockroach, CN=Cockroach CA

From 5f4794c45ca2db9ac78b9f629ded71045c176287 Mon Sep 17 00:00:00 2001
From: Amruta <amruta@cockroachlabs.com>
Date: Tue, 14 Apr 2020 14:40:17 -0400
Subject: [PATCH 09/12] wip url change

---
 v20.1/create-security-certificates-openssl.md | 42 ++++---------------
 1 file changed, 7 insertions(+), 35 deletions(-)

diff --git a/v20.1/create-security-certificates-openssl.md b/v20.1/create-security-certificates-openssl.md
index 6544054fdfb..90818ad2686 100644
--- a/v20.1/create-security-certificates-openssl.md
+++ b/v20.1/create-security-certificates-openssl.md
@@ -246,33 +246,7 @@ In the following steps, replace the placeholder text in the code with the actual
                 DNS:localhost, DNS:node.example.io, IP Address:127.0.0.1
     ~~~
 
-6. Upload certificates to the first node:
-
-    {% include copy-clipboard.html %}
-    ~~~ shell
-    $ ssh <username>@<node1 address> "mkdir node-certs"
-    ~~~
-
-    {% include copy-clipboard.html %}
-    ~~~ shell
-    $ scp node-certs/ca.crt \
-    node-certs/node.crt \
-    node-certs/node.key \
-    <username>@<node1 address>:~/node-certs
-    ~~~
-
-7. Delete the local copy of the first node's certificate and key:
-
-    {% include copy-clipboard.html %}
-    ~~~ shell
-    $ rm node-certs/node.crt node-certs/node.key
-    ~~~
-
-    {{site.data.alerts.callout_info}}This is necessary because the certificates and keys for additional nodes will also be named <code>node.crt</code> and <code>node.key</code>.{{site.data.alerts.end}}
-
-8. Repeat steps 1 - 6 for each additional node.
-
-9. Remove the `.pem` files in the `node-certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
+6. Remove the `.pem` files in the `node-certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
 
 ### Step 3. Create the certificate and key pair for the first user
 
@@ -357,7 +331,7 @@ In the following steps, replace the placeholder text in the code with the actual
 
 7. Remove the `.pem` files in the `client-certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
 
-### Step 4. Start a local cluster and connect using the built-in SQL client
+### Step 4. Start a local cluster and connect using a connection URL
 
 1. Start a single-node cluster:
 
@@ -366,11 +340,11 @@ In the following steps, replace the placeholder text in the code with the actual
     $ cockroach start-single-node --certs-dir=node-certs --cert-principal-map=<node-domain>:node,<username_1>:root --background
     ~~~
 
-2. Connect to the cluster using the built-in SQL client:
+2. Connect to the cluster using a connection URL:
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ cockroach sql --certs-dir=client-certs
+    $ cockroach sql --url='postgres://<hostname>:26257/?sslmode=verify-full&sslrootcert=client-certs/ca.crt&sslcert=client-certs/client.<username_1>.crt&sslkey=client-certs/client.<username_1>.key&sslmode=verify-full'
     ~~~
 
 3. Create a new SQL user:
@@ -457,18 +431,16 @@ In the following steps, replace the placeholder text in the code with the actual
         Subject: O=Cockroach, CN=roach
     ~~~
 
-6. Upload certificates to the client using your preferred method.
-
-7. Connect to the SQL client using the client certificate:
+6. Connect to the SQL client using the client certificate:
 
     {% include copy-clipboard.html %}
     ~~~ shell
     $ cockroach sql --certs-dir=client-certs --user=<username_2>
     ~~~
 
-8. Repeat steps 1 - 7 for each additional client.
+7. Remove the `.pem` files in the `client-certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
 
-9. Remove the `.pem` files in the `client-certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
+For each node in your deployment, repeat [Step 2](#step-2-create-the-certificate-and-key-pairs-for-nodes) and upload the CA certificate and node key and certificate to the node. For each client, repeat [Step 5](#step-5-create-the-certificate-and-key-pair-for-a-client) and upload the CA certificate and client key and certificate to the client.
 
 ## See also
 

From 4f1c3f157b912a08db4c50e1d115e5a71c8423ff Mon Sep 17 00:00:00 2001
From: Amruta <amruta@cockroachlabs.com>
Date: Tue, 14 Apr 2020 14:53:12 -0400
Subject: [PATCH 10/12] single directory updates

---
 v20.1/create-security-certificates-openssl.md | 80 +++++++++----------
 1 file changed, 36 insertions(+), 44 deletions(-)

diff --git a/v20.1/create-security-certificates-openssl.md b/v20.1/create-security-certificates-openssl.md
index 90818ad2686..ad2fba16102 100644
--- a/v20.1/create-security-certificates-openssl.md
+++ b/v20.1/create-security-certificates-openssl.md
@@ -70,14 +70,13 @@ Note the following:
 
 ### Step 1. Create the CA key and certificate pair
 
-1. Create three directories:
+1. Create two directories:
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ mkdir node-certs client-certs my-safe-directory
+    $ mkdir certs my-safe-directory
     ~~~
-    - `node-certs`: Create your CA certificate and all node certificates and keys in this directory and then upload the relevant files to the nodes.
-    - `client-certs`: Copy your CA certificate to this folder and create all client certificates and keys in this directory and then upload the relevant files to the clients.
+    - `certs`: Create your CA certificate and all node and client certificates and keys in this directory and then upload the relevant files to the nodes and clients.
     - `my-safe-directory`: Create your CA key in this directory and then reference the key when generating node and client certificates. After that, keep the key safe and secret; do not upload it to your nodes or clients.
 
 2. Create the `ca.cnf` file and copy the following configuration into it.
@@ -150,7 +149,7 @@ Note the following:
     -x509 \
     -config ca.cnf \
     -key my-safe-directory/ca.key \
-    -out node-certs/ca.crt \
+    -out certs/ca.crt \
     -days 365 \
     -batch
     ~~~
@@ -197,11 +196,11 @@ In the following steps, replace the placeholder text in the code with the actual
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ openssl genrsa -out node-certs/node.key 2048
+    $ openssl genrsa -out certs/node.key 2048
     ~~~
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ chmod 400 node-certs/node.key
+    $ chmod 400 certs/node.key
     ~~~
 
 3. Create the CSR for the first node using the [`openssl req`](https://www.openssl.org/docs/manmaster/man1/req.html) command:
@@ -211,7 +210,7 @@ In the following steps, replace the placeholder text in the code with the actual
     $ openssl req \
     -new \
     -config node.cnf \
-    -key node-certs/node.key \
+    -key certs/node.key \
     -out node.csr \
     -batch
     ~~~
@@ -223,11 +222,11 @@ In the following steps, replace the placeholder text in the code with the actual
     $ openssl ca \
     -config ca.cnf \
     -keyfile my-safe-directory/ca.key \
-    -cert node-certs/ca.crt \
+    -cert certs/ca.crt \
     -policy signing_policy \
     -extensions signing_node_req \
-    -out node-certs/node.crt \
-    -outdir node-certs/ \
+    -out certs/node.crt \
+    -outdir certs/ \
     -in node.csr \
     -batch
     ~~~
@@ -236,7 +235,7 @@ In the following steps, replace the placeholder text in the code with the actual
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ openssl x509 -in node-certs/node.crt -text | grep "X509v3 Subject Alternative Name" -A 1
+    $ openssl x509 -in certs/node.crt -text | grep "X509v3 Subject Alternative Name" -A 1
     ~~~
 
     Sample output:
@@ -246,18 +245,11 @@ In the following steps, replace the placeholder text in the code with the actual
                 DNS:localhost, DNS:node.example.io, IP Address:127.0.0.1
     ~~~
 
-6. Remove the `.pem` files in the `node-certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
+6. Remove the `.pem` files in the `certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
 
 ### Step 3. Create the certificate and key pair for the first user
 
-1. Copy the `ca.crt` from the `node-certs` directory to the `client-certs` directory
-
-    {% include copy-clipboard.html %}
-    ~~~ shell
-    $ cp node-certs/ca.crt client-certs
-    ~~~
-
-2. Create the `client.cnf` file for the first user and copy the following configuration into it:
+1. Create the `client.cnf` file for the first user and copy the following configuration into it:
 
     {% include copy-clipboard.html %}
     ~~~
@@ -276,50 +268,50 @@ In the following steps, replace the placeholder text in the code with the actual
 
     {{site.data.alerts.callout_danger}}The <code>commonName</code> and <code>subjectAltName</code> parameters are vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the <code>commonName</code> parameter or modify the <code>subjectAltName</code> parameter. {{site.data.alerts.end}}
 
-3. Create the key for the first client using the [`openssl genrsa`](https://www.openssl.org/docs/manmaster/man1/genrsa.html) command:
+2. Create the key for the first client using the [`openssl genrsa`](https://www.openssl.org/docs/manmaster/man1/genrsa.html) command:
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ openssl genrsa -out client-certs/client.<username_1>.key 2048
+    $ openssl genrsa -out certs/client.<username_1>.key 2048
     ~~~
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ chmod 400 client-certs/client.<username_1>.key
+    $ chmod 400 certs/client.<username_1>.key
     ~~~
 
-4. Create the CSR for the first client using the [`openssl req`](https://www.openssl.org/docs/manmaster/man1/req.html) command:
+3. Create the CSR for the first client using the [`openssl req`](https://www.openssl.org/docs/manmaster/man1/req.html) command:
 
     {% include copy-clipboard.html %}
     ~~~ shell
     $ openssl req \
     -new \
     -config client.cnf \
-    -key client-certs/client.<username_1>.key \
+    -key certs/client.<username_1>.key \
     -out client.<username_1>.csr \
     -batch
     ~~~
 
-5. Sign the client CSR to create the client certificate for the first client using the [`openssl ca`](https://www.openssl.org/docs/manmaster/man1/ca.html) command.
+4. Sign the client CSR to create the client certificate for the first client using the [`openssl ca`](https://www.openssl.org/docs/manmaster/man1/ca.html) command.
 
     {% include copy-clipboard.html %}
     ~~~ shell
     $ openssl ca \
     -config ca.cnf \
     -keyfile my-safe-directory/ca.key \
-    -cert client-certs/ca.crt \
+    -cert certs/ca.crt \
     -policy signing_policy \
     -extensions signing_client_req \
-    -out client-certs/client.<username_1>.crt \
-    -outdir client-certs/ \
+    -out certs/client.<username_1>.crt \
+    -outdir certs/ \
     -in client.<username_1>.csr \
     -batch
     ~~~    
 
-6. Verify the values in the `CN` field in the certificate:
+5. Verify the values in the `CN` field in the certificate:
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ openssl x509 -in client-certs/client.<username_1>.crt -text | grep CN=
+    $ openssl x509 -in certs/client.<username_1>.crt -text | grep CN=
     ~~~
 
     Sample Output:
@@ -329,7 +321,7 @@ In the following steps, replace the placeholder text in the code with the actual
         Subject: O=Cockroach, CN=maxroach
     ~~~
 
-7. Remove the `.pem` files in the `client-certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
+6. Remove the `.pem` files in the `certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
 
 ### Step 4. Start a local cluster and connect using a connection URL
 
@@ -337,14 +329,14 @@ In the following steps, replace the placeholder text in the code with the actual
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ cockroach start-single-node --certs-dir=node-certs --cert-principal-map=<node-domain>:node,<username_1>:root --background
+    $ cockroach start-single-node --certs-dir=certs --cert-principal-map=<node-domain>:node,<username_1>:root --background
     ~~~
 
 2. Connect to the cluster using a connection URL:
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ cockroach sql --url='postgres://<hostname>:26257/?sslmode=verify-full&sslrootcert=client-certs/ca.crt&sslcert=client-certs/client.<username_1>.crt&sslkey=client-certs/client.<username_1>.key&sslmode=verify-full'
+    $ cockroach sql --url='postgres://<hostname>:26257/?sslmode=verify-full&sslrootcert=certs/ca.crt&sslcert=certs/client.<username_1>.crt&sslkey=certs/client.<username_1>.key&sslmode=verify-full'
     ~~~
 
 3. Create a new SQL user:
@@ -382,11 +374,11 @@ In the following steps, replace the placeholder text in the code with the actual
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ openssl genrsa -out client-certs/client.<username_2>.key 2048
+    $ openssl genrsa -out certs/client.<username_2>.key 2048
     ~~~
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ chmod 400 client-certs/client.<username_2>.key
+    $ chmod 400 certs/client.<username_2>.key
     ~~~
 
 3. Create the CSR for the first client using the [`openssl req`](https://www.openssl.org/docs/manmaster/man1/req.html) command:
@@ -396,7 +388,7 @@ In the following steps, replace the placeholder text in the code with the actual
     $ openssl req \
     -new \
     -config client.cnf \
-    -key client-certs/client.<username_2>.key \
+    -key certs/client.<username_2>.key \
     -out client.<username_2>.csr \
     -batch
     ~~~
@@ -408,11 +400,11 @@ In the following steps, replace the placeholder text in the code with the actual
     $ openssl ca \
     -config ca.cnf \
     -keyfile my-safe-directory/ca.key \
-    -cert client-certs/ca.crt \
+    -cert certs/ca.crt \
     -policy signing_policy \
     -extensions signing_client_req \
-    -out client-certs/client.<username_2>.crt \
-    -outdir client-certs/ \
+    -out certs/client.<username_2>.crt \
+    -outdir certs/ \
     -in client.<username_2>.csr \
     -batch
     ~~~    
@@ -421,7 +413,7 @@ In the following steps, replace the placeholder text in the code with the actual
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ openssl x509 -in client-certs/client.<username_2>.crt -text | grep CN=
+    $ openssl x509 -in certs/client.<username_2>.crt -text | grep CN=
     ~~~
 
     Sample output:
@@ -435,10 +427,10 @@ In the following steps, replace the placeholder text in the code with the actual
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ cockroach sql --certs-dir=client-certs --user=<username_2>
+    $ cockroach sql --url='postgres://<username_2>@<hostname>:26257/?sslmode=verify-full&sslrootcert=certs/ca.crt&sslcert=certs/client.<username_2>.crt&sslkey=certs/client.<username_2>.key&sslmode=verify-full'
     ~~~
 
-7. Remove the `.pem` files in the `client-certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
+7. Remove the `.pem` files in the `certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
 
 For each node in your deployment, repeat [Step 2](#step-2-create-the-certificate-and-key-pairs-for-nodes) and upload the CA certificate and node key and certificate to the node. For each client, repeat [Step 5](#step-5-create-the-certificate-and-key-pair-for-a-client) and upload the CA certificate and client key and certificate to the client.
 

From 41cea8f6f8415cf01cbdf20e0b92a0f895e2d6b7 Mon Sep 17 00:00:00 2001
From: Amruta <amruta@cockroachlabs.com>
Date: Wed, 15 Apr 2020 11:49:53 -0400
Subject: [PATCH 11/12] Worked on Jesse's comments

---
 v20.1/create-security-certificates-openssl.md | 27 +++++++++++--------
 1 file changed, 16 insertions(+), 11 deletions(-)

diff --git a/v20.1/create-security-certificates-openssl.md b/v20.1/create-security-certificates-openssl.md
index ad2fba16102..fb4c64e78e2 100644
--- a/v20.1/create-security-certificates-openssl.md
+++ b/v20.1/create-security-certificates-openssl.md
@@ -127,7 +127,9 @@ Note the following:
     extendedKeyUsage = clientAuth
     ~~~
 
-    {{site.data.alerts.callout_danger}}The <code>keyUsage</code> and <code>extendedkeyUsage</code> parameters are vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration and you can add additional usages, but do not omit <code>keyUsage</code> and <code>extendedkeyUsage</code> parameters or remove the listed usages. {{site.data.alerts.end}}
+    {{site.data.alerts.callout_danger}}
+    The `keyUsage` and `extendedkeyUsage` parameters are vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration and you can add additional usages, but do not omit `keyUsage` and `extendedkeyUsage` parameters or remove the listed usages.
+    {{site.data.alerts.end}}
 
 3. Create the CA key using the [`openssl genrsa`](https://www.openssl.org/docs/manmaster/man1/genrsa.html) command:
 
@@ -154,7 +156,7 @@ Note the following:
     -batch
     ~~~
 
-6. Reset database and index files.
+6. Reset database and index files:
 
     {% include copy-clipboard.html %}
     ~~~ shell
@@ -190,7 +192,9 @@ In the following steps, replace the placeholder text in the code with the actual
     subjectAltName = critical,DNS:<node-hostname>,DNS:<node-domain>,IP:<IP Address>
     ~~~
 
-    {{site.data.alerts.callout_danger}}The <code>subjectAltName</code> parameter is vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the <code>subjectAltName</code> parameter.  {{site.data.alerts.end}}
+    {{site.data.alerts.callout_danger}}
+    The `subjectAltName` parameter is vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the `subjectAltName` parameter.
+    {{site.data.alerts.end}}
 
 2. Create the key for the first node using the [`openssl genrsa`](https://www.openssl.org/docs/manmaster/man1/genrsa.html) command:
 
@@ -245,10 +249,10 @@ In the following steps, replace the placeholder text in the code with the actual
                 DNS:localhost, DNS:node.example.io, IP Address:127.0.0.1
     ~~~
 
-6. Remove the `.pem` files in the `certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
-
 ### Step 3. Create the certificate and key pair for the first user
 
+In the following steps, replace the placeholder text in the code with the actual username.
+
 1. Create the `client.cnf` file for the first user and copy the following configuration into it:
 
     {% include copy-clipboard.html %}
@@ -266,7 +270,9 @@ In the following steps, replace the placeholder text in the code with the actual
     subjectAltName = DNS:root
     ~~~
 
-    {{site.data.alerts.callout_danger}}The <code>commonName</code> and <code>subjectAltName</code> parameters are vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the <code>commonName</code> parameter or modify the <code>subjectAltName</code> parameter. {{site.data.alerts.end}}
+    {{site.data.alerts.callout_danger}}
+    The `commonName` and `subjectAltName` parameters are vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the `commonName` parameter or modify the `subjectAltName` parameter.
+    {{site.data.alerts.end}}
 
 2. Create the key for the first client using the [`openssl genrsa`](https://www.openssl.org/docs/manmaster/man1/genrsa.html) command:
 
@@ -321,8 +327,6 @@ In the following steps, replace the placeholder text in the code with the actual
         Subject: O=Cockroach, CN=maxroach
     ~~~
 
-6. Remove the `.pem` files in the `certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
-
 ### Step 4. Start a local cluster and connect using a connection URL
 
 1. Start a single-node cluster:
@@ -368,7 +372,8 @@ In the following steps, replace the placeholder text in the code with the actual
     commonName = <username_2>
     ~~~
 
-    {{site.data.alerts.callout_danger}}The <code>commonName</code> parameter is vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the <code>commonName</code> parameter.  {{site.data.alerts.end}}
+    {{site.data.alerts.callout_danger}}
+    The `commonName` parameter is vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the `commonName` parameter.  {{site.data.alerts.end}}
 
 2. Create the key for the first client using the [`openssl genrsa`](https://www.openssl.org/docs/manmaster/man1/genrsa.html) command:
 
@@ -430,10 +435,10 @@ In the following steps, replace the placeholder text in the code with the actual
     $ cockroach sql --url='postgres://<username_2>@<hostname>:26257/?sslmode=verify-full&sslrootcert=certs/ca.crt&sslcert=certs/client.<username_2>.crt&sslkey=certs/client.<username_2>.key&sslmode=verify-full'
     ~~~
 
-7. Remove the `.pem` files in the `certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
-
 For each node in your deployment, repeat [Step 2](#step-2-create-the-certificate-and-key-pairs-for-nodes) and upload the CA certificate and node key and certificate to the node. For each client, repeat [Step 5](#step-5-create-the-certificate-and-key-pair-for-a-client) and upload the CA certificate and client key and certificate to the client.
 
+After you have uploaded all the keys and certificates to the corresponding nodes and clients, remove the `.pem` files in the `certs` directory. These files are unnecessary duplicates of the `.crt` files that CockroachDB requires.
+
 ## See also
 
 - [Manual Deployment](manual-deployment.html): Learn about starting a multi-node secure cluster and accessing it from a client.

From 14eddb9edf07a4433e870f880a1e5e0a366297cb Mon Sep 17 00:00:00 2001
From: Amruta <amruta@cockroachlabs.com>
Date: Wed, 15 Apr 2020 15:00:26 -0400
Subject: [PATCH 12/12] Worked on Jesse's comments

---
 v20.1/cockroach-start-single-node.md | 1 +
 v20.1/cockroach-start.md             | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/v20.1/cockroach-start-single-node.md b/v20.1/cockroach-start-single-node.md
index 8dc857c89e6..f17360ac25c 100644
--- a/v20.1/cockroach-start-single-node.md
+++ b/v20.1/cockroach-start-single-node.md
@@ -63,6 +63,7 @@ Flag | Description
 -----|-----------
 `--certs-dir` | The path to the [certificate directory](cockroach-cert.html). The directory must contain valid certificates if running in secure mode.<br><br>**Default:** `${HOME}/.cockroach-certs/`
 `--insecure` | Run in insecure mode. If this flag is not set, the `--certs-dir` flag must point to valid certificates.<br><br><strong>Note the following risks:</strong> An insecure cluster is open to any client that can access any node's IP addresses; any user, even `root`, can log in without providing a password; any user, connecting as `root`, can read or write any data in your cluster; and there is no network encryption or authentication, and thus no confidentiality.<br><br>**Default:** `false`
+`--cert-principal-map` | <span class="version-tag">New in v20.1:</span> A comma-separated list of `cert-principal:db-principal` mappings used to map the certificate principals to IP addresses, DNS names, and SQL users. This allows the use of certificates generated by Certificate Authorities that place restrictions on the contents of the `commonName` field. For usage information, see [Create Security Certificates using Openssl](create-security-certificates-openssl.html#examples).
 `--enterprise-encryption` | This optional flag specifies the encryption options for one of the stores on the node. If multiple stores exist, the flag must be specified for each store. <br /><br /> This flag takes a number of options.  For a complete list of options, and usage instructions, see [Encryption at Rest](encryption.html). <br /><br /> Note that this is an [enterprise feature](enterprise-licensing.html).   
 
 ### Store
diff --git a/v20.1/cockroach-start.md b/v20.1/cockroach-start.md
index 30fceba413f..7446824898c 100644
--- a/v20.1/cockroach-start.md
+++ b/v20.1/cockroach-start.md
@@ -86,7 +86,7 @@ Flag | Description
 -----|-----------
 `--certs-dir` | The path to the [certificate directory](cockroach-cert.html). The directory must contain valid certificates if running in secure mode.<br><br>**Default:** `${HOME}/.cockroach-certs/`
 `--insecure` | Run in insecure mode. If this flag is not set, the `--certs-dir` flag must point to valid certificates.<br><br><strong>Note the following risks:</strong> An insecure cluster is open to any client that can access any node's IP addresses; any user, even `root`, can log in without providing a password; any user, connecting as `root`, can read or write any data in your cluster; and there is no network encryption or authentication, and thus no confidentiality.<br><br>**Default:** `false`
-`--cert-principal-map` | A comma-separated list of `cert-principal:db-principal` mappings used to map the certificate principals to IP addresses, DNS names, and SQL users. This allows the use of certificates generated by Certificate Authorities that place restrictions on the contents of the `commonName` field. For usage information, see [Create Security Certificates using Openssl](create-security-certificates-openssl.html#examples)
+`--cert-principal-map` | <span class="version-tag">New in v20.1:</span> A comma-separated list of `cert-principal:db-principal` mappings used to map the certificate principals to IP addresses, DNS names, and SQL users. This allows the use of certificates generated by Certificate Authorities that place restrictions on the contents of the `commonName` field. For usage information, see [Create Security Certificates using Openssl](create-security-certificates-openssl.html#examples).
 `--enterprise-encryption` | This optional flag specifies the encryption options for one of the stores on the node. If multiple stores exist, the flag must be specified for each store. <br /><br /> This flag takes a number of options.  For a complete list of options, and usage instructions, see [Encryption at Rest](encryption.html). <br /><br /> Note that this is an [enterprise feature](enterprise-licensing.html).
 
 ### Locality