Tutorial: Bereitstellen mehrerer X.509-Geräte mit Registrierungsgruppen

Die folgenden Voraussetzungen gelten für eine Windows-Entwicklungsumgebung, die zum Simulieren der Geräte verwendet wird. Informationen zu Linux oder macOS finden Sie in der SDK-Dokumentation im entsprechenden Abschnitt unter Vorbereiten Ihrer Entwicklungsumgebung.

• Installieren Sie Visual Studio 2022 mit der aktivierten Workload Desktopentwicklung mit C++. Visual Studio 2015, Visual Studio 2017 und Visual Studio 2019 werden ebenfalls unterstützt.

• Installieren Sie das neueste CMake-Buildsystem. Überprüfen Sie unbedingt die Option, mit der die ausführbare Datei „CMake“ Ihrem Pfad hinzugefügt wird.

  Wichtig

  Vergewissern Sie sich vor Beginn der Installation von CMake, dass die erforderlichen Visual Studio-Komponenten (Visual Studio und die Workload „Desktopentwicklung mit C++“) auf dem Computer installiert sind. Sobald die Voraussetzungen erfüllt sind und der Download überprüft wurde, installieren Sie das CMake-Buildsystem. Beachten Sie auch, dass ältere Versionen des CMake-Buildsystems die in diesem Tutorial verwendete Projektmappendatei nicht generieren können. Stellen Sie sicher, dass Sie die neueste Version von CMake verwenden.

Die folgenden Voraussetzungen gelten für eine Windows-Entwicklungsumgebung. Informationen zu Linux oder macOS finden Sie in der SDK-Dokumentation im entsprechenden Abschnitt unter Vorbereiten Ihrer Entwicklungsumgebung.

• Installieren Sie das .NET SDK 6.0 oder höher auf Ihrem Windows-Computer. Sie können den folgenden Befehl ausführen, um Ihre Version zu überprüfen:

  dotnet --info
  

Die folgenden Voraussetzungen gelten für eine Windows-Entwicklungsumgebung. Informationen zu Linux oder macOS finden Sie in der SDK-Dokumentation im entsprechenden Abschnitt unter Vorbereiten Ihrer Entwicklungsumgebung.

• Installieren Sie Node.js v4.0 oder höher auf Ihrem Computer.

Die folgenden Voraussetzungen gelten für eine Windows-Entwicklungsumgebung.

• Python 3.6 oder höher auf Ihrem Computer.

Die folgenden Voraussetzungen gelten für eine Windows-Entwicklungsumgebung. Informationen zu Linux oder macOS finden Sie in der SDK-Dokumentation im entsprechenden Abschnitt unter Vorbereiten Ihrer Entwicklungsumgebung.

• Installieren Sie das Java SE Development Kit 8 oder höher auf Ihrem Computer.

• Laden Sie Maven herunter, und installieren Sie es.

In diesem Abschnitt bereiten Sie eine Entwicklungsumgebung vor, die zum Erstellen des Azure IoT C SDK verwendet wird. Das SDK enthält Beispielcode und Tools für die Gerätebereitstellung mit DPS.

1. Öffnen Sie einen Webbrowser, und wechseln Sie zur Releaseseite für das Azure IoT C SDK.

2. Kopieren Sie den Tagnamen für das aktuelle Release des Azure IoT C SDK, z. B.: lts_03_2024.

3. Öffnen Sie eine Windows-Eingabeaufforderung und führen Sie die folgenden Befehle zum Klonen des aktuellen Releases des GitHub-Repositorys Azure IoT-Geräte-SDK für C aus. Ersetzen Sie <release-tag> durch das Tag, das Sie im vorherigen Schritt kopiert haben.

   git clone -b <release-tag> https://github.com/Azure/azure-iot-sdk-c.git
   cd azure-iot-sdk-c
   git submodule update --init
   

   Dieser Vorgang kann mehrere Minuten dauern.

4. Wenn der Vorgang abgeschlossen ist, führen Sie die folgenden Befehle aus dem Verzeichnis azure-iot-sdk-c aus:

   mkdir cmake
   cd cmake
   

5. Das Codebeispiel verwendet ein X.509-Zertifikat für den Nachweis mittels X.509-Authentifizierung. Erstellen Sie mithilfe des folgenden Befehls eine spezifische SDK-Version für Ihre Entwicklungsplattform, die den Gerätebereitstellungsclient enthält. Im cmake-Verzeichnis wird eine Visual Studio-Projektmappe für das simulierte Gerät generiert.

   Ersetzen Sie <path durch den absoluten Pfad zum C SDK, das Sie geklont haben.

   cmake -Duse_prov_client:BOOL=ON -Dhsm_custom_lib=c:/<path>/azure-iot-sdk-c/cmake/provisioning_client/samples/custom_hsm_example/Debug/custom_hsm_example.lib ..
   

   Tipp

   Falls cmake Ihren C++-Compiler nicht findet, treten beim Ausführen des obigen Befehls unter Umständen Buildfehler auf. Führen Sie den Befehl in diesem Fall an der Visual Studio-Eingabeaufforderung aus.

6. Nach erfolgreicher Erstellung ähneln die letzten Ausgabezeilen der folgenden Ausgabe:

   cmake -Duse_prov_client:BOOL=ON -Dhsm_custom_lib=c:/azure-iot-sdk-c/cmake/provisioning_client/samples/custom_hsm_example/Debug/custom_hsm_example.lib ..
   -- Building for: Visual Studio 17 2022
   -- Selecting Windows SDK version 10.0.19041.0 to target Windows 10.0.22000.
   -- The C compiler identification is MSVC 19.32.31329.0
   -- The CXX compiler identification is MSVC 19.32.31329.0
   
   ...
   
   -- Configuring done
   -- Generating done
   -- Build files have been written to: C:/azure-iot-sdk-c/cmake
   

