Condividi tramite

Creare un gruppo di registrazione del servizio Device Provisioning a livello di codice per l'attestazione del certificato X.509

  • Articolo

Questo articolo illustra come creare un gruppo di registrazioni a livello di codice che usa certificati X.509 ca intermedi o radice. Il gruppo di registrazione viene creato usando l'SDK del servizio DPS hub IoT di Azure e un'applicazione di esempio. Un gruppo di registrazione controlla l'accesso al servizio di provisioning per i dispositivi che condividono un certificato di firma comune nella rispettiva catena di certificati. Per altre informazioni, vedere Usare certificati X.509 con DPS. Per altre informazioni sull'uso di un'infrastruttura a chiave pubblica (PKI, Public Key Infrastructure) basata su certificati X.509 con l'hub IoT di Azure e il servizio Device Provisioning, vedere Panoramica della sicurezza dei certificati della CA X.509.

Prerequisiti

  • Installare la versione più recente di Git. Assicurarsi che Git venga aggiunto alle variabili di ambiente accessibili alla finestra di comando. Vedere Strumenti client Git di Software Freedom Conservancy per la versione più recente degli strumenti da installare, che include Git Bash, l'app da riga di git comando che è possibile usare per interagire con il repository Git locale.

Nota

I passaggi qui illustrati funzionano su computer sia Windows che Linux, ma questo articolo usa un computer di sviluppo Windows.

Creare certificati di test

I gruppi di registrazioni che usano l'attestazione del certificato X.509 possono essere configurati per l'uso di un certificato CA radice o di un certificato intermedio. Il caso più comune consiste nel configurare il gruppo di registrazioni con un certificato intermedio. L'uso di un certificato intermedio offre maggiore flessibilità perché più certificati intermedi possono essere generati o revocati dallo stesso certificato CA radice.

Per questo articolo è necessario un file di certificato CA radice, un file di certificato CA intermedio o entrambi in formato pem o .cer . Un file contiene la parte pubblica del certificato X.509 della CA radice e l'altro contiene la parte pubblica del certificato X.509 intermedio della CA.

Se si dispone già di un file CA radice e/o di un file CA intermedio, è possibile continuare a aggiungere e verificare il certificato CA radice o intermedio.

Se non si dispone di un file CA radice e/o di un file CA intermedio, seguire la procedura descritta in Creare una catena di certificati X.509 per crearli. È possibile arrestarsi dopo aver completato i passaggi descritti in Creare il certificato CA intermedio perché non sono necessari certificati del dispositivo per completare i passaggi descritti in questo articolo. Al termine, sono disponibili due file di certificato X.509: ./certs/azure-iot-test-only.root.ca.cert.pem e ./certs/azure-iot-test-only.intermediate.cert.pem.

Aggiungere e verificare il certificato ca radice o intermedio

I dispositivi di cui viene effettuato il provisioning tramite un gruppo di registrazioni usando certificati X.509, presentano l'intera catena di certificati quando eseguono l'autenticazione con DPS. Per poter convalidare la catena di certificati, il certificato radice o intermedio configurato in un gruppo di registrazioni deve essere un certificato verificato o deve essere eseguito il rollup di un certificato verificato nella catena di certificati presentato da un dispositivo quando esegue l'autenticazione con il servizio.

Per questo articolo, presupponendo che sia presente un certificato CA radice che un certificato CA intermedio firmato dalla CA radice:

  • Se si prevede di creare il gruppo di registrazione con il certificato CA radice, è necessario caricare e verificare il certificato CA radice.

  • Se si prevede di creare il gruppo di registrazione con il certificato CA intermedio, è possibile caricare e verificare il certificato CA radice o il certificato ca intermedio. Se nella catena di certificati sono presenti più certificati CA intermedi, è possibile, in alternativa, caricare e verificare qualsiasi certificato intermedio compreso tra il certificato ca radice e il certificato intermedio con cui si crea il gruppo di registrazione.

