Skip to content

Commit 0ef9aa3

Browse files
KennedyDMSFTKennedyDMSFT
committed
Draft, in progress
1 parent ff0e833 commit 0ef9aa3

File tree

1 file changed

+255
-0
lines changed

1 file changed

+255
-0
lines changed

‎articles/iot-hub/tutorial-x509-test-ca-certs.md

Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,258 @@ ms.custom: [mvc, 'Role: Cloud Development', 'Role: Data Analytics']
1414

1515
# Tutorial: Create a root CA and certificates for testing
1616

17+
## Prerequisites
18+
19+
* A local instance of Azure CLI. This article requires Azure CLI version 2.36 or later. Run `az --version` to find the version. To locally install or upgrade Azure CLI, see [Install Azure CLI](/cli/azure/install-azure-cli).
20+
21+
## Create a root CA
22+
23+
Intro
24+
25+
Proc
26+
27+
1. Start an Azure CLI session and run the following command, replacing *{basedir}* with the desired folder in which to create the root CA.
28+
29+
```bash
30+
cd {basedir}
31+
```
32+
33+
1. In the CLI session, run the following commands, one at a time. This step creates the following folder structure and support files for the root CA.
34+
35+
| Folder or file | Description |
36+
| --- | --- |
37+
| rootca | The root folder of the root CA. |
38+
| rootca/certs | The folder in which CA certificates for the root CA are created and stored. |
39+
| rootca/db | The folder in which the database for the root CA is stored. |
40+
| rootca/db/index | The index file for the root CA. The `touch` command creates a file without any content, for later use. |
41+
| rootca/db/serial | The serial number file for the root CA. The `openssl` command creates a 16-byte random number in hexadecimal format, then stores it in this file. |
42+
| rootca/db/crlnumber | A file used to store serial numbers for revoked CA certificates issued by the root CA. The `echo` command pipes a sample serial number, 1001, into the file. |
43+
| rootca/private | The folder in which private files for the root CA, including the private key, are stored. |
44+
45+
```bash
46+
mkdir rootca
47+
cd rootca
48+
mkdir certs db private
49+
touch db/index
50+
openssl rand -hex 16 > db/serial
51+
echo 1001 > db/crlnumber
52+
```
53+
54+
1. Create a text file named *rootca.conf* in the *rootca* folder created in the previous step, then copy and save the following OpenSSL configuration settings into that file. The file provides OpenSSL with the values needed to configure your test root CA. For this example, the file configures a root CA named *rootca* for the *example.com* domain, using the folders and files created in previous steps. The file also provides configuration settings for:
55+
- The CA policy used by the root CA for certificate Distinguished Name (DN) fields
56+
- Certificate requests created by the root CA
57+
- X.509 extensions applied to root CA certificates, intermediate CA certificates, and client certificates issued by the root CA
58+
59+
For more information about the syntax of OpenSSL configuration files, see the [config](https://www.openssl.org/docs/manmaster/man5/config.html) master manual page in [OpenSSL documentation](https://www.openssl.org/docs/).
60+
61+
```xml
62+
[default]
63+
name = rootca
64+
domain_suffix = example.com
65+
aia_url = http://$name.$domain_suffix/$name.crt
66+
crl_url = http://$name.$domain_suffix/$name.crl
67+
default_ca = ca_default
68+
name_opt = utf8,esc_ctrl,multiline,lname,align
69+
70+
[ca_dn]
71+
commonName = "Test Root CA"
72+
73+
[ca_default]
74+
home = ../rootca
75+
database = $home/db/index
76+
serial = $home/db/serial
77+
crlnumber = $home/db/crlnumber
78+
certificate = $home/$name.crt
79+
private_key = $home/private/$name.key
80+
RANDFILE = $home/private/random
81+
new_certs_dir = $home/certs
82+
unique_subject = no
83+
copy_extensions = none
84+
default_days = 3650
85+
default_crl_days = 365
86+
default_md = sha256
87+
policy = policy_c_o_match
88+
89+
[policy_c_o_match]
90+
countryName = optional
91+
stateOrProvinceName = optional
92+
organizationName = optional
93+
organizationalUnitName = optional
94+
commonName = supplied
95+
emailAddress = optional
96+
97+
[req]
98+
default_bits = 2048
99+
encrypt_key = yes
100+
default_md = sha256
101+
utf8 = yes
102+
string_mask = utf8only
103+
prompt = no
104+
distinguished_name = ca_dn
105+
req_extensions = ca_ext
106+
107+
[ca_ext]
108+
basicConstraints = critical,CA:true
109+
keyUsage = critical,keyCertSign,cRLSign
110+
subjectKeyIdentifier = hash
111+
112+
[sub_ca_ext]
113+
authorityKeyIdentifier = keyid:always
114+
basicConstraints = critical,CA:true,pathlen:0
115+
extendedKeyUsage = clientAuth,serverAuth
116+
keyUsage = critical,keyCertSign,cRLSign
117+
subjectKeyIdentifier = hash
118+
119+
[client_ext]
120+
authorityKeyIdentifier = keyid:always
121+
basicConstraints = critical,CA:false
122+
extendedKeyUsage = clientAuth
123+
keyUsage = critical,digitalSignature
124+
subjectKeyIdentifier = hash
125+
126+
```
127+
128+
1. In the CLI session, run the following command to generate a private key and a certificate signing request (CSR) in the *rootca* directory. For more information about the OpenSSL `req` command, see the [openssl-req](https://www.openssl.org/docs/man3.1/man1/openssl-req.html) manual page in [OpenSSL documentation](https://www.openssl.org/docs/).
129+
130+
```bash
131+
openssl req -new -config rootca.conf -out rootca.csr -keyout private/rootca.key
132+
```
133+
134+
1. In the CLI session, run the following command to create a self-signed root CA certificate. The command applies the `ca_ext` configuration file extensions to the certificate. These extensions indicate that the certificate is for a root CA and can be used to sign certificates and certificate revocation lists (CRLs).
135+
136+
```bash
137+
openssl ca -selfsign -config rootca.conf -in rootca.csr -out rootca.crt -extensions ca_ext
138+
```
139+
140+
## Create a subordinate CA
141+
142+
Intro
143+
144+
Proc
145+
146+
1. Start an Azure CLI session and run the following command, replacing *{basedir}* with the folder that contains your previously-created root CA.
147+
148+
```bash
149+
cd {basedir}
150+
```
151+
152+
1. In the CLI session, run the following commands, one at a time. This step creates the following folder structure and support files for the subordinate CA.
153+
154+
| Folder or file | Description |
155+
| --- | --- |
156+
| subca | The root folder of the subordinate CA. |
157+
| subca/certs | The folder in which CA certificates for the subordinate CA are created and stored. |
158+
| subca/db | The folder in which the database for the subordinate CA is stored. |
159+
| subca/db/index | The index file for the subordinate CA. The `touch` command creates a file without any content, for later use. |
160+
| subca/db/serial | The serial number file for the subordinate CA. The `openssl` command creates a 16-byte random number in hexadecimal format, then stores it in this file. |
161+
| subca/db/crlnumber | A file used to store serial numbers for revoked CA certificates issued by the subordinate CA. The `echo` command pipes a sample serial number, 1001, into the file. |
162+
| subca/private | The folder in which private files, including the private key, for the subordinate CA are stored. |
163+
164+
```bash
165+
mkdir subca
166+
cd subca
167+
mkdir certs db private
168+
touch db/index
169+
openssl rand -hex 16 > db/serial
170+
echo 1001 > db/crlnumber
171+
```
172+
173+
1. Create a text file named *subca.conf* in the *subca* folder created in the previous step, then copy and save the following OpenSSL configuration settings into that file. The file provides OpenSSL with the values needed to configure your test subordinate CA. For this example, the file configures a subordinate CA named *subca* for the *example.com* domain, using the folders and files created in previous steps. The file also provides configuration settings for:
174+
- The CA policy used by the subordinate CA for certificate Distinguished Name (DN) fields
175+
- Certificate requests created by the subordinate CA
176+
- X.509 extensions applied to root CA certificates, intermediate CA certificates, and client certificates issued by the subordinate CA
177+
178+
For more information about the syntax of OpenSSL configuration files, see the [config](https://www.openssl.org/docs/manmaster/man5/config.html) master manual page in [OpenSSL documentation](https://www.openssl.org/docs/).
179+
180+
```bash
181+
[default]
182+
name = subca
183+
domain_suffix = example.com
184+
aia_url = http://$name.$domain_suffix/$name.crt
185+
crl_url = http://$name.$domain_suffix/$name.crl
186+
default_ca = ca_default
187+
name_opt = utf8,esc_ctrl,multiline,lname,align
188+
189+
[ca_dn]
190+
commonName = "Test Subordinate CA"
191+
192+
[ca_default]
193+
home = .
194+
database = $home/db/index
195+
serial = $home/db/serial
196+
crlnumber = $home/db/crlnumber
197+
certificate = $home/$name.crt
198+
private_key = $home/private/$name.key
199+
RANDFILE = $home/private/random
200+
new_certs_dir = $home/certs
201+
unique_subject = no
202+
copy_extensions = copy
203+
default_days = 365
204+
default_crl_days = 90
205+
default_md = sha256
206+
policy = policy_c_o_match
207+
208+
[policy_c_o_match]
209+
countryName = optional
210+
stateOrProvinceName = optional
211+
organizationName = optional
212+
organizationalUnitName = optional
213+
commonName = supplied
214+
emailAddress = optional
215+
216+
[req]
217+
default_bits = 2048
218+
encrypt_key = yes
219+
default_md = sha256
220+
utf8 = yes
221+
string_mask = utf8only
222+
prompt = no
223+
distinguished_name = ca_dn
224+
req_extensions = ca_ext
225+
226+
[ca_ext]
227+
basicConstraints = critical,CA:true
228+
keyUsage = critical,keyCertSign,cRLSign
229+
subjectKeyIdentifier = hash
230+
231+
[sub_ca_ext]
232+
authorityKeyIdentifier = keyid:always
233+
basicConstraints = critical,CA:true,pathlen:0
234+
extendedKeyUsage = clientAuth,serverAuth
235+
keyUsage = critical,keyCertSign,cRLSign
236+
subjectKeyIdentifier = hash
237+
238+
[client_ext]
239+
authorityKeyIdentifier = keyid:always
240+
basicConstraints = critical,CA:false
241+
extendedKeyUsage = clientAuth
242+
keyUsage = critical,digitalSignature
243+
subjectKeyIdentifier = hash
244+
```
245+
246+
1. In the CLI session, run the following commands to generate a private key and a certificate signing request (CSR) in the *subca* directory.
247+
248+
```bash
249+
openssl req -new -config subca.conf -out subca.csr -keyout private/subca.key
250+
```
251+
252+
1. In the CLI session, run the following command to create a self-signed root CA certificate in the *subca* directory. The command applies the `ca_ext` configuration file extensions to the certificate. These extensions indicate that the certificate is for a root CA and can be used to sign certificates and certificate revocation lists (CRLs). The command also signs
253+
254+
```bash
255+
openssl ca -selfsign -config rootca.conf -in rootca.csr -out rootca.crt -extensions ca_ext
256+
```
257+
## Step 6 - Create a subordinate CA
258+
259+
This example shows you how to create a subordinate or registration CA. Because you can use the root CA to sign certificates, creating a subordinate CA isn’t strictly necessary. Having a subordinate CA does, however, mimic real world certificate hierarchies in which the root CA is kept offline and a subordinate CA issues client certificates.
260+
261+
From the *subca* directory, use the configuration file to generate a private key and a certificate signing request (CSR).
262+
263+
```bash
264+
openssl req -new -config subca.conf -out subca.csr -keyout private/subca.key
265+
```
266+
267+
Submit the CSR to the root CA and use the root CA to issue and sign the subordinate CA certificate. Specify `sub_ca_ext` for the extensions switch on the command line. The extensions indicate that the certificate is for a CA that can sign certificates and certificate revocation lists (CRLs). When prompted, sign the certificate, and commit it to the database.
268+
269+
```bash
270+
openssl ca -config ../rootca/rootca.conf -in subca.csr -out subca.crt -extensions sub_ca_ext
271+
```

0 commit comments

Comments
 (0)