Öffnen Sie eine Windows-Eingabeaufforderung und klonen Sie das GitHub-Repository mit dem Azure IoT SDK für C# mithilfe des folgenden Befehls:

git clone https://github.com/Azure/azure-iot-sdk-csharp.git

Öffnen Sie eine Windows-Eingabeaufforderung und klonen Sie das GitHub-Repository mit dem Azure IoT SDK für Node.js mithilfe des folgenden Befehls:

git clone https://github.com/Azure/azure-iot-sdk-node.git

Öffnen Sie eine Windows-Eingabeaufforderung und klonen Sie das GitHub-Repository Azure IoT-Geräte-SDK für Python mithilfe des folgenden Befehls:

git clone -b v2 https://github.com/Azure/azure-iot-sdk-python.git --recursive

1. Öffnen Sie eine Windows-Eingabeaufforderung und klonen Sie das GitHub-Repository mit den Azure IoT-Beispielen für Java mithilfe des folgenden Befehls:

   git clone https://github.com/Azure/azure-iot-sdk-java.git --recursive
   

2. Navigieren Sie zum Stammverzeichnis azure-iot-sdk-java, und erstellen Sie das Projekt, um alle erforderlichen Pakete herunterzuladen.

   cd azure-iot-sdk-java
   mvn install -DskipTests=true
   

In diesem Abschnitt verwenden Sie Ihre Git Bash-Eingabeaufforderung und die Visual Studio-IDE.

Konfigurieren des Codes für die Bereitstellung des Geräts

In diesem Abschnitt aktualisieren Sie den Beispielcode mit den Informationen zu Ihrer Device Provisioning Service-Instanz.

1. Navigieren Sie im Azure-Portal zur Registerkarte Übersicht für Ihre Gerätebereitstellungsinstanz, und notieren Sie sich den Wert unter ID-Bereich.

   

2. Starten Sie Visual Studio, und öffnen Sie die neue Projektmappendatei, die im Verzeichnis cmake erstellt wurde, das Sie im Stammverzeichnis des Git-Repositorys „azure-iot-sdk-c“ erstellt haben. Die Projektmappendatei hat den Namen azure_iot_sdks.sln.

3. Navigieren Sie im Projektmappen-Explorer von Visual Studio zu Provision_Samples > prov_dev_client_sample > Source Files, und öffnen Sie prov_dev_client_sample.c.

4. Suchen Sie die Konstante id_scope, und ersetzen Sie den Wert durch Ihren ID-Bereich-Wert, den Sie zuvor kopiert haben. Beispiel:

   static const char* id_scope = "0ne00000A0A";
   

5. Suchen Sie die Definition für die Funktion main() in der gleichen Datei. Stellen Sie sicher, dass die Variable hsm_type auf SECURE_DEVICE_TYPE_X509 festgelegt ist und dass alle anderen hsm_type-Zeilen auskommentiert werden. Zum Beispiel:

   SECURE_DEVICE_TYPE hsm_type;
   //hsm_type = SECURE_DEVICE_TYPE_TPM;
   hsm_type = SECURE_DEVICE_TYPE_X509;
   //hsm_type = SECURE_DEVICE_TYPE_SYMMETRIC_KEY;
   

6. Speichern Sie die Änderungen.

7. Klicken Sie mit der rechten Maustaste auf das Projekt prov_dev_client_sample, und wählen Sie Als Startprojekt festlegen aus.

Konfigurieren des Stubcodes für das benutzerdefinierte HSM

Die Details der Interaktion mit sicherem hardwarebasiertem Speicher in der Praxis variieren je nach Gerätehardware. Die Zertifikatketten, die in diesem Tutorial von den simulierten Geräten genutzt werden, sind im Stubcode für das benutzerdefinierte HSM hartcodiert. In einem realen Fall wird die Zertifikatkette auf der eigentlichen HSM-Hardware gespeichert, um eine höhere Sicherheit für vertrauliche Informationen zu erzielen. Anschließend werden Methoden implementiert, die den Stubmethoden dieses Beispiels ähneln, um die Geheimnisse aus dem hardwarebasierten Speicher auszulesen.

HSM-Hardware ist zwar nicht erforderlich, wird aber empfohlen, um vertrauliche Informationen wie den privaten Schlüssel für das Zertifikat zu schützen. Wenn ein tatsächliches HSM durch das Beispiel aufgerufen werden würde, wäre der private Schlüssel nicht im Quellcode vorhanden. Ist der Schlüssel im Quellcode enthalten, wird er für jeden Benutzer verfügbar gemacht, der den Code anzeigen kann. Dieser Schritt wird in diesem Tutorial nur zu Lernzwecken ausgeführt.

So aktualisieren Sie den Stubcode für das benutzerdefinierte HSM zum Simulieren der Identität des Geräts mit der ID device-01:

1. Navigieren Sie im Projektmappen-Explorer von Visual Studio zu Provision_Samples> custom_hsm_example > Source Files, und öffnen Sie custom_hsm_example.c.

2. Aktualisieren Sie den Zeichenfolgenwert der Zeichenfolgenkonstante COMMON_NAME mit dem allgemeinen Namen (Common Name), den Sie beim Generieren des Gerätezertifikats verwendet haben.

   static const char* const COMMON_NAME = "device-01";
   

