Skip to content

Commit 5f85e53

Browse files
prmerger-automator[bot]prmerger-automator[bot]
authored
Merge pull request #223367 from PatAltimore/patricka-cert-perms
Add certificate owner and permission requirements
2 parents 60ccd19 + 3b39306 commit 5f85e53

5 files changed

+286
-57
lines changed

‎articles/iot-edge/how-to-connect-downstream-device.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
---
2-
title: Connect downstream devices - Azure IoT Edge | Microsoft Docs
2+
title: Connect a downstream device to an Azure IoT Edge gateway
33
description: How to configure downstream devices to connect to Azure IoT Edge gateway devices.
44
author: PatAltimore
55

66
ms.author: patricka
7-
ms.date: 06/02/2022
7+
ms.date: 01/09/2023
88
ms.topic: conceptual
99
ms.service: iot-edge
1010
services: iot-edge

‎articles/iot-edge/how-to-connect-downstream-iot-edge-device.md

Lines changed: 139 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: Step by step adaptable manual instructions on how to create a hiera
44
author: PatAltimore
55

66
ms.author: patricka
7-
ms.date: 10/5/2022
7+
ms.date: 01/17/2023
88
ms.topic: conceptual
99
ms.service: iot-edge
1010
services: iot-edge
@@ -140,26 +140,99 @@ To configure your parent device, open a local or remote command shell.
140140

141141
To enable secure connections, every IoT Edge parent device in a gateway scenario needs to be configured with a unique device CA certificate and a copy of the root CA certificate shared by all devices in the gateway hierarchy.
142142

