Snabbstart: Etablera en enhet med symmetriska nycklar

I den här snabbstarten lär du dig att köra enhetsetableringskod på en Windows-utvecklingsdator för att ansluta den till en IoT Hub som en IoT-enhet. Du konfigurerar den här enheten så att den använder en autentisering med symmetrisk nyckel med en instans av enhetsetableringstjänsten och tilldelas till en IoT-hubb. Exempelkod från Azure IoT C SDK används för att etablera enheten. Enheten identifieras baserat på enskild registrering med etableringstjänstinstansen och tilldelas till en IoT-hubb.

Även om den här artikeln visar etablering med en enskild registrering kan du använda registreringsgrupper. Det finns några skillnader när du använder registreringsgrupper. Du måste till exempel använda en härledd enhetsnyckel med ett unikt registrerings-ID för enheten. Även om registreringsgrupper för symmetrisk nyckel inte är begränsade till äldre enheter finns det ett exempel för registreringsgrupper i avsnittet om hur du etablerar äldre enheter med symmetrisk nyckelattestering. Mer information finns i avsnittet om gruppregistreringar för symmetrisk nyckelattestering.

Om du inte är bekant med processen för automatisk etablering kan du läsa etableringsöversikten.

Se även till att slutföra stegen i Set up IoT Hub Device Provisioning Service with the Azure portal (Konfigurera IoT Hub-enhetsetableringstjänsten med Azure-portalen) innan du fortsätter med den här snabbstarten. Den här snabbstarten kräver att du redan har skapat en Device Provisioning Service-instans.

Den här artikeln riktar sig till en Windows-arbetsstation. Du kan dock utföra procedurerna i Linux. Ett Linux-exempel finns i informationen om att etablera för flera innehavare.

Om du inte har en Azure-prenumerationkan du skapa ett kostnads fritt konto innan du börjar.

Förutsättningar

Följande krav är för en Windows utvecklingsmiljö. För Linux eller macOS, se lämpligt avsnitt i Förbereda utvecklingsmiljön i SDK-dokumentationen.

Förbereda en utvecklingsmiljö för Azure IoT C SDK

I det här avsnittet förbereder du en utvecklingsmiljö som används för att skapa Azure IoT C SDK.

SDK:n innehåller etableringsexempelkoden för enheter. Den här koden försöker etableras under enhetens startsekvens.

  1. Ladda ned CMake-buildsystemet.

    Det är viktigt att förutsättningarna för Visual Studio (Visual Studio och arbetsbelastningen ”Desktop development with C++” (Skrivbordsutveckling med C++)) är installerade på datorn innan installationen av CMake påbörjas. När förutsättningarna är uppfyllda och nedladdningen har verifierats installerar du CMake-byggesystemet.

    Äldre versioner av CMake-byggsystemet kan inte generera lösningsfilen som används i den här artikeln. Se till att använda en nyare version av CMake.

  2. Klicka Taggar och leta reda på taggnamnet för den senaste versionen på sidan Version i Azure IoT C SDK.

  3. Öppna en kommandotolk eller Git Bash-gränssnittet. Kör följande kommandon för att klona den senaste versionen av Azure IoT C SDK GitHub lagringsplats. Använd taggen som du hittade i föregående steg som värde för -b parametern :

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

    Den här åtgärden kan förväntas ta flera minuter att slutföra.

  4. Skapa en cmake-underkatalog i rotkatalogen på git-lagringsplatsen och navigera till den mappen. Kör följande kommandon från azure-iot-sdk-c katalogen :

    mkdir cmake
    cd cmake
    
  5. Kör följande kommando som skapar en version av SDK:t som är specifik för plattformen i din utvecklingsklient. En Visual Studio lösning för enhetsetableringskoden genereras i cmake katalogen .

    cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON  ..
    

    Om cmake inte hittar din C++-kompilerare kan du få kompileringsfel när du kör kommandot ovan. Om det händer ska du försöka köra det här kommandot i kommandotolken i Visual Studio.

    När bygget är klart ser de sista utdataraderna ut ungefär som följande utdata:

    $ cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON  ..
    -- Building for: Visual Studio 15 2017
    -- Selecting Windows SDK version 10.0.16299.0 to target Windows 10.0.17134.
    -- The C compiler identification is MSVC 19.12.25835.0
    -- The CXX compiler identification is MSVC 19.12.25835.0
    
    ...
    
    -- Configuring done
    -- Generating done
    -- Build files have been written to: E:/IoT Testing/azure-iot-sdk-c/cmake
    

Skapa en post för enhetsregistrering i portalen

  1. Logga in på Azure Portal, välj knappen Alla resurser på den vänstra menyn och öppna device provisioning-tjänsten.

  2. Välj fliken Hantera registreringar och välj sedan knappen Lägg till enskild registrering högst upp.

  3. I panelen Lägg till registrering anger du följande information och trycker på knappen Spara.

    • Mekanism: välj Symmetrisk nyckel som identitetsattesterings mekanism.

    • Generera nycklar automatiskt: Markera den här kryssrutan.

    • Registrerings-ID: Ange ett registrerings-ID för att identifiera registreringen. Använd endast alfanumeriska gemener och bindestreck (”-”). Till exempel symm-key-device-007.

    • Enhets-ID för IoT Hub: Ange en enhetsidentifierare. Till exempel device-007.

      Lägga till en enskild registrering för symmetrisk nyckelattestering i portalen

  4. När du har sparat registreringen genereras primärnyckeln och den sekundära nyckeln och läggs till i registreringsposten. Registreringen av din symmetriska nyckel visas som symm-key-device-007 under kolumnen Registrerings-ID på fliken Enskilda registreringar.

    Öppna registreringen och kopiera värdet för din genererade primärnyckel.