3. Führen Sie in Ihrem Git Bash-Terminal den folgenden Befehl aus, um die Zeichenfolgenkonstante für Ihr Gerätezertifikat zu generieren:

   sed -e 's/^/"/;$ !s/$/""\\n"/;$ s/$/"/' ./certs/device-01-full-chain.cert.pem
   

   Kopieren Sie die Ausgabe dieses Befehls.

4. Aktualisieren Sie den Zeichenfolgenwert der Zeichenfolgenkonstante CERTIFICATE mit der Zertifikatkette, die Sie nach dem Erstellen Ihrer Zertifikate in ./certs/device-01-full-chain.cert.pem gespeichert haben. Verwenden Sie den ausgegebenen Zertifikattext aus dem vorherigen Schritt für den konstanten Wert.

   Die Syntax des Zertifikattexts muss dem folgenden Muster (ohne zusätzliche Leerstellen oder eine Analyse durch Visual Studio) entsprechen.

   // <Device/leaf cert>
   // <intermediates>
   // <root>
   static const char* const CERTIFICATE = "-----BEGIN CERTIFICATE-----\n"
   "MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n"
       ...
   "MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n"
   "-----END CERTIFICATE-----\n"
   "-----BEGIN CERTIFICATE-----\n"
   "MIIFPDCCAySgAwIBAgIBATANBgkqhkiG9w0BAQsFADAqMSgwJgYDVQQDDB9BenVy\n"
       ...
   "MTEyMjIxMzAzM1owNDEyMDAGA1UEAwwpQXp1cmUgSW9UIEh1YiBJbnRlcm1lZGlh\n"
   "-----END CERTIFICATE-----\n"
   "-----BEGIN CERTIFICATE-----\n"
   "MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n"
       ...
   "MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n"
   "-----END CERTIFICATE-----";        
   

5. Führen Sie in Git Bash den folgenden Befehl aus, um die Zeichenfolgenkonstante für Ihren privaten Geräteschlüssel zu generieren:

   sed -e 's/^/"/;$ !s/$/""\\n"/;$ s/$/"/' ./private/device-01.key.pem
   

   Kopieren Sie die Ausgabe dieses Befehls.

6. Aktualisieren Sie den Zeichenfolgenwert der Zeichenfolgenkonstante PRIVATE_KEY mit dem privaten Schlüssel für Ihr Gerätezertifikat. Verwenden Sie den ausgegebenen Text des privaten Schlüssels aus dem vorherigen Schritt für den konstanten Wert.

   Die Syntax des Texts des privaten Schlüssels muss dem folgenden Muster ohne zusätzliche Leerstellen oder eine Analyse durch Visual Studio entsprechen.

   static const char* const PRIVATE_KEY = "-----BEGIN RSA PRIVATE KEY-----\n"
   "MIIJJwIBAAKCAgEAtjvKQjIhp0EE1PoADL1rfF/W6v4vlAzOSifKSQsaPeebqg8U\n"
       ...
   "X7fi9OZ26QpnkS5QjjPTYI/wwn0J9YAwNfKSlNeXTJDfJ+KpjXBcvaLxeBQbQhij\n"
   "-----END RSA PRIVATE KEY-----";
   

7. Speichern Sie die Änderungen.

8. Klicken Sie mit der rechten Maustaste auf das Projekt custom_hsm_-_example, und wählen Sie Erstellen aus.

   Wichtig

   Sie müssen das Projekt custom_hsm_example erstellen, bevor Sie die restliche Projektmappe im nächsten Abschnitt erstellen.

Ausführen des Beispiels

1. Wählen Sie im Visual Studio-Menü die Option Debuggen>Starten ohne Debugging aus, um die Projektmappe auszuführen. Wählen Sie in der Aufforderung zum erneuten Erstellen des Projekts Ja aus, um das Projekt vor der Ausführung neu zu erstellen.

   Die folgende Ausgabe ist ein Beispiel dafür, wie das simulierte Gerät device-01 erfolgreich hochfährt und sich mit dem Bereitstellungsdienst verbindet. Das Gerät wurde einem IoT-Hub zugewiesen und registriert:

   Provisioning API Version: 1.8.0
   
   Registering Device
   
   Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
   Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
   
   Registration Information received from service: contoso-hub-2.azure-devices.net, deviceId: device-01
   Press enter key to exit:
   

2. Wiederholen Sie die Schritte in Konfigurieren des Stubcodes für das benutzerdefinierte HSM für Ihr zweites Gerät (device-02) und führen Sie das Beispiel erneut aus. Verwenden Sie für dieses Gerät die folgenden Werte:

   BESCHREIBUNG	Wert
   Allgemeiner Name	"device-02"
   Vollständige Zertifikatkette	Generieren Sie den Text mithilfe von ./certs/device-02-full-chain.cert.pem
   Privater Schlüssel	Generieren Sie den Text mithilfe von ./private/device-02.key.pem

   Die folgende Ausgabe ist ein Beispiel dafür, wie das simulierte Gerät device-02 erfolgreich hochfährt und sich mit dem Bereitstellungsdienst verbindet. Das Gerät wurde einem IoT-Hub zugewiesen und registriert:

   Provisioning API Version: 1.8.0
   
   Registering Device
   
   Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
   Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
   
   Registration Information received from service: contoso-hub-2.azure-devices.net, deviceId: device-02
   Press enter key to exit:
   

