高度なアプリケーションで証明書を管理する

[アーティクル]
08/09/2023

CertStore API を使用すると、高度なアプリケーションがネットワーク認証で使用する証明書を管理できます。 az sphere デバイス証明書を使用すると、コマンドラインから証明書を管理できます。

証明書は、Azure Sphere デバイス上の不揮発性ストレージに格納されます。 証明書ストア (証明書ストア) は、最大 24 KiB の証明書を保持できます。証明書の最大サイズは 8 KiB です。通常、ルート CA 証明書はクライアント証明書よりも大きくなります。証明書ストアを使用するだけでなく、Microsoft が管理するクライアント証明書にもアクセスできます。 Microsoft が管理するクライアント証明書は、デバイスが少なくとも 24 時間に 1 回インターネットに接続されている場合にのみ使用できます。

Microsoft マネージドクライアント証明書を使用する

これら 2 つの関数を使用して、クライアント証明書を取得し、使用する準備ができているかどうかを判断します。

DeviceAuth_GetCertificatePath は、OS によって管理されるクライアント証明書へのファイルパスを返します。このファイルパスは、TLS 通信用の証明書を読み込むための一部のライブラリで必要です。
Application_IsDeviceAuthReady 、現在のアプリケーションのデバイス認証の準備ができているかどうかを確認します。

CertStore の要件

CertStore API を使用するアプリケーションには、適切なヘッダーファイルを含め、アプリケーションマニフェストに CertStore 機能を追加する必要があります。

ヘッダーファイル

プロジェクトに CertStore ヘッダーを含めます。

 #include <applibs\certstore.h>

アプリケーションマニフェストの設定

証明書ストア API を使用するには、アプリケーション機能を CertStore アプリケーションマニフェストに追加し、値をに設定する true必要があります。 Azure Sphere アプリケーションマニフェストトピックには、アプリケーションマニフェストの詳細が記載されています。

{
  "SchemaVersion": 1,
  "Name" : "Mt3620App3",
  "ComponentId" : "bb267cbd-4d2a-4937-8dd8-3603f48cb8f6",
  "EntryPoint": "/bin/app",
  "CmdArgs": [],
   "Capabilities": {
    "AllowedConnections": [],
    "AllowedTcpServerPorts": [],
    "AllowedUdpServerPorts": [],
    "CertStore" : true,
    "Gpio": [],
    "Uart": [],
    "EnterpriseWifiConfig": true,
    "WifiConfig": true,
    "NetworkConfig": false,
    "SystemTime": true
  }
}

証明書 ID

すべての証明書は、 証明書識別子 (ID) に関連付けられます。証明書 ID は、デバイス上の証明書を一意に識別する 1 から 16 文字の文字列です。有効な文字は、'a'-'z'、'A'-'Z'、'0'-'9'、ハイフン (-) です。とアンダースコア (_)。すべての証明書 ID は、識別する証明書の種類に関係なく、デバイス全体で一意である必要があります。

各証明書の識別子は証明書ストアに保存され、 CertStore API、 WifiConfig API、Azure CLI 拡張機能によってデバイス全体で使用されます。そのため、コマンドラインから証明書を読み込む場合、その証明書のクエリ、移動、または削除を行うアプリケーションでは、同じ ID を使用する必要があります。同様に、アプリが証明書を読み込む場合、証明書を操作するすべての az sphere コマンドで同じ ID を使用する必要があります。任意の種類の既存の証明書と同じ ID の新しい証明書をインストールすると、新しい証明書によって既存の証明書が上書きされます。

注意

証明書 ID はクライアントとルート CA の両方の証明書に対してシステム全体であるため、az sphere コマンドまたは新しい証明書を追加する関数呼び出しによって、以前のコマンドまたは関数呼び出しによって追加された証明書が上書きされ、ネットワーク接続エラーが発生する可能性があります。明確な証明書の更新手順を開発し、証明書 ID を慎重に選択することを強くお勧めします。

証明書ストアに証明書を追加する

証明書ストアに証明書を追加するために、アプリは次のいずれかの関数を呼び出します。

CertStore_InstallClientCertificate は、公開証明書と秘密キーで構成されるクライアント証明書をインストールします
CertStore_InstallRootCACertificate は、パブリック証明書で構成されるルート CA 証明書をインストールします

証明書は、アプリがインストールする前にデバイスに存在している必要があります。 Azure Sphere デバイスに読み込むには、証明書が PKCS1 または PKCS8 構文と .pem 形式である必要があります。 EAP-TLS ネットワークの証明書を取得して展開する方法については、証明書を取得してデバイスに読み込む方法について説明します。 Microsoft は証明書を提供していません。

証明書をインストールすると、証明書ストアに追加され、認証で使用できるようになります。証明書ストア内では、証明書はインデックスによって管理され、インデックスによって取得できます。インデックス値の範囲は、0 から (CertStore_GetCertificateCount - 1) まで実行されます。

アプリは、 CertStore_GetCertificateIdentifierAt関数を呼び出すことによって、特定のインデックスにある証明書の ID を取得できます。その後、呼び出しで証明書 ID を使用して、証明書に関する情報を取得したり、証明書を移動または削除したり、認証に証明書を使用したりできます。

証明書情報を取得する

CertStore API には、格納されている証明書に関する情報を返すいくつかの関数が含まれています。

CertStore_GetCertificateNotBefore は、証明書が有効になる時刻を取得します
CertStore_GetCertificateNotAfter 証明書の有効期限が切れる時刻を取得します
証明書の 発行者の名前を取得CertStore_GetCertificateIssuerName
CertStore_GetCertificateSubjectName 証明書のサブジェクトの名前を取得します。つまり、証明書が保護するもの

証明書の有効期間と更新プログラムを管理する場合は、前以外と後以外の時刻が役立ちます。詳細については、「証明書のライフサイクルと更新」を参照してください。

証明書の名前を変更または削除する

証明書の名前を変更または削除するには、アプリが CertStore_MoveCertificate または CertStore_DeleteCertificateを呼び出します。

CertStore_MoveCertificate 証明書 ID を変更して証明書の名前を変更します。証明書 ID はデバイス間で一意である必要があるため、別の証明書と同じ ID を指定して証明書の名前を変更すると、その証明書が削除されます。たとえば、証明書ストアにと YourCertが含まれているMyCert場合、に移動MyCertするとYourCert、ID YourCertを持つ証明書が 1 つになり、前の MyCertからのデータが含まれます。エラーは返されません。

CertStore_DeleteCertificate は、1 つの証明書を削除します。証明書を削除すると、残りの証明書のインデックスが 0 から再作成されます。したがって、証明書ストア内のすべての証明書を削除するには、証明書の数に基づいてループする必要がありますが、各イテレーションでインデックス 0 で証明書を削除する必要があります。使用されなくなったインデックスで証明書を削除しようとすると、ERANGE が返CertStore_GetCertificateIdentifierAt 。

次のメソッドは正しく動作します。

for (int i = 0; i < CertStore_GetCertificateCount(); i++) {
    struct CertStore_Identifier id;
    result = CertStore_GetCertificateIdentifierAt(0, &id);
    CertStore_DeleteCertificate(id.identifier);
}

ネットワーク認証に証明書を使用する

WifiConfig API には、特定の Wi-Fi 構成で有効になっている証明書を設定して返す関数が用意されています。認証に証明書を使用する EAP-TLS ネットワークを上位レベルのアプリケーションで設定する方法の詳細については、「アプリでの EAP-TLS ネットワークの設定」を参照してください。

証明書のサンプル

証明書サンプルアプリケーションは、アプリケーションで CertStore 関数を使用する方法を示しています。