Per aggiungere e verificare il certificato ca radice o intermedio al servizio Device Provisioning:

  1. Accedere al portale di Azure.

  2. Nel menu a sinistra o nella pagina del portale selezionare Tutte le risorse.

  3. Selezionare il servizio Device Provisioning.

  4. Nel menu Impostazioni selezionare Certificati.

  5. Nel menu in alto selezionare + Aggiungi:.

  6. Immettere un nome per il certificato CA radice o intermedio e caricare il file con estensione pem o .cer .

  7. Selezionare Imposta stato certificato da verificare al caricamento.

    Screenshot che mostra l'aggiunta del certificato CA radice a un'istanza del servizio Device Provisioning.

  8. Seleziona Salva.

Ottenere la stringa di connessione del servizio di provisioning

Per l'esempio in questo articolo, è necessario il stringa di connessione per il servizio di provisioning. Per recuperarlo, seguire questa procedura.

  1. Accedere al portale di Azure.

  2. Nel menu a sinistra o nella pagina del portale selezionare Tutte le risorse.

  3. Selezionare il servizio Device Provisioning.

  4. Nel menu Impostazioni selezionare Criteri di accesso condiviso.

  5. Selezionare i criteri di accesso da usare.

  6. Nel pannello Criteri di accesso copiare e salvare la chiave primaria stringa di connessione.

    Screenshot che mostra il percorso del servizio di provisioning stringa di connessione nel portale.

Creare l'esempio di gruppo di registrazioni

Questa sezione illustra come creare un'applicazione console .NET Core che aggiunge un gruppo di registrazione al servizio di provisioning.

  1. Aprire un prompt dei comandi di Windows e passare a una cartella in cui si vuole creare l'app.

  2. Per creare un progetto console, eseguire il comando seguente:

    dotnet new console --framework net6.0 --use-program-main

  3. Per aggiungere un riferimento all'SDK del servizio DPS, eseguire il comando seguente:

    dotnet add package Microsoft.Azure.Devices.Provisioning.Service

    Questo passaggio scarica, installa e aggiunge un riferimento al pacchetto NuGet del client del servizio Device Provisioning IoT di Azure e alle relative dipendenze. Questo pacchetto include i file binari per .NET Service SDK.

  4. Aprire Program.cs file in un editor.

  5. Sostituire l'istruzione dello spazio dei nomi all'inizio del file con la riga seguente:

    namespace CreateEnrollmentGroup;

  6. Aggiungere le istruzioni seguenti using all'inizio del file sopra l'istruzione namespace :

    using System.Security.Cryptography.X509Certificates;
using System.Threading.Tasks;
using Microsoft.Azure.Devices.Provisioning.Service;

  7. Aggiungere i campi seguenti alla Program classe e apportare le modifiche indicate.

    private static string ProvisioningConnectionString = "{ProvisioningServiceConnectionString}";
