add --cert-principal-map

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

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.
@@ -119,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 ]
@@ -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,22 @@ 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
 
     [ 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. 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>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:
 
     {% 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 +211,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 +225,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 +239,133 @@ 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.
+
+### 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
+
+    {% include copy-clipboard.html %}
+    ~~~ shell
+    $ cp node-certs/ca.crt client-certs
+    ~~~
+
+2. Create the `client.cnf` file for the `root` user and copy the following configuration into it:
+
+    {% include copy-clipboard.html %}
+    ~~~
+    [ req ]
+    prompt=no
+    distinguished_name = distinguished_name
+
+    [ distinguished_name ]
+    organizationName = Cockroach
+    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}}
+
+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.root.key 2048
+    ~~~
+    {% include copy-clipboard.html %}
+    ~~~ shell
+    $ 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:
+
+    {% include copy-clipboard.html %}
+    ~~~ shell
+    $ openssl req \
+    -new \
+    -config client.cnf \
+    -key client-certs/client.root.key \
+    -out client.root.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.root.crt \
+    -outdir client-certs/ \
+    -in client.root.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.
+
+### 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-domain>:node --background
+    ~~~
+
+2. Connect to the cluster using the built-in SQL client:
+
+    {% include copy-clipboard.html %}
+    ~~~ shell
+    $ 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
+    ~~~
 
-### Create the certificate and key pair for a 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.
 
-1. Create the `client.cnf` file for the first client and copy the following configuration into it:
+1. Create the `client.cnf` file for the client and copy the following configuration into it:
 
     {% include copy-clipboard.html %}
     ~~~
@@ -286,17 +378,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 +398,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 +410,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 +424,7 @@ 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.
 
 ## See also