Mengelola sertifikat dalam aplikasi tingkat tinggi

Artikel
08/09/2023

API CertStore memungkinkan aplikasi tingkat tinggi mengelola sertifikat untuk digunakan dalam autentikasi jaringan. Sertifikat perangkat bola az memungkinkan Anda mengelola sertifikat dari baris perintah.

Sertifikat disimpan di penyimpanan nonvolatil di perangkat Azure Sphere. Toko sertifikat, atau toko sert, dapat menyimpan hingga 24 KiB sertifikat. Ukuran maksimum untuk sertifikat adalah 8 KiB. Sertifikat CA Akar biasanya lebih besar dari sertifikat klien. Selain menggunakan toko sert, Anda juga dapat mengakses sertifikat klien yang dikelola Microsoft. Sertifikat klien yang dikelola Microsoft hanya akan tersedia untuk digunakan saat perangkat tersambung ke internet setidaknya sekali setiap 24 jam.

Menggunakan sertifikat klien yang dikelola Microsoft

Gunakan dua fungsi ini untuk mendapatkan sertifikat klien dan tentukan apakah sudah siap digunakan.

DeviceAuth_GetCertificatePath mengembalikan jalur file ke sertifikat klien yang dikelola oleh OS. Jalur file ini diperlukan oleh beberapa pustaka untuk memuat sertifikat untuk komunikasi TLS.
Application_IsDeviceAuthReady untuk memverifikasi apakah autentikasi perangkat untuk aplikasi saat ini sudah siap.

Persyaratan CertStore

Aplikasi yang menggunakan API CertStore harus menyertakan file header yang sesuai dan menambahkan kapabilitas CertStore ke manifes aplikasi.

File header

Sertakan header CertStore di proyek Anda:

 #include <applibs\certstore.h>

Pengaturan manifes aplikasi

Untuk menggunakan API penyimpanan sertifikat, Anda harus menambahkan CertStore kapabilitas aplikasi ke manifes aplikasi dan mengatur nilai ke true. Topik manifes aplikasi Azure Sphere memiliki detail selengkapnya tentang manifes aplikasi.