private static string EnrollmentGroupId = "enrollmentgrouptest";
private static string X509RootCertPath = @"{Path to a .cer or .pem file for a verified root CA or intermediate CA X.509 certificate}";

    • Sostituire il ProvisioningServiceConnectionString valore segnaposto con il stringa di connessione del servizio di provisioning copiato nella sezione precedente.

    • Sostituire il valore segnaposto di X509RootCertPath con il percorso di un file con estensione pem o cer. Questo file rappresenta la parte pubblica di un certificato X.509 ca radice caricato e verificato in precedenza con il servizio di provisioning oppure un certificato intermedio che è stato caricato e verificato oppure che nella catena di firma è stato caricato e verificato un certificato.

    • Facoltativamente, è possibile modificare il valore di EnrollmentGroupId. La stringa può contenere solo caratteri minuscoli e trattini.

    Importante

    Nel codice di produzione occorre tenere presenti le considerazioni seguenti sulla sicurezza:

    • L'impostazione della stringa di connessione come hardcoded per l'amministratore del servizio di provisioning non è conforme alle procedure consigliate per la sicurezza. La stringa di connessione deve essere tuttavia conservata in modo sicuro, ad esempio in un file di configurazione sicuro o nel Registro di sistema.
    • Assicurarsi di caricare solo la parte pubblica del certificato di firma. Non caricare mai nel servizio di provisioning i file PFX (PKCS12) o PEM contenenti le chiavi private.

  8. Aggiungere il seguente metodo alla classe Program. Questo codice crea una EnrollmentGroup voce e quindi chiama il ProvisioningServiceClient.CreateOrUpdateEnrollmentGroupAsync metodo per aggiungere il gruppo di registrazione al servizio di provisioning.

    public static async Task RunSample()
{
    Console.WriteLine("Starting sample...");

    using (ProvisioningServiceClient provisioningServiceClient =
            ProvisioningServiceClient.CreateFromConnectionString(ProvisioningConnectionString))
    {
        #region Create a new enrollmentGroup config
        Console.WriteLine("\nCreating a new enrollmentGroup...");
        var certificate = new X509Certificate2(X509RootCertPath);
        Attestation attestation = X509Attestation.CreateFromRootCertificates(certificate);
        EnrollmentGroup enrollmentGroup =
                new EnrollmentGroup(
                        EnrollmentGroupId,
                        attestation)
                {
                    ProvisioningStatus = ProvisioningStatus.Enabled
                };
        Console.WriteLine(enrollmentGroup);
        #endregion

        #region Create the enrollmentGroup
        Console.WriteLine("\nAdding new enrollmentGroup...");
        EnrollmentGroup enrollmentGroupResult =
            await provisioningServiceClient.CreateOrUpdateEnrollmentGroupAsync(enrollmentGroup).ConfigureAwait(false);
        Console.WriteLine("\nEnrollmentGroup created with success.");
        Console.WriteLine(enrollmentGroupResult);
        #endregion

    }
}

  9. Sostituire infine il metodo Main con le righe seguenti:

    static async Task Main(string[] args)
{
    await RunSample();
    Console.WriteLine("\nHit <Enter> to exit ...");
    Console.ReadLine();
}

  10. Salva le modifiche.

