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

重要

これは Azure Sphere (レガシ) のドキュメントです。 Azure Sphere (レガシ) は 2027 年 9 月 27 日に 再提供されておりユーザーは現時点で Azure Sphere (統合) に移行する必要があります。 TOC の上にある Version セレクターを使用して、Azure Sphere (統合) のドキュメントを表示します。

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

証明書は 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、azsphere CLI によって使用されます。 このため、コマンド ラインから証明書を読み込む場合、その証明書をクエリ、移動、または削除するすべてのアプリケーションで同じ ID を使用する必要があります。 同様に、アプリで証明書を読み込む場合、その証明書を操作するすべての azsphere コマンドで同じ ID を使用する必要があります。 任意の種類の既存の証明書と同じ ID を持つ新しい証明書をインストールすると、新しい証明書によって既存の証明書が上書きされます。

注意事項

証明書 ID はシステム全体でクライアントとルート CA の両方の証明書に対して使用されるため、azsphere コマンドまたは新しい証明書を追加する関数呼び出しにより、以前のコマンドまたは関数呼び出しによって追加された証明書が上書きされることがあり、これにより、ネットワーク接続エラーが発生する可能性があります。 明確な証明書の更新手順を作成し、証明書 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 は、証明書のサブジェクトの名前、つまり、証明書で保護されるものを取得します

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

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

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

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

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

次のメソッドは正常に機能します。

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 関数を使用する方法が示されています。