143-
01. Transfer the **root CA certificate**, **parent device CA certificate**, and **parent private key** to the parent device. The examples in this article use the preferred directory `/var/aziot` for the certificates and keys.
143+
01. Check your certificates meet the [format requirements](how-to-manage-device-certificates.md#format-requirements).
144144

145-
01. Install the **root CA certificate** on the parent IoT Edge device. First, copy the root certificate into the certificate directory and add `.crt` to the end of the file name. Next, update the certificate store on the device using the platform-specific command.
145+
01. Transfer the **root CA certificate**, **parent device CA certificate**, and **parent private key** to the parent device.
146146

147-
**Debian or Ubuntu:**
147+
01. Copy the certificates and keys to the correct directories. The preferred directories for device certificates are `/var/aziot/certs` for the certificates and `/var/aziot/secrets` for keys.
148148

149149
```bash
150-
sudo cp /var/aziot/certs/azure-iot-test-only.root.ca.cert.pem /usr/local/share/ca-certificates/azure-iot-test-only.root.ca.cert.pem.crt
150+
### Copy device certificate ###
151151

152-
sudo update-ca-certificates
152+
# If the device certificate and keys directories don't exist, create, set ownership, and set permissions
153+
sudo mkdir -p /var/aziot/certs
154+
sudo chown aziotcs:aziotcs /var/aziot/certs
155+
sudo chmod 755 /var/aziot/certs
156+
157+
sudo mkdir -p /var/aziot/secrets
158+
sudo chown aziotks:aziotks /var/aziot/secrets
159+
sudo chmod 700 /var/aziot/secrets
160+
161+
# Copy full-chain device certificate and private key into the correct directory
162+
sudo cp iot-edge-device-ca-gateway-full-chain.cert.pem /var/aziot/certs
163+
sudo cp iot-edge-device-ca-gateway.key.pem /var/aziot/secrets
164+
165+
### Root certificate ###
166+
167+
# Copy root certificate into the /certs directory
168+
sudo cp azure-iot-test-only.root.ca.cert.pem /var/aziot/certs
169+
170+
# Copy root certificate into the CA certificate directory and add .crt extension.
171+
# The root certificate must be in the CA certificate directory to install it in the certificate store.
172+
# Use the appropriate copy command for your device OS or if using EFLOW.
173+
174+
# For Ubuntu and Debian, use /usr/local/share/ca-certificates/
175+
sudo cp azure-iot-test-only.root.ca.cert.pem /usr/local/share/azure-iot-test-only.root.ca.cert.pem.crt
176+
# For EFLOW, use /etc/pki/ca-trust/source/anchors/
177+
sudo cp azure-iot-test-only.root.ca.cert.pem /etc/pki/ca-trust/source/anchors/azure-iot-test-only.root.ca.pem.crt
153178
```
154179

155-
**IoT Edge for Linux on Windows (EFLOW):**
180+
01. Change the ownership and permissions of the certificates and keys.
156181

157182
```bash
158-
sudo cp /var/aziot/certs/azure-iot-test-only.root.ca.cert.pem /etc/pki/ca-trust/source/anchors/azure-iot-test-only.root.ca.cert.pem.crt
183+
# Give aziotcs ownership to certificates
184+
# Read and write for aziotcs, read-only for others
185+
sudo chown -R aziotcs:aziotcs /var/aziot/certs
186+
sudo find /var/aziot/certs -type f -name "*.*" -exec chmod 644 {} \;
187+
188+
# Give aziotks ownership to private keys
189+
# Read and write for aziotks, no permission for others
190+
sudo chown -R aziotks:aziotks /var/aziot/secrets
191+
sudo find /var/aziot/secrets -type f -name "*.*" -exec chmod 600 {} \;
192+
193+
# Verify permissions of directories and files
194+
sudo ls -Rla /var/aziot
195+
```
159196

197+
The output of list with correct ownership and permission is similar to the following:
198+
199+
```Output
200+
azureUser@vm-h2hnm5j5uxk2a:/var/aziot$ sudo ls -Rla /var/aziot
201+
/var/aziot:
202+
total 16
203+
drwxr-xr-x 4 root root 4096 Dec 14 00:16 .
204+
drwxr-xr-x 15 root root 4096 Dec 14 00:15 ..
205+
drw-r--r-- 2 aziotcs aziotcs 4096 Jan 14 00:31 certs
206+
drwx------ 2 aziotks aziotks 4096 Jan 14 00:35 secrets
207+
208+
/var/aziot/certs:
209+
total 20
210+
drw-r--r-- 2 aziotcs aziotcs 4096 Jan 14 00:31 .
211+
drwxr-xr-x 4 root root 4096 Dec 14 00:16 ..
212+
-rw-r--r-- 1 aziotcs aziotcs 1984 Jan 14 00:24 azure-iot-test-only.root.ca.cert.pem
213+
-rw-r--r-- 1 aziotcs aziotcs 5887 Jan 14 00:27 iot-edge-device-ca-gateway-full-chain.cert.pem
214+
215+
/var/aziot/secrets:
216+
total 20
217+
drwx------ 2 aziotks aziotks 4096 Jan 14 00:35 .
218+
drwxr-xr-x 4 root root 4096 Dec 14 00:16 ..
219+
-rw------- 1 aziotks aziotks 3326 Jan 14 00:29 azure-iot-test-only.root.ca.key.pem
220+
-rw------- 1 aziotks aziotks 3243 Jan 14 00:28 iot-edge-device-ca-gateway.key.pem
221+
```
222+
223+
224+
01. Install the **root CA certificate** on the parent IoT Edge device by updating the certificate store on the device using the platform-specific command.
225+
226+
```bash
227+
# Update the certificate store
228+
229+
# For Ubuntu and Debian, use update-ca-certificates command
230+
sudo update-ca-certificates
231+
# For EFLOW, use update-ca-trust
160232
sudo update-ca-trust
161233
```
162-
For more information about using `update-ca-trust`, see [CBL-Mariner SSL CA certificates management](https://github.com/microsoft/CBL-Mariner/blob/1.0/toolkit/docs/security/ca-certificates.md).
234+
235+
For more information about using `update-ca-trust` in EFLOW, see [CBL-Mariner SSL CA certificates management](https://github.com/microsoft/CBL-Mariner/blob/1.0/toolkit/docs/security/ca-certificates.md).
163236

164237
The command reports one certificate was added to `/etc/ssl/certs`.
165238

@@ -319,26 +392,69 @@ To configure your downstream device, open a local or remote command shell.
319392
320393
To enable secure connections, every IoT Edge downstream device in a gateway scenario needs to be configured with a unique device CA certificate and a copy of the root CA certificate shared by all devices in the gateway hierarchy.
321394
322-
01. Transfer the **root CA certificate**, **child device CA certificate**, and **child private key** to the downstream device. The examples in this article use the directory `/var/aziot` for the certificates and keys directory.
395+
01. Check your certificates meet the [format requirements](how-to-manage-device-certificates.md#format-requirements).
323396
324-
01. Install the **root CA certificate** on the downstream IoT Edge device. First, copy the root certificate into the certificate directory and add `.crt` to the end of the file name. Next, update the certificate store on the device using the platform-specific command.
397+
01. Transfer the **root CA certificate**, **child device CA certificate**, and **child private key** to the downstream device.
325398
326-
**Debian or Ubuntu:**
399+
01. Copy the certificates and keys to the correct directories. The preferred directories for device certificates are `/var/aziot/certs` for the certificates and `/var/aziot/secrets` for keys.
327400
328401
```bash
329-
sudo cp /var/aziot/certs/azure-iot-test-only.root.ca.cert.pem /usr/local/share/ca-certificates/azure-iot-test-only.root.ca.cert.pem.crt
402+
### Copy device certificate ###
330403
331-
sudo update-ca-certificates
404+
# If the device certificate and keys directories don't exist, create, set ownership, and set permissions
405+
sudo mkdir -p /var/aziot/certs
406+
sudo chown aziotcs:aziotcs /var/aziot/certs
407+
sudo chmod 755 /var/aziot/certs
408+
409+
sudo mkdir -p /var/aziot/secrets
410+
sudo chown aziotks:aziotks /var/aziot/secrets
411+
sudo chmod 700 /var/aziot/secrets
412+
413+
# Copy device full-chain certificate and private key into the correct directory
414+
sudo cp iot-device-downstream-full-chain.cert.pem /var/aziot/certs
415+
sudo cp iot-device-downstream.key.pem /var/aziot/secrets
416+
417+
### Root certificate ###
418+
419+
# Copy root certificate into the /certs directory
420+
sudo cp azure-iot-test-only.root.ca.cert.pem /var/aziot/certs
421+
422+
# Copy root certificate into the CA certificate directory and add .crt extension.
423+
# The root certificate must be in the CA certificate directory to install it in the certificate store.
424+
# Use the appropriate copy command for your device OS or if using EFLOW.
425+
426+
# For Ubuntu and Debian, use /usr/local/share/ca-certificates/
427+
sudo cp azure-iot-test-only.root.ca.cert.pem /usr/local/share/azure-iot-test-only.root.ca.cert.pem.crt
428+
# For EFLOW, use /etc/pki/ca-trust/source/anchors/
429+
sudo cp azure-iot-test-only.root.ca.cert.pem /etc/pki/ca-trust/source/anchors/azure-iot-test-only.root.ca.pem.crt
332430
```
333431
334-
**IoT Edge for Linux on Windows (EFLOW):**
432+
01. Change the ownership and permissions of the certificates and keys.
335433
336434
```bash
337-
sudo cp /var/aziot/certs/azure-iot-test-only.root.ca.cert.pem /etc/pki/ca-trust/source/anchors/azure-iot-test-only.root.ca.cert.pem.crt
435+
# Give aziotcs ownership to certificates
436+
# Read and write for aziotcs, read-only for others
437+
sudo chown -R aziotcs:aziotcs /var/aziot/certs
438+
sudo find /var/aziot/certs -type f -name "*.*" -exec chmod 644 {} \;
439+
440+
# Give aziotks ownership to private keys
441+
# Read and write for aziotks, no permission for others
442+
sudo chown -R aziotks:aziotks /var/aziot/secrets
443+
sudo find /var/aziot/secrets -type f -name "*.*" -exec chmod 600 {} \;
444+
```
338445
446+
01. Install the **root CA certificate** on the downstream IoT Edge device by updating the certificate store on the device using the platform-specific command.
447+
448+
```bash
449+
# Update the certificate store
450+
451+
# For Ubuntu and Debian, use update-ca-certificates command
452+
sudo update-ca-certificates
453+
# For EFLOW, use update-ca-trust
339454
sudo update-ca-trust
340455
```
341-
For more information about using `update-ca-trust`, see [CBL-Mariner SSL CA certificates management](https://github.com/microsoft/CBL-Mariner/blob/1.0/toolkit/docs/security/ca-certificates.md).
456+
457+
For more information about using `update-ca-trust` in EFLOW, see [CBL-Mariner SSL CA certificates management](https://github.com/microsoft/CBL-Mariner/blob/1.0/toolkit/docs/security/ca-certificates.md).
342458
343459
The command reports one certificate was added to `/etc/ssl/certs`.
344460
@@ -390,8 +506,8 @@ You should already have IoT Edge installed on your device. If not, follow the st
390506
391507
```toml
392508
[edge_ca]
393-
cert = "file:///var/aziot/certs/iot-edge-device-ca-downstream-full-chain.cert.pem"
394-
pk = "file:///var/aziot/secrets/iot-edge-device-ca-downstream.key.pem"
509+
cert = "file:///var/aziot/certs/iot-device-downstream-full-chain.cert.pem"
510+
pk = "file:///var/aziot/secrets/iot-device-downstream.key.pem"
395511
```
396512
397513
01. Verify your IoT Edge device uses the correct version of the IoT Edge agent when it starts. Find the **Default Edge Agent** section and set the image value for IoT Edge to version 1.4. For example:
@@ -408,8 +524,8 @@ You should already have IoT Edge installed on your device. If not, follow the st
408524
trust_bundle_cert = "file:///var/aziot/certs/azure-iot-test-only.root.ca.cert.pem"
409525
410526
[edge_ca]
411-
cert = "file:///var/aziot/certs/iot-edge-device-ca-downstream-full-chain.cert.pem"
412-
pk = "file:///var/aziot/secrets/iot-edge-device-ca-downstream.key.pem"
527+
cert = "file:///var/aziot/certs/iot-device-downstream-full-chain.cert.pem"
528+
pk = "file:///var/aziot/secrets/iot-device-downstream.key.pem"
413529
```
414530
415531
01. Save and close the `config.toml` configuration file. For example if you're using the **nano** editor, select **Ctrl+O** - *Write Out*, **Enter**, and **Ctrl+X** - *Exit*.
@@ -455,7 +571,6 @@ You should already have IoT Edge installed on your device. If not, follow the st
455571
456572
```Output
457573
azureUser@child-vm:~$ openssl s_client -connect <parent hostname>:8883 </dev/null 2>&1 >/dev/null
458-
459574
Can't use SSL_get_servername
460575
depth=3 CN = Azure_IoT_Hub_CA_Cert_Test_Only
461576
verify return:1
@@ -475,7 +590,7 @@ You should already have IoT Edge installed on your device. If not, follow the st
475590
If the command times out, there may be blocked ports between the child and parent devices. Review the network configuration and settings for the devices.
476591
477592
> [!WARNING]
478-
> A previous version of this document directed users to copy the `iot-edge-device-ca-gateway.cert.pem` certificate for use in the gateway `[edge_ca]` section. This was incorrect, and results in certificate validation errors from the downstream device. For example, the `openssl s_client ...` command above will produce:
593+
> Not using a full-chain certificate in the gateway's `[edge_ca]` section results in certificate validation errors from the downstream device. For example, the `openssl s_client ...` command above will produce:
479594
>
480595
> ```
481596
> Can't use SSL_get_servername
@@ -487,7 +602,7 @@ You should already have IoT Edge installed on your device. If not, follow the st
487602
> DONE
488603
> ```
489604
>
490-
> The same issue will appear for TLS-enabled devices connecting to the downstream Edge device if `iot-edge-device-ca-downstream.cert.pem` is copied to the device instead of `iot-edge-device-ca-downstream-full-chain.cert.pem`.
605+
> The same issue occurs for TLS-enabled devices that connect to the downstream IoT Edge device if the full-chain device certificate isn't used and configured on the downstream device.
491606
492607
## Network isolate downstream devices
493608

‎articles/iot-edge/how-to-create-transparent-gateway.md

Lines changed: 46 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
---
2-
title: Create transparent gateway device - Azure IoT Edge | Microsoft Docs
2+
title: Create transparent gateway device using Azure IoT Edge
33
description: Use an Azure IoT Edge device as a transparent gateway that can process information from downstream devices
44
author: PatAltimore
55

66
ms.author: patricka
7-
ms.date: 11/1/2022
7+
ms.date: 01/17/2022
88
ms.topic: conceptual
99
ms.service: iot-edge
1010
services: iot-edge
@@ -114,20 +114,41 @@ If you don't have your own certificate authority and want to use demo certificat
114114

115115
# [IoT Edge](#tab/iotedge)
116116

117+
1. Check the certificate meets [format requirements](how-to-manage-device-certificates.md#format-requirements).
117118
1. If you created the certificates on a different machine, copy them over to your IoT Edge device. You can use a USB drive, a service like [Azure Key Vault](../key-vault/general/overview.md), or with a function like [Secure file copy](https://www.ssh.com/ssh/scp/).
118119
1. Move the files to the preferred directory for certificates and keys. Use `/var/aziot/certs` for certificates and `/var/aziot/secrets` for keys.
119-
1. Change the ownership and permissions of the certificates and keys.
120+
1. Create the certificates and keys directories and set permissions. You should store your certificates and keys to the preferred `/var/aziot` directory. Use `/var/aziot/certs` for certificates and `/var/aziot/secrets` for keys.
120121

121122
```bash
123+
# If the certificate and keys directories don't exist, create, set ownership, and set permissions
124+
sudo mkdir -p /var/aziot/certs
122125
sudo chown aziotcs:aziotcs /var/aziot/certs
123-
sudo chown -R iotedge /var/aziot/certs
124-
sudo chmod 644 /var/aziot/secrets/
126+
sudo chmod 755 /var/aziot/certs
127+
128+
sudo mkdir -p /var/aziot/secrets
129+
sudo chown aziotks:aziotks /var/aziot/secrets
130+
sudo chmod 700 /var/aziot/secrets
131+
```
132+
1. Change the ownership and permissions of the certificates and keys.
133+
134+
```bash
135+
# Give aziotcs ownership to certificates
136+
# Read and write for aziotcs, read-only for others
137+
sudo chown -R aziotcs:aziotcs /var/aziot/certs
138+
sudo find /var/aziot/certs -type f -name "*.*" -exec chmod 644 {} \;
139+
140+
# Give aziotks ownership to private keys
141+
# Read and write for aziotks, no permission for others
142+
sudo chown -R aziotks:aziotks /var/aziot/secrets
143+
sudo find /var/aziot/secrets -type f -name "*.*" -exec chmod 600 {} \;
125144
```
126145

127146
# [IoT Edge for Linux on Windows](#tab/eflow)
128147

129148
Now, you need to copy the certificates to the Azure IoT Edge for Linux on Windows virtual machine.
130149

150+
1. Check the certificate meets [format requirements](how-to-manage-device-certificates.md#format-requirements).
151+
131152
1. Copy the certificates to the EFLOW virtual machine to a directory where you have write access. For example, the `/home/iotedge-user` home directory.
132153

133154
```powershell
@@ -146,27 +167,42 @@ Now, you need to copy the certificates to the Azure IoT Edge for Linux on Window
146167
Connect-EflowVm
147168
```
148169

149-
1. Create the certificates directory. You should store your certificates and keys to the preferred `/var/aziot` directory. Use `/var/aziot/certs` for certificates and `/var/aziot/secrets` for keys.
170+
1. Create the certificates and keys directories and set permissions. You should store your certificates and keys to the preferred `/var/aziot` directory. Use `/var/aziot/certs` for certificates and `/var/aziot/secrets` for keys.
150171

151172
```bash
173+
# If the certificate and keys directories don't exist, create, set ownership, and set permissions
152174
sudo mkdir -p /var/aziot/certs
175+
sudo chown aziotcs:aziotcs /var/aziot/certs
176+
sudo chmod 755 /var/aziot/certs
177+
153178
sudo mkdir -p /var/aziot/secrets
179+
sudo chown aziotks:aziotks /var/aziot/secrets
180+
sudo chmod 700 /var/aziot/secrets
154181
```
155182

156183
1. Move the certificates and keys to the preferred `/var/aziot` directory.
157184

158185
```bash
159186
# Move the IoT Edge device CA certificate and key to preferred location
187+
sudo mv ~/azure-iot-test-only.root.ca.cert.pem /var/aziot/certs
160188
sudo mv ~/iot-edge-device-ca-<cert name>-full-chain.cert.pem /var/aziot/certs
161189
sudo mv ~/iot-edge-device-ca-<cert name>.key.pem /var/aziot/secrets
162-
sudo mv ~/azure-iot-test-only.root.ca.cert.pem /var/aziot/certs
163190
```
164191

165192
1. Change the ownership and permissions of the certificates and keys.
166193

167194
```bash
168-
sudo chown -R iotedge /var/aziot/certs
169-
sudo chmod 644 /var/aziot/secrets/iot-edge-device-ca-<cert name>.key.pem
195+
# Give aziotcs ownership to certificate
196+
# Read and write for aziotcs, read-only for others
197+
sudo chown aziotcs:aziotcs /var/aziot/certs/azure-iot-test-only.root.ca.cert.pem
198+
sudo chown aziotcs:aziotcs /var/aziot/certs/iot-edge-device-ca-<cert name>-full-chain.cert.pem
199+
sudo chmod 644 /var/aziot/certs/azure-iot-test-only.root.ca.cert.pem
200+
sudo chmod 644 /var/aziot/certs/iot-edge-device-ca-<cert name>-full-chain.cert.pem
201+
202+
# Give aziotks ownership to private key
203+
# Read and write for aziotks, no permission for others
204+
sudo chown aziotks:aziotks /var/aziot/secrets/iot-edge-device-ca-<cert name>.key.pem
205+
sudo chmod 600 /var/aziot/secrets/iot-edge-device-ca-<cert name>.key.pem
170206
```
171207

172208
1. Exit the EFLOW VM connection.
@@ -239,7 +275,7 @@ Downstream devices send telemetry and messages to the gateway device, where the
239275

240276
* The IoT Edge hub module is deployed to the device.
241277

242-
When you first install IoT Edge on a device, only one system module starts automatically: the IoT Edge agent. Once you create the first deployment for a device, the second system module, the IoT Edge hub, starts as well. If the **edgeHub** module isn't running on your device, create a deployment for your device.
278+
When you first install IoT Edge on a device, only one system module starts automatically: the IoT Edge agent. Once you create the first deployment for a device, the second system module and the IoT Edge hub start as well. If the **edgeHub** module isn't running on your device, create a deployment for your device.
243279

244280
* The IoT Edge hub module has routes set up to handle incoming messages from downstream devices.
245281

0 commit comments

Comments
 (0)