Kör etableringskoden för enheten

I det här avsnittet uppdaterar du exempelkoden för att skicka enhetens startsekvens till din instans av enhetsetableringstjänsten. Den här startsekvensen medför att enheten identifieras och tilldelas till en IoT-hubb som är länkad till instansen av enhetsetableringstjänsten.

  1. I Azure Portal väljer du fliken Översikt för enhetsetableringstjänsten och noterar värdet för ID-omfång.

    Extrahera information om enhetsetableringstjänstens slutpunkt från bladet på portalen

  2. I Visual Studio öppnar du lösningsfilen azure_iot_sdks.sln som har genererats genom att köra CMake. Lösningsfilen bör vara på följande plats:

    \azure-iot-sdk-c\cmake\azure_iot_sdks.sln
    

    Om filen inte genererades i cmake-katalogen kontrollerar du att du har använt en ny version av CMake-buildsystemet.

  3. I fönstret Solution Explorer i Visual Studio går du till mappen Provision (Etablera)_Exempel. Expandera exempelprojektet som heter prov_dev_client_sample. Expandera Källfiler och öppna prov_dev_client_sample.c.

  4. Hitta konstanten id_scope och ersätt värdet med ditt värde för ID-omfång som du kopierade tidigare.

    static const char* id_scope = "0ne00002193";
    
  5. Hitta definitionen för funktionen main() i samma fil. Kontrollera att variabeln hsm_type är inställd på SECURE_DEVICE_TYPE_SYMMETRIC_KEY enligt nedan:

    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. Leta reda på prov_dev_set_symmetric_key_info() anropet till i prov dev client _ _ _ sample.c som har kommenterats bort.

    // Set the symmetric key if using they auth type
    //prov_dev_set_symmetric_key_info("<symm_registration_id>", "<symmetric_Key>");
    

    Avkommentera funktionsanropet och ersätt platshållarvärdena (inklusive hakparenteserna) med ditt registrerings-ID och primärnyckelvärdena.

    // Set the symmetric key if using they auth type
    prov_dev_set_symmetric_key_info("symm-key-device-007", "your primary key here");
    

    Spara filen.

  7. Högerklicka på projektet prov_dev_client_sample och välj Set as Startup Project (Ange som startprojekt).

  8. På Visual Studio väljer du Felsök > Starta utan felsökning för att köra lösningen. I kommandotolken för att återskapa projektet väljer du Ja för att återskapa projektet innan du kör det.

    Följande utdata är ett exempel på när enheten har anslutit till etableringstjänstinstansen som ska tilldelas till en IoT-hubb:

    Provisioning API Version: 1.2.8
    
    Registering Device
    
    Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
    Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
    Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
    
    Registration Information received from service: 
    test-docs-hub.azure-devices.net, deviceId: device-007    
    Press enter key to exit:
    
  9. I portalen går du till den IoT-hubb som din enhet tilldelades till och väljer fliken IoT-enheter. Vid lyckad etablering av enheten till hubben visas dess enhets-ID på bladet IoT-enheter med STATUS som aktiverad. Du kan behöva trycka på knappen Uppdatera längst upp.

    Enheten är registrerad på IoT-hubben

Rensa resurser

Om du planerar att fortsätta arbeta med och utforska enhetsklientexempel ska du inte rensa resurserna som skapades i den här snabbstarten. Om du inte planerar att fortsätta kan du använda följande steg för att ta bort alla resurser som har skapats i den här snabbstarten.

  1. Stäng utdatafönstret för enhetsklientexemplet på datorn.
  2. På den vänstra menyn i Azure Portal väljer du Alla resurser och sedan din enhetsetableringstjänst. Öppna Hantera registreringar för din tjänst och välj sedan fliken Enskilda registreringar. Markera kryssrutan bredvid REGISTRERINGS-ID för den enhet som du har registrerat i den här snabbstarten och tryck på knappen Ta bort längst upp i fönstret.
  3. På den vänstra menyn i den Azure Portal väljer du Alla resurser och sedan din IoT-hubb. Öppna IoT-enheter för din hubb, markera kryssrutan bredvid ENHETS-ID för den enhet som du registrerade i den här snabbstarten och tryck sedan på knappen Ta bort längst upp i fönstret.

Nästa steg

I den här snabbstarten körde du enhetsetableringskoden på Windows datorn. Enheten autentiserades och etablerades på din IoT-hubb med hjälp av en symmetrisk nyckel. Om du vill lära dig hur du etablerar en X.509-certifikatenhet fortsätter du till snabbstarten för X.509-enheter.