{
  "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 Sertifikat

Setiap sertifikat dikaitkan dengan pengidentifikasi sertifikat (ID). ID sertifikat adalah string 1-16 karakter yang mengidentifikasi sertifikat di perangkat secara unik. Karakter yang valid adalah 'a'-'z', 'A'-'Z', '0'-'9', tanda hubung (-). dan garis bawah (_). Setiap ID sertifikat harus unik di seluruh perangkat, terlepas dari tipe sertifikat yang diidentifikasinya.

Setiap pengidentifikasi sertifikat disimpan di penyimpanan sertifikat dan digunakan di seluruh perangkat: oleh API CertStore , API WifiConfig , dan ekstensi Azure CLI. Akibatnya, jika Anda memuat sertifikat dari baris perintah, aplikasi apa pun yang meminta, memindahkan, atau menghapus sertifikat tersebut harus menggunakan ID yang sama. Demikian pula, jika aplikasi memuat sertifikat, perintah apa pun az sphere yang memanipulasi sertifikat harus menggunakan ID yang sama. Jika Anda menginstal sertifikat baru dengan ID yang sama dengan sertifikat tipe apa pun yang sudah ada, sertifikat baru akan menimpa sertifikat yang sudah ada.

Hati

Karena ID sertifikat berskala sistem untuk sertifikat CA Akar dan klien, perintah az sphere atau panggilan fungsi yang menambahkan sertifikat baru bisa menimpa sertifikat yang ditambahkan oleh perintah atau panggilan fungsi yang lebih lama, berpotensi menyebabkan kegagalan koneksi jaringan. Kami sangat menyarankan agar Anda mengembangkan prosedur pembaruan sertifikat yang jelas dan memilih ID sertifikat dengan hati-hati.

Menambahkan sertifikat ke penyimpanan sertifikat

Untuk menambahkan sertifikat ke toko sertifikat, aplikasi memanggil salah satu fungsi berikut:

CertStore_InstallClientCertificate menginstal sertifikat klien, yang terdiri dari sertifikat publik dan kunci privat
CertStore_InstallRootCACertificate menginstal sertifikat CA Akar, yang terdiri dari sertifikat publik

Sertifikat harus ada di perangkat sebelum aplikasi dapat menginstalnya. Sertifikat harus berada dalam sintaks PKCS1 atau PKCS8 dan format .pem untuk dimuat ke perangkat Azure Sphere. Memperoleh dan menyebarkan sertifikat untuk jaringan EAP-TLS menjelaskan cara memperoleh sertifikat dan memuatnya ke perangkat. Microsoft tidak menyediakan sertifikat.

Menginstal sertifikat akan menambahkannya ke penyimpanan sertifikat dan membuatnya tersedia untuk digunakan dalam autentikasi. Di dalam penyimpanan sertifikat, sertifikat dikelola oleh indeks dan dapat diambil oleh indeks. Rentang nilai indeks berjalan dari 0 hingga (CertStore_GetCertificateCount - 1).

Aplikasi bisa mendapatkan ID sertifikat di indeks tertentu dengan memanggil fungsi CertStore_GetCertificateIdentifierAt. Kemudian, ID sertifikat dapat digunakan dalam panggilan untuk mendapatkan informasi tentang sertifikat, memindahkan atau menghapus sertifikat, dan menggunakan sertifikat untuk autentikasi.

Dapatkan informasi sertifikat

API CertStore menyertakan beberapa fungsi yang mengembalikan informasi tentang sertifikat yang disimpan:

CertStore_GetCertificateNotBefore mendapatkan waktu sertifikat menjadi valid
CertStore_GetCertificateNotAfter mendapatkan waktu kedaluwarsa sertifikat
CertStore_GetCertificateIssuerName mendapatkan nama penerbit sertifikat
CertStore_GetCertificateSubjectName mendapatkan nama subjek sertifikat; yaitu, apa yang dilindungi sertifikat

Waktu yang tidak sebelum dan tidak sesudahnya berguna dalam mengelola masa berlaku dan pembaruan sertifikat. Lihat Siklus hidup dan perpanjangan sertifikat untuk detailnya.

Mengganti nama atau menghapus sertifikat

Untuk mengganti nama atau menghapus sertifikat, aplikasi memanggil CertStore_MoveCertificate atau CertStore_DeleteCertificate.

CertStore_MoveCertificate mengganti nama sertifikat dengan mengubah ID sertifikatnya. Karena ID sertifikat harus unik di seluruh perangkat, mengganti nama sertifikat dengan memberikan ID yang sama seperti sertifikat lain menghapus sertifikat tersebut. Misalnya, jika penyimpanan sertifikat berisi MyCert dan YourCert, berpindah MyCert ke YourCert hasil dalam satu sertifikat dengan ID YourCert, yang berisi data dari mantan MyCert. Tidak ada kesalahan yang dikembalikan.

CertStore_DeleteCertificate menghapus satu sertifikat. Menghapus sertifikat menyebabkan sertifikat yang tersisa diindeks ulang, dimulai dari 0. Oleh karena itu, untuk menghapus semua sertifikat di penyimpanan sertifikat, Anda perlu mengulang berdasarkan jumlah sertifikat tetapi menghapus sertifikat pada indeks 0 di setiap perulangan. Jika Anda mencoba menghapus sertifikat di indeks yang tidak lagi digunakan, CertStore_GetCertificateIdentifierAt mengembalikan ERANGE.

Metode berikut ini berfungsi dengan benar:

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

Menggunakan sertifikat untuk autentikasi jaringan

API WifiConfig menyediakan fungsi yang mengatur dan mengembalikan sertifikat yang diaktifkan untuk konfigurasi Wi-Fi tertentu. Lihat Menyiapkan jaringan EAP-TLS dalam aplikasi untuk detail tentang bagaimana aplikasi tingkat tinggi dapat menyiapkan jaringan EAP-TLS yang menggunakan sertifikat untuk autentikasi.

Sampel sertifikat

Aplikasi sampel Sertifikat memperlihatkan bagaimana aplikasi dapat menggunakan fungsi CertStore.

Bagikan melalui