Der C#-Beispielcode ist für die Verwendung von X.509-Zertifikaten konzipiert, die in einer kennwortgeschützten Datei im PKCS12-Format (.pfx) gespeichert sind. Die vollständigen Kettenzertifikate, die Sie zuvor erstellt haben, haben das PEM-Format. Um die vollständigen Kettenzertifikate in das PKCS#12-Format zu konvertieren, geben Sie die folgenden Befehle an Ihrer Git Bash-Eingabeaufforderung aus dem Verzeichnis ein, in dem Sie zuvor die OpenSSL-Befehle ausgeführt haben.

• device-01

  openssl pkcs12 -inkey ./private/device-01.key.pem -in ./certs/device-01-full-chain.cert.pem -export -passin pass:1234 -passout pass:1234 -out ./certs/device-01-full-chain.cert.pfx
  

• device-02

  openssl pkcs12 -inkey ./private/device-02.key.pem -in ./certs/device-02-full-chain.cert.pem -export -passin pass:1234 -passout pass:1234 -out ./certs/device-02-full-chain.cert.pfx
  

Im Rest dieses Abschnitts verwenden Sie Ihre Windows-Eingabeaufforderung.

1. Wählen Sie im Azure-Portal die Registerkarte Übersicht für Ihre Device Provisioning Service-Instanz.

2. Kopieren Sie den Wert von ID-Bereich.

   

3. Wechseln Sie in Ihrer Windows-Eingabeaufforderung zum Verzeichnis X509Sample. Dieses Verzeichnis befindet sich im SDK-Repository, das Sie in einem früheren Schritt geklont haben: .\azure-iot-sdk-csharp\provisioning\device\samples\getting started\X509Sample.

4. Geben Sie den folgenden Befehl ein, um das X.509-Gerätebereitstellungsbeispiel zu erstellen und auszuführen. Ersetzen Sie <id-scope> durch den ID-Bereich, den Sie im Azure-Portal kopiert haben. Ersetzen Sie <your-certificate-folder> durch den Pfad zu dem Ordner, in dem Sie Ihre OpenSSL-Befehle ausgeführt haben.

   dotnet run -- -s <id-scope> -c <your-certificate-folder>\certs\device-01-full-chain.cert.pfx -p 1234
   

   Das Gerät stellt eine Verbindung mit DPS her und wird einem IoT-Hub zugewiesen. Dann sendet das Gerät eine Telemetrienachricht an den IoT-Hub. Die Ausgabe sollte etwa folgendem Beispiel entsprechen:

   Loading the certificate...
   Found certificate: 3E5AA3C234B2032251F0135E810D75D38D2AA477 CN=Azure IoT Hub CA Cert Test Only; PrivateKey: False
   Found certificate: 81FE182C08D18941CDEEB33F53F8553BA2081E60 CN=Azure IoT Hub Intermediate Cert Test Only; PrivateKey: False
   Found certificate: 5BA1DB226D50EBB7A6A6071CED4143892855AE43 CN=device-01; PrivateKey: True
   Using certificate 5BA1DB226D50EBB7A6A6071CED4143892855AE43 CN=device-01
   Initializing the device provisioning client...
   Initialized for registration Id device-01.
   Registering with the device provisioning service...
   Registration status: Assigned.
   Device device-01 registered to contoso-hub-2.azure-devices.net.
   Creating X509 authentication for IoT Hub...
   Testing the provisioned device with IoT Hub...
   Sending a telemetry message...
   Finished.
   

   Hinweis

   Wenn Sie Zertifikat und Kennwort nicht in der Befehlszeile angeben, wird die Zertifikatdatei standardmäßig unter ./certificate.pfx erstellt, und Sie werden zur Eingabe Ihres Kennworts aufgefordert.

   Zusätzliche Parameter können übergeben werden, um TransportType (-t) und GlobalDeviceEndpoint (-g) zu ändern. Eine vollständige Liste der Parameter erhalten Sie durch Eingabe von dotnet run -- --help.

5. Führen Sie zum Registrieren Ihres zweiten Geräts das Beispiel mithilfe des vollständigen Kettenzertifikats erneut aus.

   dotnet run -- -s <id-scope> -c <your-certificate-folder>\certs\device-02-full-chain.cert.pfx -p 1234
   

Verwenden Sie in den folgenden Schritten Ihre Windows-Eingabeaufforderung.

1. Wählen Sie im Azure-Portal die Registerkarte Übersicht für Ihre Device Provisioning Service-Instanz.

2. Kopieren Sie den Wert von ID-Bereich.

   

3. Wechseln Sie in Ihrer Windows-Eingabeaufforderung zum Beispielverzeichnis, und installieren Sie die für das Beispiel erforderlichen Pakete. Der angezeigte Pfad ist relativ zu dem Speicherort, in dem Sie das SDK geklont haben.

   cd .\azure-iot-sdk-node\provisioning\device\samples
   npm install
   

4. Öffnen Sie im Ordner provisioning\device\samples die Datei register_x509.js, und überprüfen Sie den Code.

   Das Beispiel ist standardmäßig auf MQTT als Transportprotokoll festgelegt. Wenn Sie ein anderes Protokoll verwenden möchten, kommentieren Sie die folgende Zeile aus, und heben Sie die Auskommentierung für das geeignete Protokoll aus.

   var ProvisioningTransport = require('azure-iot-provisioning-device-mqtt').Mqtt;
   

   In dem Beispiel werden fünf Umgebungsvariablen für die Authentifizierung und Bereitstellung eines IoT-Geräts per DPS genutzt. Dies sind die folgenden Umgebungsvariablen:

   Variablenname	BESCHREIBUNG
   PROVISIONING_HOST	Der Endpunkt, der zum Herstellen einer Verbindung mit Ihrer DPS-Instanz verwendet werden soll. Verwenden Sie für dieses Tutorial den globalen Endpunkt global.azure-devices-provisioning.net.
   PROVISIONING_IDSCOPE	Der ID-Bereich für Ihre DPS-Instanz.
   PROVISIONING_REGISTRATION_ID	Registrierungs-ID für Ihre Geräteregistrierung Er muss mit dem allgemeinen Namen des Antragstellers im Gerätezertifikat übereinstimmen.
   CERTIFICATE_FILE	Der Pfad zur Datei mit dem vollständigen Kettenzertifikat Ihres Geräts.
   KEY_FILE	Der Pfad zur privaten Schlüsseldatei für das Gerätezertifikat.

   Die Methode ProvisioningDeviceClient.register() versucht, Ihr Gerät zu registrieren.