Questa sezione illustra come creare uno script Node.js che aggiunge un gruppo di registrazione al servizio di provisioning.

  1. In una finestra di comando della cartella di lavoro eseguire:

    npm install azure-iot-provisioning-service

    Questo passaggio scarica, installa e aggiunge un riferimento al pacchetto client del servizio Dps IoT di Azure e alle relative dipendenze. Questo pacchetto include i file binari per l'SDK del servizio Node.js.

  2. Con un editor di testo creare un file create_enrollment_group.js nella cartella di lavoro. Aggiungere il codice seguente al file e salvare:

        'use strict';
    var fs = require('fs');

    var provisioningServiceClient = require('azure-iot-provisioning-service').ProvisioningServiceClient;

    var serviceClient = provisioningServiceClient.fromConnectionString(process.argv[2]);

    var enrollment = {
      enrollmentGroupId: 'first',
      attestation: {
        type: 'x509',
        x509: {
          signingCertificates: {
            primary: {
              certificate: fs.readFileSync(process.argv[3], 'utf-8').toString()
            }
          }
        }
      },
      provisioningStatus: 'disabled'
    };

    serviceClient.createOrUpdateEnrollmentGroup(enrollment, function(err, enrollmentResponse) {
      if (err) {
        console.log('error creating the group enrollment: ' + err);
      } else {
        console.log("enrollment record returned: " + JSON.stringify(enrollmentResponse, null, 2));
        enrollmentResponse.provisioningStatus = 'enabled';
        serviceClient.createOrUpdateEnrollmentGroup(enrollmentResponse, function(err, enrollmentResponse) {
          if (err) {
            console.log('error updating the group enrollment: ' + err);
          } else {
            console.log("updated enrollment record returned: " + JSON.stringify(enrollmentResponse, null, 2));
          }
        });
      }
    });

  1. Aprire un prompt dei comandi di Windows.

  2. Clonare il repository GitHub per l'esempio di codice di registrazione del dispositivo usando Java Service SDK:

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

  3. Dal percorso in cui è stato scaricato il repository, passare alla cartella di esempio:

    cd azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-group-sample

  4. Aprire il file /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentGroupSample.java in un editor di propria scelta.

  5. Sostituire [Provisioning Connection String] con il stringa di connessione copiato in Ottenere il stringa di connessione per il servizio di provisioning.

  6. Sostituire la PUBLIC_KEY_CERTIFICATE_STRING stringa costante con il valore del file di certificato .pem ca radice o intermedio. Questo file rappresenta la parte pubblica di un certificato X.509 ca radice caricato e verificato in precedenza con il servizio di provisioning oppure un certificato intermedio che è stato caricato e verificato oppure che nella catena di firma è stato caricato e verificato un certificato.

    La sintassi del testo del certificato deve seguire il modello seguente senza spazi o caratteri aggiuntivi.

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

    L'aggiornamento manuale di questo valore stringa può essere soggetto a errori. Per generare la sintassi corretta, è possibile copiare e incollare il comando seguente in un prompt di Git Bash , sostituire your-cert.pem con il percorso del file del certificato e premere INVIO. Questo comando genera la sintassi per il PUBLIC_KEY_CERTIFICATE_STRING valore costante stringa e la scrive nell'output.

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

    Copiare e incollare il testo del certificato di output per il valore costante.

    Importante

    Nel codice di produzione occorre tenere presenti le considerazioni seguenti sulla sicurezza:

    • L'impostazione della stringa di connessione come hardcoded per l'amministratore del servizio di provisioning non è conforme alle procedure consigliate per la sicurezza. La stringa di connessione deve essere tuttavia conservata in modo sicuro, ad esempio in un file di configurazione sicuro o nel Registro di sistema.
    • Assicurarsi di caricare solo la parte pubblica del certificato di firma. Non caricare mai nel servizio di provisioning i file PFX (PKCS12) o PEM contenenti le chiavi private.

  7. L'esempio consente di impostare un hub IoT nel gruppo di registrazione in cui effettuare il provisioning del dispositivo. Deve trattarsi di un hub IoT collegato in precedenza al servizio di provisioning. Per questo articolo, è possibile scegliere dps tra gli hub collegati in base ai criteri di allocazione predefiniti, distribuzione ponderata in modo uniforme. Impostare come commento l'istruzione seguente nel file :

    enrollmentGroup.setIotHubHostName(IOTHUB_HOST_NAME);                // Optional parameter.

  8. Il codice di esempio crea, aggiorna, esegue query ed elimina un gruppo di registrazioni per i dispositivi X.509. Per verificare la corretta creazione del gruppo di registrazione in portale di Azure, impostare come commento le righe di codice seguenti vicino alla fine del file:

    // ************************************** Delete info of enrollmentGroup ***************************************
System.out.println("\nDelete the enrollmentGroup...");
provisioningServiceClient.deleteEnrollmentGroup(enrollmentGroupId);

  9. Salvare il file ServiceEnrollmentGroupSample.java .

