セキュアストレージ用のカスタム証明書ハンドラーを作成する

マネージド統合ハブをオンボーディングするときは、デバイス証明書の管理が不可欠です。証明書はデフォルトでファイルシステムに保存されていますが、セキュリティを強化し、柔軟な認証情報管理を行うためのカスタム証明書ハンドラーを作成できます。

マネージド統合エンドデバイス SDK は、共有オブジェクト (.so) ライブラリとして実装できるストレージインターフェイスを保護するための証明書ハンドラーを提供します。安全なストレージ実装を構築して証明書を読み書きし、実行時にライブラリファイルを HubOnboarding プロセスにリンクします。

API 定義とコンポーネント

次のsecure_storage_cert_handler_interface.hppファイルを確認して、実装の API コンポーネントと要件を理解します。

API 定義

secure_storage_cert_hander_interface.hpp の内容


/* 
    * Copyright 2024 Amazon.com, Inc. or its affiliates. All rights reserved. 
    *
    * AMAZON PROPRIETARY/CONFIDENTIAL 
    *
    * You may not use this file except in compliance with the terms and
    * conditions set forth in the accompanying LICENSE.txt file.
    *
    * THESE MATERIALS ARE PROVIDED ON AN "AS IS" BASIS. AMAZON SPECIFICALLY 
    * DISCLAIMS, WITH RESPECT TO THESE MATERIALS, ALL WARRANTIES, EXPRESS, 
    * IMPLIED, OR STATUTORY, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, 
    * FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. 
    */ 
    #ifndef SECURE_STORAGE_CERT_HANDLER_INTERFACE_HPP
    #define SECURE_STORAGE_CERT_HANDLER_INTERFACE_HPP 
    
    #include <iostream>
    #include <memory>
    
    namespace IoTManagedIntegrationsDevice { 
    namespace CertHandler {
    /**
     * @enum CERT_TYPE_T
     * @brief enumeration defining certificate types. 
     */ 
     typedef enum { CLAIM = 0, DHA = 1, PERMANENT = 2 } CERT_TYPE_T;
     class SecureStorageCertHandlerInterface {
      public:
       /** 
        * @brief Read certificate and private key value of a particular certificate
        * type from secure storage.
        */ 
        virtual bool read_cert_and_private_key(const CERT_TYPE_T cert_type, 
                                              std::string &cert_value, 
                                              std::string &private_key_value) = 0; 
        /** 
          * @brief Write permanent certificate and private key value to secure storage.
          */
        virtual bool write_permanent_cert_and_private_key(
            std::string_view cert_value, std::string_view private_key_value) = 0; 
        };
        std::shared_ptr<SecureStorageCertHandlerInterface> createSecureStorageCertHandler();
    } //namespace CertHandler
    } //namespace IoTManagedIntegrationsDevice
  
    #endif //SECURE_STORAGE_CERT_HANDLER_INTERFACE_HPP

主要コンポーネント

CERT_TYPE_T - ハブ上のさまざまなタイプの証明書。
- CLAIM - クレーム証明書は、元々ハブにあり、永続的な証明書と交換されます。
- DHA - 現時点では未使用です。
- PERMANENT - マネージド統合エンドポイントに接続するための永続的な証明書。
read_cert_and_private_key - (FUNCTION TO BE IMPLEMENTED) の証明書とキーの値をリファレンス入力に読み取ります。この関数は、CLAIM 証明書と PERMANENT 証明書の両方を読み取ることができ、上記の証明書タイプによって区別される必要があります。
write_permanent_cert_and_private_key - (FUNCTION TO BE IMPLEMENTED) は、永続的な証明書とキーの値を目的の場所に書き込みます。

ビルド例

内部実装ヘッダーをパブリックインターフェイス (secure_storage_cert_handler_interface.hpp) から分離して、クリーンなプロジェクト構造を維持します。この分離により、証明書ハンドラーを構築しながら、パブリックコンポーネントとプライベートコンポーネントを管理できます。

注記

パブリックsecure_storage_cert_handler_interface.hppとして宣言します。

トピック

プロジェクト構造
インターフェイスを継承する
実装
CMakeList.txt

プロジェクト構造

インターフェイスを継承する

インターフェイスを継承する具体的なクラスを作成します。このヘッダーファイルやその他のファイルを別のディレクトリに非表示にして、プライベートヘッダーとパブリックヘッダーをビルド時に簡単に区別できるようにします。


#ifndef IOTMANAGEDINTEGRATIONSDEVICE_SDK_STUB_SECURE_STORAGE_CERT_HANDLER_HPP
  #define IOTMANAGEDINTEGRATIONSDEVICE_SDK_STUB_SECURE_STORAGE_CERT_HANDLER_HPP 
  
  #include "secure_storage_cert_handler_interface.hpp" 
  
  namespace IoTManagedIntegrationsDevice::CertHandler { 
    class StubSecureStorageCertHandler : public SecureStorageCertHandlerInterface { 
      public:
        StubSecureStorageCertHandler() = default; 
        
        bool read_cert_and_private_key(const CERT_TYPE_T cert_type,
                                      std::string &cert_value, 
                                      std::string &private_key_value) override; 
                                      
        bool write_permanent_cert_and_private_key(
            std::string_view cert_value, std::string_view private_key_value) override; 
            /*
            * any other resource for function you might need 
            */
            
            
          }; 
      } 
    #endif //IOTMANAGEDINTEGRATIONSDEVICE_SDK_STUB_SECURE_STORAGE_CERT_HANDLER_HPP

実装

上記で定義したストレージクラスを実装しますsrc/stub_secure_storage_cert_handler.cpp。


/* 
  * Copyright 2024 Amazon.com, Inc. or its affiliates. All rights reserved. 
  * 
  * AMAZON PROPRIETARY/CONFIDENTIAL 
  *
  * You may not use this file except in compliance with the terms and
  * conditions set forth in the accompanying LICENSE.txt file. 
  * 
  * THESE MATERIALS ARE PROVIDED ON AN "AS IS" BASIS. AMAZON SPECIFICALLY 
  * DISCLAIMS, WITH RESPECT TO THESE MATERIALS, ALL WARRANTIES, EXPRESS, 
  * IMPLIED, OR STATUTORY, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, 
  * FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. 
  */

  #include "stub_secure_storage_cert_handler.hpp" 
  
  using namespace IoTManagedIntegrationsDevice::CertHandler;
  
  bool StubSecureStorageCertHandler::write_permanent_cert_and_private_key( 
              std::string_view cert_value, std::string_view private_key_value) { 
            // TODO: implement write function 
            return true;
  }
  
  bool StubSecureStorageCertHandler::read_cert_and_private_key(const CERT_TYPE_T cert_type, 
                                                          std::string &cert_value,
                                                          std::string &private_key_value) {
          std::cout<<"Using Stub Secure Storage Cert Handler, returning dummy values";
          cert_value = "StubCertVal"; 
          private_key_value = "StubKeyVal"; 
          // TODO: implement read function 
          return true;
  }

インターフェイスで定義されたファクトリ関数を実装しますsrc/secure_storage_cert_handler.cpp。


#include "stub_secure_storage_cert_handler.hpp"
        
        std::shared_ptr<IoTManagedIntegrationsDevice::CertHandler::SecureStorageCertHandlerInterface>
        IoTManagedIntegrationsDevice::CertHandler::createSecureStorageCertHandler() { 
          // TODO: replace with your implementation 
        return std::make_shared<IoTManagedIntegrationsDevice::CertHandler::StubSecureStorageCertHandler>(); 
      }

CMakeList.txt


#project name must stay the same
      project(SecureStorageCertHandler) 
      
      # Public Header files. The interface definition must be in top level with exactly the same name 
      #ie. Not in anotherDir/secure_storage_cert_hander_interface.hpp 
      set(PUBLIC_HEADERS
                ${PROJECT_SOURCE_DIR}/include 
      )
      
      # private implementation headers.
      set(PRIVATE_HEADERS 
                ${PROJECT_SOURCE_DIR}/internal/stub 
      )
      
      #set all sources 
      set(SOURCES 
                ${PROJECT_SOURCE_DIR}/src/secure_storage_cert_handler.cpp 
                ${PROJECT_SOURCE_DIR}/src/stub_secure_storage_cert_handler.cpp 
        )
        
      # Create the shared library
      add_library(${PROJECT_NAME} SHARED ${SOURCES})
      target_include_directories( 
                ${PROJECT_NAME} 
                PUBLIC
                    ${PUBLIC_HEADERS} 
                PRIVATE 
                    ${PRIVATE_HEADERS}
      )
      
      # Set the library output location. Location can be customized but version must stay the same
      set_target_properties(${PROJECT_NAME} PROPERTIES 
                LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/../lib 
                VERSION 1.0 
                SOVERSION 1
      )
      
      # Install rules
      install(TARGETS ${PROJECT_NAME} 
                LIBRARY DESTINATION lib 
                ARCHIVE DESTINATION lib 
      )
      
      install(FILES ${HEADERS} 
                DESTINATION include/SecureStorageCertHandler
      )

使用方法

コンパイル後、libSecureStorageCertHandler.so共有オブジェクトライブラリファイルとそれに関連するシンボリックリンクが作成されます。ライブラリファイルとシンボリックリンクの両方を、HubOnboarding バイナリで想定されるライブラリの場所にコピーします。

トピック

主な考慮事項
安全なストレージを使用する

主な考慮事項

ユーザーアカウントに HubOnboarding バイナリとlibSecureStorageCertHandler.soライブラリの両方に対する読み取りおよび書き込みアクセス許可があることを確認します。
を唯一のパブリックヘッダーファイルsecure_storage_cert_handler_interface.hppとして保持します。他のすべてのヘッダーファイルは、プライベート実装に残ります。
共有オブジェクトライブラリ名を確認します。の構築中にlibSecureStorageCertHandler.so、HubOnboarding でなどのファイル名に特定のバージョンが必要になる場合がありますlibSecureStorageCertHandler.so.1.0。ldd コマンドを使用してライブラリの依存関係を確認し、必要に応じてシンボリックリンクを作成します。
共有ライブラリの実装に外部依存関係がある場合は、HubOnboarding がアクセスできるディレクトリに/usr/lib or the iotmi_common保存します。

安全なストレージを使用する

iot_claim_cert_path との両方iot_claim_pk_pathをに設定して、 iotmi_config.json ファイルを更新しますSECURE_STORAGE。


{
  "ro": { 
    "iot_provisioning_method": "FLEET_PROVISIONING", 
    "iot_claim_cert_path": "SECURE_STORAGE",
    "iot_claim_pk_path": "SECURE_STORAGE", 
    "fp_template_name": "device-integration-example",
    "iot_endpoint_url": "[ACCOUNT-PREFIX]-ats.iot.AWS-REGION.amazonaws.com", 
    "SN": "1234567890", 
    "UPC": "1234567890" 
  },
  "rw": { 
    "iot_provisioning_state": "NOT_PROVISIONED"
  }
}

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

ユーザーガイドの設定を使用してデバイスをオンボードおよび運用する

プロセス間通信 (IPC) APIs