5. Fügen Sie Umgebungsvariablen für den globalen Geräteendpunkt und den ID-Bereich hinzu. Ersetzen Sie <id-scope> durch den Wert, den Sie aus dem Azure-Portal kopiert haben.

   set PROVISIONING_HOST=global.azure-devices-provisioning.net
   set PROVISIONING_IDSCOPE=<id-scope>
   

6. Legen Sie die Umgebungsvariable für die Registrierungs-ID für das Gerät fest. Die Registrierungs-ID für das IoT-Gerät muss mit dem allgemeinen Namen des Antragstellers im Gerätezertifikat übereinstimmen. In diesem Tutorial ist device-01 sowohl der Antragstellername als auch die Registrierungs-ID für das Gerät.

   set PROVISIONING_REGISTRATION_ID=device-01
   

7. Legen Sie die Umgebungsvariablen für das vollständige Kettenzertifikat des Geräts und die Dateien des privaten Geräteschlüssels fest, die Sie zuvor generiert haben. Ersetzen Sie <your-certificate-folder> durch den Pfad zu dem Ordner, in dem Sie Ihre OpenSSL-Befehle ausgeführt haben.

   set CERTIFICATE_FILE=<your-certificate-folder>\certs\device-01-full-chain.cert.pem
   set KEY_FILE=<your-certificate-folder>\private\device-01.key.pem
   

8. Führen Sie das Beispiel aus, und überprüfen Sie, ob das Gerät erfolgreich bereitgestellt wurde.

   node register_x509.js
   

   Die Ausgabe sollte etwa folgendem Beispiel entsprechen:

   registration succeeded
   assigned hub=contoso-hub-2.azure-devices.net
   deviceId=device-01
   Client connected
   send status: MessageEnqueued
   

9. Aktualisieren Sie die Umgebungsvariablen für Ihr zweites Gerät (device-02) gemäß der folgenden Tabelle, und führen Sie das Beispiel erneut aus.

   Umgebungsvariable	Wert
   PROVISIONING_REGISTRATION_ID	device-02
   CERTIFICATE_FILE	<your-certificate-folder>\certs\device-02-full-chain.cert.pem
   KEY_FILE	<your-certificate-folder>\private\device-02.key.pem

Verwenden Sie in den folgenden Schritten Ihre Windows-Eingabeaufforderung.

1. Wählen Sie im Azure-Portal die Registerkarte Übersicht für Ihre Device Provisioning Service-Instanz.

2. Kopieren Sie den Wert von ID-Bereich.

   

3. Wechseln Sie in Ihrer Windows-Eingabeaufforderung zum Verzeichnis des Beispiels provision_x509.py. Der angezeigte Pfad ist relativ zu dem Speicherort, in dem Sie das SDK geklont haben.

   cd .\azure-iot-sdk-python\samples\async-hub-scenarios
   

   In diesem Beispiel werden sechs Umgebungsvariablen für die Authentifizierung und Bereitstellung eines IoT-Geräts per DPS genutzt. Dies sind die folgenden Umgebungsvariablen:

   Variablenname	BESCHREIBUNG
   PROVISIONING_HOST	Der Endpunkt, der zum Herstellen einer Verbindung mit Ihrer DPS-Instanz verwendet werden soll. Verwenden Sie für dieses Tutorial den globalen Endpunkt global.azure-devices-provisioning.net.
   PROVISIONING_IDSCOPE	Der ID-Bereich für Ihre DPS-Instanz.
   DPS_X509_REGISTRATION_ID	Registrierungs-ID für Ihre Geräteregistrierung Er muss mit dem allgemeinen Namen des Antragstellers im Gerätezertifikat übereinstimmen.
   X509_CERT_FILE	Der Pfad zur Datei mit dem vollständigen Kettenzertifikat Ihres Geräts.
   X509_KEY_FILE	Der Pfad zur privaten Schlüsseldatei für das Gerätezertifikat.
   PASS_PHRASE	Die Passphrase, die Sie zum Verschlüsseln der Datei für den privaten Schlüssel verwendet haben (sofern zutreffend). Für dieses Tutorial nicht erforderlich.

4. Fügen Sie die Umgebungsvariablen für den globalen Geräteendpunkt und den ID-Bereich hinzu. Verwenden Sie für die Variable ID Bereich den Wert, den Sie aus dem Azure-Portal kopiert haben.

   set PROVISIONING_HOST=global.azure-devices-provisioning.net
   set PROVISIONING_IDSCOPE=<ID scope for your DPS resource>
   

5. Legen Sie die Umgebungsvariable für die Registrierungs-ID für das Gerät fest. Die Registrierungs-ID für das IoT-Gerät muss mit dem allgemeinen Namen des Antragstellers im Gerätezertifikat übereinstimmen. In diesem Tutorial ist device-01 sowohl der Antragstellername als auch die Registrierungs-ID für das Gerät.

   set DPS_X509_REGISTRATION_ID=device-01
   