Eseguire l'esempio di gruppo di registrazioni

  1. Eseguire l'esempio:

    dotnet run

  2. Al termine della creazione, nella finestra di comando vengono visualizzate le proprietà del nuovo gruppo di registrazione.

  1. Eseguire il comando seguente nel prompt dei comandi. Includere le virgolette relative agli argomenti del comando e sostituire <connection string> con stringa di connessione copiate nella sezione precedente e <certificate .pem file> con il percorso del file del certificato.pem. Questo file rappresenta la parte pubblica di un certificato X.509 ca radice caricato e verificato in precedenza con il servizio di provisioning oppure un certificato intermedio che è stato caricato e verificato oppure che nella catena di firma è stato caricato e verificato un certificato.

    node create_enrollment_group.js "<connection string>" "<certificate .pem file>"

  2. Al termine della creazione, nella finestra di comando vengono visualizzate le proprietà del nuovo gruppo di registrazione.

  1. Dalla cartella azure-iot-sdk-java\provisioning\provisioning-service-client-samples\service-enrollment-group-sample nel prompt dei comandi eseguire il comando seguente per compilare l'esempio:

    mvn install -DskipTests

    Questo comando scarica il pacchetto Maven del servizio Dps di Azure IoT nel computer e compila l'esempio. Questo pacchetto include i file binari per Java Service SDK.

  2. Passare alla cartella di destinazione ed eseguire l'esempio. La compilazione nel passaggio precedente restituisce .jar file nella cartella di destinazione con il formato di file seguente: provisioning-x509-sample-{version}-with-deps.jar; ad esempio: provisioning-x509-sample-1.8.1-with-deps.jar. Potrebbe essere necessario sostituire la versione nel comando seguente.

    cd target
java -jar ./service-enrollment-group-sample-1.8.1-with-deps.jar

  3. Al termine della creazione, nella finestra di comando vengono visualizzate le proprietà del nuovo gruppo di registrazione.

Per verificare che il gruppo di registrazione sia stato creato:

  1. Nella portale di Azure passare all'istanza del servizio Device Provisioning.

  2. Nel menu Impostazioni selezionare Gestisci registrazioni.

  3. Selezionare la scheda Gruppi di registrazione. Verrà visualizzata una nuova voce di registrazione corrispondente all'ID del gruppo di registrazione usato nell'esempio.

Screenshot che mostra il gruppo di registrazione appena creato nel portale.

Screenshot che mostra il gruppo di registrazione appena creato nel portale.

Screenshot che mostra il gruppo di registrazione appena creato nel portale.

Pulire le risorse

Se si prevede di esplorare le esercitazioni sul servizio Device Provisioning hub IoT di Azure, non pulire le risorse create in questo articolo. In caso contrario, seguire questa procedura per eliminare tutte le risorse create da questo articolo.

  1. Chiudere la finestra di output di esempio nel computer.

  2. Nel menu a sinistra nella portale di Azure selezionare Tutte le risorse.

  3. Selezionare il servizio Device Provisioning.

  4. Nel menu a sinistra in Impostazioni selezionare Gestisci registrazioni.

  5. Selezionare la scheda Gruppi di registrazione.

  6. Selezionare la casella di controllo accanto al nome del gruppo di registrazione creato in questo articolo.

  7. Nella parte superiore della pagina selezionare Elimina.

  8. Dal servizio Device Provisioning nella portale di Azure selezionare Certificati in Impostazioni nel menu a sinistra.

  9. Selezionare il certificato caricato per questo articolo.

  10. Nella parte superiore dei dettagli del certificato selezionare Elimina.

Strumenti per i certificati

Azure IoT C SDK include script che consentono di creare e gestire i certificati. Per altre informazioni, vedere Gestione dei certificati della CA di test per esempi ed esercitazioni.

Azure IoT Node.js SDK include script che consentono di creare e gestire i certificati. Per altre informazioni, vedere Strumenti per Azure IoT Device Provisioning Device SDK per Node.js.

È anche possibile usare gli strumenti disponibili in Azure IoT C SDK. Per altre informazioni, vedere Gestione dei certificati della CA di test per esempi ed esercitazioni.

Azure IoT Java SDK contiene strumenti di test che consentono di creare e gestire i certificati. Per altre informazioni, vedere Generatore di certificati X509 con l'emulatore DICE.

Passaggi successivi

In questo articolo è stato creato un gruppo di registrazione per un certificato CA intermedio o radice X.509 usando il servizio Device Provisioning hub IoT di Azure. Per altre informazioni, vedere i collegamenti seguenti: