Skip to content

Update generate-self-signed-certificates.md (#2703) #2750

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 9, 2020
Merged

Update generate-self-signed-certificates.md (#2703) #2750

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
288 changes: 155 additions & 133 deletions generate-self-signed-certificates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,156 +1,178 @@
---
title: Generate Self-signed Certificates
summary: Use `cfssl` to generate self-signed certificates.
summary: Use `openssl` to generate self-signed certificates.
category: how-to
aliases: ['/docs/stable/how-to/secure/generate-self-signed-certificates/']
---

# Generate Self-signed Certificates

## Overview

This document describes how to generate self-signed certificates using `cfssl`.
This document provides an example of using `openssl` to generate a self-signed certificate. You can also generate certificates and keys that meet requirements according to your demands.

Assume that the topology of the instance cluster is as follows:

| Name | Host IP | Services |
| ----- | ----------- | ---------- |
| node1 | 172.16.10.1 | PD1, TiDB1 |
| node2 | 172.16.10.2 | PD2, TiDB2 |
| node3 | 172.16.10.3 | PD3 |
| node4 | 172.16.10.4 | TiKV1 |
| node5 | 172.16.10.5 | TiKV2 |
| node6 | 172.16.10.6 | TiKV3 |
| Name | Host IP | Services |
| ----- | ----------- | ---------- |
| node1 | 172.16.10.11 | PD1, TiDB1 |
| node2 | 172.16.10.12 | PD2 |
| node3 | 172.16.10.13 | PD3 |
| node4 | 172.16.10.14 | TiKV1 |
| node5 | 172.16.10.15 | TiKV2 |
| node6 | 172.16.10.16 | TiKV3 |

## Install OpenSSL

- For Debian or Ubuntu OS:

{{< copyable "shell-regular" >}}

```bash
apt install openssl
```

- For RedHat or CentOS OS:

{{< copyable "shell-regular" >}}

```bash
yum install openssl
```

You can also refer to OpenSSL's official [download document](https://www.openssl.org/source/) for installation.

## Generate the CA certificate

A certificate authority (CA) is a trusted entity that issues digital certificates. In practice, contact your administrator to issue the certificate or use a trusted CA. CA manages multiple certificate pairs. Here you only need to generate an original pair of certificates as follows.

1. Generate the root key:

{{< copyable "shell-regular" >}}

## Download `cfssl`
```bash
openssl genrsa -out root.key 4096
```

Assume that the host is x86_64 Linux:
2. Generate root certificates:

```bash
mkdir ~/bin
curl -s -L -o ~/bin/cfssl https://pkg.cfssl.org/R1.2/cfssl_linux-amd64
curl -s -L -o ~/bin/cfssljson https://pkg.cfssl.org/R1.2/cfssljson_linux-amd64
chmod +x ~/bin/{cfssl,cfssljson}
export PATH=$PATH:~/bin
```
{{< copyable "shell-regular" >}}

## Initialize the certificate authority
```bash
openssl req -new -x509 -days 1000 -key root.key -out root.crt
```

To make it easy for modification later, generate the default configuration of `cfssl`:
3. Validate root certificates:

```bash
mkdir ~/cfssl
cd ~/cfssl
cfssl print-defaults config > ca-config.json
cfssl print-defaults csr > ca-csr.json
```
{{< copyable "shell-regular" >}}

## Generate certificates
```bash
openssl x509 -text -in root.crt -noout
```

### Certificates description
## Issue certificates for individual components

This section describes how to issue certificates for individual components.

### Certificates that might be used in the cluster

- tidb-server certificate: used by TiDB to authenticate TiDB for other components and clients
- tikv-server certificate: used by TiKV to authenticate TiKV for other components and clients
- pd-server certificate: used by PD to authenticate PD for other components and clients
- client certificate: used to authenticate the clients from PD, TiKV and TiDB, such as `pd-ctl`, `tikv-ctl` and `pd-recover`

### Configure the CA option

Edit `ca-config.json` according to your need:

```json
{
"signing": {
"default": {
"expiry": "43800h"
},
"profiles": {
"server": {
"expiry": "43800h",
"usages": [
"signing",
"key encipherment",
"server auth",
"client auth"
]
},
"client": {
"expiry": "43800h",
"usages": [
"signing",
"key encipherment",
"client auth"
]
}
}
}
}
```

Edit `ca-csr.json` according to your need:

```json
{
"CN": "My own CA",
"key": {
"algo": "rsa",
"size": 2048
},
"names": [
{
"C": "CN",
"L": "Beijing",
"O": "PingCAP",
"ST": "Beijing"
}
]
}
```

### Generate the CA certificate

```bash
cfssl gencert -initca ca-csr.json | cfssljson -bare ca -
```

The command above generates the following files:

```bash
ca-key.pem
ca.csr
ca.pem
```

### Generate the server certificate

The IP address of all components and `127.0.0.1` are included in `hostname`.

```bash
echo '{"CN":"tidb-server","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=server -hostname="172.16.10.1,172.16.10.2,127.0.0.1" - | cfssljson -bare tidb-server

echo '{"CN":"tikv-server","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=server -hostname="172.16.10.4,172.16.10.5,172.16.10.6,127.0.0.1" - | cfssljson -bare tikv-server

echo '{"CN":"pd-server","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=server -hostname="172.16.10.1,172.16.10.2,172.16.10.3,127.0.0.1" - | cfssljson -bare pd-server
```

The command above generates the following files:

```Bash
tidb-server-key.pem tikv-server-key.pem pd-server-key.pem
tidb-server.csr tikv-server.csr pd-server.csr
tidb-server.pem tikv-server.pem pd-server.pem
```

### Generate the client certificate

```bash
echo '{"CN":"client","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=client -hostname="" - | cfssljson -bare client
```

The command above generates the following files:

```bash
client-key.pem
client.csr
client.pem
```
- client certificate: used to authenticate the clients from PD, TiKV and TiDB, such as `pd-ctl`, `tikv-ctl`

### Issue certificates to TiKV instances

To issue a certificate to a TiKV instance, perform the following steps:

1. Generate the private key corresponding to the certificate:

{{< copyable "shell-regular" >}}

```bash
openssl genrsa -out tikv.key 2048
```

2. Make a copy of the OpenSSL configuration template file (Refer to the actual location of your template file because it might have more than one location):

{{< copyable "shell-regular" >}}

```bash
cp /usr/lib/ssl/openssl.cnf .
```

If you do not know the actual location, look for it in the root directory:

```bash
find / -name openssl.cnf
```

3. Edit `openssl.cnf`, add `req_extensions = v3_req` under the `[ req ]` field, and add `subjectAltName = @alt_names` under the `[ v3_req ]` field. Finally, create a new field and edit the information of SAN.

```
[ alt_names ]
IP.1 = 127.0.0.1
IP.2 = 172.16.10.14
IP.3 = 172.16.10.15
IP.4 = 172.16.10.16
```

4. Save the `openssl.cnf` file, and generate the certificate request file (in this step, you can also assign a Common Name to the certificate, which is used to allow the server to validate the identity of the client. Each component does not enable the validation by default, and you can enable it in the configuration file):

{{< copyable "shell-regular" >}}

```bash
openssl req -new -key tikv.key -out tikv.csr -config openssl.cnf
```

5. Issue and generate the certificate:

{{< copyable "shell-regular" >}}

```bash
openssl x509 -req -days 365 -CA root.crt -CAkey root.key -CAcreateserial -in tikv.csr -out tikv.crt -extensions v3_req -extfile openssl.cnf
```

6. Verify that the certificate includes the SAN field (optional):

{{< copyable "shell-regular" >}}

```bash
openssl x509 -text -in tikv.crt -noout
```

7. Confirm that the following files exist in your current directory:

```
root.crt
tikv.crt
tikv.key
```

The process of issuing certificates for other TiDB components is similar and will not be repeated in this document.

### Issue certificates for clients

To issue a certificate to a client, perform the following steps:

1. Generate the private key corresponding to the certificate:

{{< copyable "shell-regular" >}}

```bash
openssl genrsa -out client.key 2048
```

2. Generate the certificate request file (in this step, you can also assign a Common Name to the certificate, which is used to allow the server to validate the identity of the client. Each component does not enable the validation by default, and you can enable it in the configuration file):

{{< copyable "shell-regular" >}}

```bash
openssl req -new -key client.key -out client.csr
```

3. Issue and generate the certificate:

{{< copyable "shell-regular" >}}

```bash
openssl x509 -req -days 365 -CA root.crt -CAkey root.key -CAcreateserial -in client.csr -out client.crt
```