6. Legen Sie die Umgebungsvariablen für das vollständige Kettenzertifikat des Geräts und die Dateien des privaten Geräteschlüssels fest, die Sie zuvor generiert haben. Ersetzen Sie <your-certificate-folder> durch den Pfad zu dem Ordner, in dem Sie Ihre OpenSSL-Befehle ausgeführt haben.

   set X509_CERT_FILE=<your-certificate-folder>\certs\device-01-full-chain.cert.pem
   set X509_KEY_FILE=<your-certificate-folder>\private\device-01.key.pem
   

7. Sehen Sie sich den Code für provision_x509.py an. Wenn Sie nicht die Python-Version 3.7 oder höher verwenden, führen Sie die hier beschriebene Codeänderung durch, um asyncio.run(main()) zu ersetzen.

8. Führen Sie das Beispiel aus. Das Beispiel stellt eine Verbindung mit DPS her, wodurch das Gerät für einen IoT-Hub bereitgestellt wird. Nachdem das Gerät bereitgestellt wurde, sendet das Beispiel einige Testnachrichten an den IoT-Hub.

   python provision_x509.py
   

   Die Ausgabe sollte etwa folgendem Beispiel entsprechen:

   The complete registration result is
   device-01
   contoso-hub-2.azure-devices.net
   initialAssignment
   null
   Will send telemetry from the provisioned device
   sending message #1
   sending message #2
   sending message #3
   sending message #4
   sending message #5
   sending message #6
   sending message #7
   sending message #8
   sending message #9
   sending message #10
   done sending message #1
   done sending message #2
   done sending message #3
   done sending message #4
   done sending message #5
   done sending message #6
   done sending message #7
   done sending message #8
   done sending message #9
   done sending message #10
   

9. Aktualisieren Sie die Umgebungsvariablen für Ihr zweites Gerät (device-02) gemäß der folgenden Tabelle, und führen Sie das Beispiel erneut aus.

   Umgebungsvariable	Wert
   DPS_X509_REGISTRATION_ID	device-02
   X509_CERT_FILE	<your-certificate-folder>\certs\device-02-full-chain.cert.pem
   X509_KEY_FILE	<your-certificate-folder>\private\device-02.key.pem

In den folgenden Schritten verwenden Sie sowohl Ihre Windows-Eingabeaufforderung als auch Ihre Git Bash-Eingabeaufforderung.

1. Wählen Sie im Azure-Portal die Registerkarte Übersicht für Ihre Device Provisioning Service-Instanz.

2. Kopieren Sie den Wert von ID-Bereich.

   

3. Navigieren Sie in Ihrer Windows-Eingabeaufforderung zum Ordner des Beispielprojekts. Der angezeigte Pfad ist relativ zu dem Speicherort, in dem Sie das SDK geklont haben.

   cd .\azure-iot-sdk-java\provisioning\provisioning-device-client-samples\provisioning-X509-sample
   

4. Geben Sie im Beispielcode den Bereitstellungsdienst und die X.509-Identitätsinformationen ein. Diese Angaben werden während der Bereitstellung als Nachweis für das simulierte Gerät verwendet, bevor es registriert wird.

   1. Öffnen Sie die Datei .\src\main\java\samples\com\microsoft\azure\sdk\iot\ProvisioningX509Sample.java in Ihrem bevorzugten Text-Editor.

   2. Aktualisieren Sie die folgenden Werte. Verwenden Sie für idScope den ID-Bereich, den Sie zuvor kopiert haben. Verwenden Sie für den globalen Endpunkt den Wert für Globaler Geräteendpunkt. Dieser Endpunkt ist für alle DPS-Instanzen identisch (global.azure-devices-provisioning.net).

      private static final String idScope = "[Your ID scope here]";
      private static final String globalEndpoint = "[Your Provisioning Service Global Endpoint here]";
      

   3. Das Beispiel ist standardmäßig auf HTTPS als Transportprotokoll festgelegt. Wenn Sie das Protokoll ändern möchten, kommentieren Sie die folgende Zeile aus, und heben Sie die Auskommentierung der Zeile für das gewünschte Protokoll auf.

      private static final ProvisioningDeviceClientTransportProtocol PROVISIONING_DEVICE_CLIENT_TRANSPORT_PROTOCOL = ProvisioningDeviceClientTransportProtocol.HTTPS;
      

   4. Aktualisieren Sie den Wert der konstanten Zeichenfolge leafPublicPem mit dem Wert Ihres Gerätezertifikats device-01.cert.pem.

      Die Syntax des Zertifikattexts muss dem unten folgenden Muster (ohne zusätzliche Leerstellen oder Zeichen) entsprechen.

      private static final String leafPublicPem = "-----BEGIN CERTIFICATE-----\n"
      "MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n"
          ...
      "MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n"
      "-----END CERTIFICATE-----";        
      

      Das manuelle Aktualisieren dieses Zeichenfolgenwerts kann fehleranfällig sein. Zum Generieren der richtigen Syntax können Sie den folgenden Befehl kopieren und in Ihre Git Bash-Eingabeaufforderung einfügen. Drücken Sie dann die EINGABETASTE. Dieser Befehl generiert die Syntax für den Wert der Zeichenfolgenkonstante leafPublicPem und schreibt sie in die Ausgabe.

      sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' ./certs/device-01.cert.pem
      

      Kopieren Sie den ausgegebenen Zertifikattext für den konstanten Wert, und fügen Sie ihn ein.

   5. Aktualisieren Sie den Zeichenfolgenwert der Konstante leafPrivateKey mit dem unverschlüsselten privaten Schlüssel für Ihr Gerätezertifikat, unencrypted-device-key.pem.

      Die Syntax des Texts zum privaten Schlüssel muss dem folgenden Muster (ohne zusätzliche Leerstellen oder Zeichen) entsprechen.

      private static final String leafPrivateKey = "-----BEGIN PRIVATE KEY-----\n" +
      "MIIJJwIBAAKCAgEAtjvKQjIhp0EE1PoADL1rfF/W6v4vlAzOSifKSQsaPeebqg8U\n" +
          ...
      "X7fi9OZ26QpnkS5QjjPTYI/wwn0J9YAwNfKSlNeXTJDfJ+KpjXBcvaLxeBQbQhij\n" +
      "-----END PRIVATE KEY-----";
      

      Zum Generieren der richtigen Syntax können Sie den folgenden Befehl kopieren und in Ihre Git Bash-Eingabeaufforderung einfügen. Drücken Sie dann die EINGABETASTE. Dieser Befehl generiert die Syntax für den Wert der Zeichenfolgenkonstante leafPrivateKey und schreibt sie in die Ausgabe.

      sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' ./private/device-01.key.pem
      

      Kopieren Sie den ausgegebenen Text zum privaten Schlüssel für den konstanten Wert, und fügen Sie ihn ein.

   6. Fügen Sie die konstante Zeichenfolge rootPublicPem mit dem Wert Ihres Zertifikats der Stammzertifizierungsstelle azure-iot-test-only.root.ca.cert.pem hinzu. Sie können ihn direkt nach der Konstante leafPrivateKey hinzufügen.

      Die Syntax des Zertifikattexts muss dem unten folgenden Muster (ohne zusätzliche Leerstellen oder Zeichen) entsprechen.

      private static final String rootPublicPem = "-----BEGIN CERTIFICATE-----\n"
      "MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n"
          ...
      "MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n"
      "-----END CERTIFICATE-----";        
      

      Zum Generieren der richtigen Syntax können Sie den folgenden Befehl kopieren und in Ihre Git Bash-Eingabeaufforderung einfügen. Drücken Sie dann die EINGABETASTE. Dieser Befehl generiert die Syntax für den Wert der Zeichenfolgenkonstante rootPublicPem und schreibt sie in die Ausgabe.

      sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' ./certs/azure-iot-test-only.root.ca.cert.pem
      

      Kopieren Sie den ausgegebenen Zertifikattext für den konstanten Wert, und fügen Sie ihn ein.

   7. Fügen Sie die konstante Zeichenfolge intermediatePublicPem mit dem Wert Ihres Zertifikats der Zwischenzertifizierungsstelle azure-iot-test-only.intermediate.cert.pem hinzu. Sie können ihn direkt nach der vorherigen Konstante hinzufügen.

      Die Syntax des Zertifikattexts muss dem unten folgenden Muster (ohne zusätzliche Leerstellen oder Zeichen) entsprechen.

      private static final String intermediatePublicPem = "-----BEGIN CERTIFICATE-----\n"
      "MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n"
          ...
      "MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n"
      "-----END CERTIFICATE-----";        
      

      Zum Generieren der richtigen Syntax können Sie den folgenden Befehl kopieren und in Ihre Git Bash-Eingabeaufforderung einfügen. Drücken Sie dann die EINGABETASTE. Dieser Befehl generiert die Syntax für den Wert der Zeichenfolgenkonstante intermediatePublicPem und schreibt sie in die Ausgabe.

      sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' ./certs/azure-iot-test-only.intermediate.cert.pem
      

      Kopieren Sie den ausgegebenen Zertifikattext für den konstanten Wert, und fügen Sie ihn ein.

   8. Suchen Sie in der main-Methode die folgenden Zeilen:

      // For group enrollment uncomment this line
      //signerCertificatePemList.add("<Your Signer/intermediate Certificate Here>");
      

      Fügen Sie diese beiden Zeilen direkt darunter hinzu, um der Signaturkette die Zertifikate der Zwischen- und Stammzertifizierungsstelle hinzuzufügen. Ihre Signaturkette sollte die gesamte Zertifikatkette bis hin zu einem Zertifikat umfassen, das Sie mit DPS überprüft haben.

      signerCertificatePemList.add(intermediatePublicPem);
      signerCertificatePemList.add(rootPublicPem);
      

      Hinweis

      Die Reihenfolge, in der die Signaturzertifikate hinzugefügt werden, ist wichtig. Wird sie geändert, ist das Beispiel nicht erfolgreich.

   9. Speichern Sie die Änderungen.

5. Erstellen Sie das Beispiel, und wechseln Sie zum Ordner target.

   mvn clean install
   cd target
   

6. Der Build gibt die JAR-Datei im Ordner target mit folgendem Dateiformat aus: provisioning-x509-sample-{version}-with-deps.jar; Beispiel: provisioning-x509-sample-1.8.1-with-deps.jar. Führen Sie die JAR-Datei aus. Möglicherweise müssen Sie die Version im folgenden Befehl ersetzen.

   java -jar ./provisioning-x509-sample-1.8.1-with-deps.jar
   

   Das Beispiel stellt eine Verbindung mit DPS her, wodurch das Gerät für einen IoT-Hub bereitgestellt wird. Nachdem das Gerät bereitgestellt wurde, sendet das Beispiel einige Testnachrichten an den IoT-Hub.

   Starting...
   Beginning setup.
   WARNING: sun.reflect.Reflection.getCallerClass is not supported. This will impact performance.
   2022-10-21 10:41:20,476 DEBUG (main) [com.microsoft.azure.sdk.iot.provisioning.device.ProvisioningDeviceClient] - Initialized a ProvisioningDeviceClient instance using SDK version 2.0.2
   2022-10-21 10:41:20,479 DEBUG (main) [com.microsoft.azure.sdk.iot.provisioning.device.ProvisioningDeviceClient] - Starting provisioning thread...
   Waiting for Provisioning Service to register
   2022-10-21 10:41:20,482 INFO (global.azure-devices-provisioning.net-4f8279ac-CxnPendingConnectionId-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Opening the connection to device provisioning service...
   2022-10-21 10:41:20,652 INFO (global.azure-devices-provisioning.net-4f8279ac-Cxn4f8279ac-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Connection to device provisioning service opened successfully, sending initial device registration message
   2022-10-21 10:41:20,680 INFO (global.azure-devices-provisioning.net-4f8279ac-Cxn4f8279ac-azure-iot-sdk-RegisterTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.RegisterTask] - Authenticating with device provisioning service using x509 certificates
   2022-10-21 10:41:21,603 INFO (global.azure-devices-provisioning.net-4f8279ac-Cxn4f8279ac-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Waiting for device provisioning service to provision this device...
   2022-10-21 10:41:21,605 INFO (global.azure-devices-provisioning.net-4f8279ac-Cxn4f8279ac-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Current provisioning status: ASSIGNING
   2022-10-21 10:41:24,868 INFO (global.azure-devices-provisioning.net-4f8279ac-Cxn4f8279ac-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Device provisioning service assigned the device successfully
   IotHUb Uri : contoso-hub-2.azure-devices.net
   Device ID : device-01
   2022-10-21 10:41:30,514 INFO (main) [com.microsoft.azure.sdk.iot.device.transport.ExponentialBackoffWithJitter] - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
   2022-10-21 10:41:30,526 INFO (main) [com.microsoft.azure.sdk.iot.device.transport.ExponentialBackoffWithJitter] - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
   2022-10-21 10:41:30,533 DEBUG (main) [com.microsoft.azure.sdk.iot.device.DeviceClient] - Initialized a DeviceClient instance using SDK version 2.1.2
   2022-10-21 10:41:30,590 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.MqttIotHubConnection] - Opening MQTT connection...
   2022-10-21 10:41:30,625 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sending MQTT CONNECT packet...
   2022-10-21 10:41:31,452 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sent MQTT CONNECT packet was acknowledged
   2022-10-21 10:41:31,453 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sending MQTT SUBSCRIBE packet for topic devices/device-01/messages/devicebound/#
   2022-10-21 10:41:31,523 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sent MQTT SUBSCRIBE packet for topic devices/device-01/messages/devicebound/# was acknowledged
   2022-10-21 10:41:31,525 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.MqttIotHubConnection] - MQTT connection opened successfully
   2022-10-21 10:41:31,528 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - The connection to the IoT Hub has been established
   2022-10-21 10:41:31,531 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Updating transport status to new status CONNECTED with reason CONNECTION_OK
   2022-10-21 10:41:31,532 DEBUG (main) [com.microsoft.azure.sdk.iot.device.DeviceIO] - Starting worker threads
   2022-10-21 10:41:31,535 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Invoking connection status callbacks with new status details
   2022-10-21 10:41:31,536 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Client connection opened successfully
   2022-10-21 10:41:31,537 INFO (main) [com.microsoft.azure.sdk.iot.device.DeviceClient] - Device client opened successfully
   Sending message from device to IoT Hub...
   2022-10-21 10:41:31,539 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Message was queued to be sent later ( Message details: Correlation Id [aaaa0000-bb11-2222-33cc-444444dddddd] Message Id [aaaa0000-bb11-2222-33cc-444444dddddd] )
   Press any key to exit...
   2022-10-21 10:41:31,540 DEBUG (contoso-hub-2.azure-devices.net-device-01-d7c67552-Cxn0bd73809-420e-46fe-91ee-942520b775db-azure-iot-sdk-IotHubSendTask) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Sending message ( Message details: Correlation Id [aaaa0000-bb11-2222-33cc-444444dddddd] Message Id [aaaa0000-bb11-2222-33cc-444444dddddd] )
   2022-10-21 10:41:31,844 DEBUG (MQTT Call: device-01) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - IotHub message was acknowledged. Checking if there is record of sending this message ( Message details: Correlation Id [aaaa0000-bb11-2222-33cc-444444dddddd] Message Id [aaaa0000-bb11-2222-33cc-444444dddddd] )
   2022-10-21 10:41:31,846 DEBUG (contoso-hub-2.azure-devices.net-device-01-d7c67552-Cxn0bd73809-420e-46fe-91ee-942520b775db-azure-iot-sdk-IotHubSendTask) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Invoking the callback function for sent message, IoT Hub responded to message ( Message details: Correlation Id [aaaa0000-bb11-2222-33cc-444444dddddd] Message Id [aaaa0000-bb11-2222-33cc-444444dddddd] ) with status OK
   Message sent!
   

7. Aktualisieren Sie die Konstanten für Ihr zweites Gerät (device-02) gemäß der folgenden Tabelle, erstellen Sie das Beispiel neu, und führen Sie es erneut aus.

   Dauerhaft	Zu verwendende Datei
   leafPublicPem	./certs/device-02.cert.pem
   leafPrivateKey	./private/device-02.key.pem