Memperluas Fungsionalitas CertOpenStore

Penyimpanan sertifikat adalah pusat untuk semua operasi manajemen sertifikat. Fungsionalitas fungsiCertOpenStoredapat diperluas melalui penggunaan fungsi penyedia penyimpanan sertifikat yang dapat diinstal (atau terdaftar). Untuk gambaran umum tentang cara menginstal atau mendaftarkan fungsi untuk digunakan dengan CryptoAPI, lihat Gambaran Umum OID .

Nota

Penyimpanan sertifikat kustom tidak dimigrasikan secara otomatis saat melakukan penyebaran otomatis. Untuk memigrasikan penyimpanan sertifikat kustom, Anda harus membuat manifes untuk memigrasikan penyimpanan kustom dan menggunakan Windows User State Migration Tool (USMT).

 

CertOpenStore membuka penyimpanan kosong dalam memori dan memanggil fungsi penyedia penyimpanan (jika terdaftar atau diinstal) dengan menggunakan pengidentifikasi objek (OID) yang diteruskan dalam parameter lpszStoreProvider. Untuk daftar jenis penyedia yang telah ditentukan sebelumnya yang disediakan dengan CryptoAPI, lihat CertOpenStore.

Fungsi penyedia penyimpanan menyalin sertifikatnya dan daftar pencabutan sertifikat (CRL) ke penyimpanan dalam memori yang ditentukan oleh pegangan hCertStore yang diteruskan ke fungsi tersebut. Fungsi penyedia penyimpanan baru dapat menggunakan salah satu fungsi penyimpanan sertifikat CryptoAPI, seperti, CertAddCertificateContextToStore atau CertAddSerializedElementToStore, untuk menambahkan sertifikat dan CRLnya ke penyimpanan dalam memori. Selain itu, fungsi penyedia penyimpanan secara opsional mengembalikan nilai untuk semua anggota data dari struktur CERT_STORE_PROV_INFO. Fungsi ini hanya perlu memperbarui struktur ini jika mendukung fungsi panggilan balik tambahan. Misalnya, jika penyimpanan akan menjadi penyimpanan baca-saja, dukungan fungsi panggilan balik lainnya mungkin tidak akan diperlukan. Untuk detail dan prototipe fungsi panggilan balik yang mungkin, lihat Fungsi Panggilan Balik Penyedia Penyimpanan Sertifikat.

Penyimpanan TrustedPeople per pengguna dibatasi untuk penyimpanan fisik yang telah ditentukan sebelumnya. Anda tidak dapat memperluas penyimpanan TrustedPeople per pengguna. Namun, Anda dapat memperluas penyimpanan TrustedPeople di komputer lokal.

Windows XP dan Windows Server 2003: Penyimpanan TrustedPeople per pengguna tidak dibatasi untuk penyimpanan fisik yang telah ditentukan sebelumnya.

Salah satu anggota data dari struktur CERT_STORE_PROV_INFO adalah array rgpvStoreProvFunc. Jika fungsi penyedia penyimpanan perlu mendukung satu atau beberapa fungsi panggilan balik, fungsi tersebut harus menyediakan pointer untuk array ini. Pointer ini harus menunjuk ke fungsi callback yang akan digunakan untuk aktivitas lain terkait penyimpanan sertifikat (seperti menutup toko sertifikat). Ilustrasi berikut menunjukkan alur proses ini.

Seperti yang ditunjukkan dalam ilustrasi berikut, setelah toko dibuka, fungsi CryptoAPI lainnya (seperti CertCloseStore) menggunakan array pointer untuk mengakses fungsi panggilan balik yang melaksanakan tugas yang dimaksudkan. Definisi struktur CERT_STORE_PROV_INFO dan prototipe fungsi panggilan balik default yang disediakan dengan CryptoAPI ditampilkan dalam Fungsi Panggilan Balik Penyedia Penyimpanan Sertifikat.

API penyimpanan memungkinkan penyedia penyimpanan untuk mempertahankan sertifikat, CRL, dan daftar kepercayaan sertifikat (CTL) di luar cache penyimpanan (misalnya, database eksternal sertifikat, seperti yang disediakan oleh Microsoft Certificate Server Database).

CertOpenStore disalurkan melalui parameter pszStoreProvider ke fungsi penyedia yang dapat diinstal CertDllOpenStoreProv yang sesuai. Penyedia mengembalikan informasi dalam parameter pStoreProvInfo yang menunjuk ke struktur CERT_STORE_PROV_INFO. Struktur CERT_STORE_PROV_INFO berisi anggota dwStoreProvFlags. Flag CERT_STORE_PROV_EXTERNAL_FLAG ditambahkan untuk memungkinkan penyedia menunjukkan bahwa sertifikat, CRL, dan CTL berada di luar cache toko.

CertDllOpenStoreProv mengembalikan array fungsi panggilan balik. Penyedia dapat menerapkan fungsi panggilan balik berikut:

• CERT_STORE_PROV_CLOSE_FUNC
• CERT_STORE_PROV_READ_CERT_FUNC
• CERT_STORE_PROV_WRITE_CERT_FUNC
• CERT_STORE_PROV_DELETE_CERT_FUNC
• CERT_STORE_PROV_SET_CERT_PROPERTY_FUNC
• CERT_STORE_PROV_READ_CRL_FUNC
• CERT_STORE_PROV_WRITE_CRL_FUNC
• CERT_STORE_PROV_DELETE_CRL_FUNC (Fungsi Menghapus CRL Penyedia Toko Sertifikat)
• Fungsi Pengaturan Properti CRL dari Penyedia Toko Sertifikat (CERT_STORE_PROV_SET_CRL_PROPERTY_FUNC)
• CERT_STORE_PROV_READ_CTL_FUNC
• CERT_STORE_PROV_WRITE_CTL_FUNC
• CERT_STORE_PROV_DELETE_CTL_FUNC
• CERT_STORE_PROV_SET_CTL_PROPERTY_FUNC

Pada panggilan ke fungsi callback WRITE_CERT, WRITE_CRL, dan WRITE_CTL saat CERT_STORE_PROV_WRITE_ADD_FLAG diatur, 16 bit teratas dari parameter dwFlags berisi nilai dwAddDisposition. Untuk mendukung penyimpanan eksternal, penyedia dapat menerapkan fungsi panggilan balik berikut:

• CERT_STORE_PROV_FIND_CERT_FUNC
• CERT_STORE_PROV_FREE_FIND_CERT_FUNC
• CERT_STORE_PROV_GET_CERT_PROPERTY_FUNC
• CERT_STORE_PROV_FIND_CRL_FUNC
• CERT_STORE_PROV_FREE_FIND_CRL_FUNC
• CERT_STORE_PROV_GET_CRL_PROPERTY_FUNC
• CERT_STORE_PROV_FIND_CTL_FUNC
• CERT_STORE_PROV_FREE_FIND_CTL_FUNC
• CERT_STORE_PROV_GET_CTL_PROPERTY_FUNC

Fungsi panggilan balik sertifikat memiliki tanda tangan berikut:

typedef struct _CERT_STORE_PROV_FIND_INFO {
    DWORD               cbSize;
    DWORD               dwMsgAndCertEncodingType;
    DWORD               dwFindFlags;
    DWORD               dwFindType;
    const void          *pvFindPara;
} CERT_STORE_PROV_FIND_INFO, *PCERT_STORE_PROV_FIND_INFO;
typedef const CERT_STORE_PROV_FIND_INFO CCERT_STORE_PROV_FIND_INFO,
    *PCCERT_STORE_PROV_FIND_INFO;

typedef BOOL (WINAPI *PFN_CERT_STORE_PROV_FIND_CERT)(
        IN HCERTSTOREPROV hStoreProv,
        IN PCCERT_STORE_PROV_FIND_INFO pFindInfo,
        IN PCCERT_CONTEXT pPrevCertContext,
        IN DWORD dwFlags,
        IN OUT void **ppvStoreProvFindInfo,
        OUT PCCERT_CONTEXT *ppProvCertContext
        );

typedef BOOL (WINAPI *PFN_CERT_STORE_PROV_FREE_FIND_CERT)(
        IN HCERTSTOREPROV hStoreProv,
        IN PCCERT_CONTEXT pCertContext,
        IN void *pvStoreProvFindInfo,
        IN DWORD dwFlags
        );

typedef BOOL (WINAPI *PFN_CERT_STORE_PROV_GET_CERT_PROPERTY)(
        IN HCERTSTOREPROV hStoreProv,
        IN PCCERT_CONTEXT pCertContext,
        IN DWORD dwPropId,
        IN DWORD dwFlags,
        OUT void *pvData,
        IN OUT DWORD *pcbData
        );

Penanda tangan untuk fungsi panggilan balik CRL dan CTL identik dengan yang di atas dengan penunjuk ke CERT_CONTEXT diganti dengan penunjuk ke CRL_CONTEXT atau CTL_CONTEXT.

Panggilan balik FIND_CERT dipanggil saat API penyimpanan menghitung, menemukan, atau menambahkan sertifikat. pPrevCertContext dan ppvStoreProvFindInfo diatur ke NULL untuk memulai FIND baru. yang dikembalikan ppvStoreProvFindInfo diteruskan kembali pada pencarian berikutnya, pada saat itu, mungkin akan dibebaskan oleh penyedia. Penyedia dapat mengatur semua, beberapa, atau tidak ada properti sertifikat. Penyedia memiliki opsi untuk menunda hingga panggilan balik GET_CERT_PROPERTY dipanggil. Disarankan agar penyedia mengatur sebanyak mungkin properti untuk memungkinkan penggandaan ke toko lain.

Jenis temuan sertifikat berikut didukung di CertFindCertificateInStore:

• CERT_FIND_ANY
• CERT_FIND_SHA1_HASH
• CERT_FIND_MD5_HASH
• CERT_FIND_PROPERTY (Pencarian Properti Sertifikat)
• CERT_FIND_PUBLIC_KEY (TEMUKAN_KUNCI_UMUM)
• CERT_FIND_SUBJECT_NAME
• CERT_FIND_SUBJECT_ATTR
• CERT_FIND_ISSUER_NAME
• CERT_FIND_ISSUER_ATTR
• CERT_FIND_SUBJECT_STR_A
• CERT_FIND_SUBJECT_STR_W
• CERT_FIND_ISSUER_STR_A
• CERT_FIND_ISSUER_STR_W
• CERT_FIND_KEY_SPEC
• CERT_FIND_ENHKEY_USAGE

Panggilan balik FIND_CERT dipanggil untuk setiap jenis temuan di atas. Parameter yang diteruskan ke CertFindCertificateInStore disalin langsung ke struktur CERT_STORE_PROV_FIND_INFO sebelum panggilan balik FIND_CERT dipanggil. Untuk detail tentang nilai-nilai bidang untuk jenis pencarian yang berbeda dari struktur CERT_STORE_PROV_FIND_INFO, lihat CertFindCertificateInStore.

Jenis pencarian sertifikat berikut mendukung CertGetSubjectCertificateFromStore dan CertGetIssuerCertificateFromStore API dan membantu menentukan apakah sertifikat sudah ada di penyimpanan sebelum menambahkan:

• CERT_FIND_SUBJECT_CERT
• TEMUKAN_PENERBIT_DARI
• CERT_FIND_EXISTING

Untuk CERT_FIND_SUBJECT_CERT, parameter pvFindPara menunjuk ke struktur CERT_INFO yang berisi Penerbit dan SerialNumber subjek. Untuk CERT_FIND_ISSUER_OF, pvFindPara menunjuk ke struktur CERT_CONTEXT dari subjek. Untuk CERT_FIND_EXISTING, pvFindPara menunjuk ke CERT_CONTEXT sertifikat untuk memeriksa keberadaannya di toko.

Callback FREE_FIND_CERT dipanggil ketika sertifikat yang dikembalikan oleh callback FIND_CERT tidak dirilis dengan digunakan dalam FIND_CERT berikutnya, sehingga jumlah referensinya berkurang menjadi nol, atau dilepaskan melalui panggilan ke CertCloseStore. Sebelum panggilan balik CLOSE dipanggil, semua sertifikat yang dikembalikan oleh panggilan balik FIND_CERT harus dirilis ke penyedia dengan diteruskan ke panggilan balik FIND_CERT atau panggilan ke panggilan balik FREE_FIND_CERT. Hal yang sama berlaku untuk panggilan balik CRL dan CTL.

Panggilan balik GET_CERT_PROPERTY dipanggil oleh CertGetCertificateContextProperty jika tidak dapat menemukan properti yang ditentukan untuk parameter pCertContext. Hal yang sama berlaku untuk GET_CRL_PROPERTY dan GET_CTL_PROPERTY.

Panggilan balik FIND_CRL dipanggil ketika API penyimpanan menghitung atau mendapatkan CRL dan sebelum menambahkan CRL. Jenis temuan CRL berikut akan ditentukan:

Untuk CRL_FIND_ISSUED_BY, pvFindPara merupakan penunjuk ke CERT_CONTEXT dari penerbit CRL. Untuk CRL_FIND_EXISTING, pvFindPara adalah pointer ke CRL_CONTEXT dari CRL untuk menentukan apakah sudah ada di penyimpanan.

Panggilan balik FIND_CTL dipanggil saat API penyimpanan menghitung atau menemukan CTL. Jenis temuan CTL berikut didukung di CertFindCTLInStore:

• CTL_CARI_APAPUN
• CTL_FIND_SHA1_HASH
• CTL_FIND_MD5_HASH
• CTL_FIND_USAGE
• CTL_FIND_SUBJECT
• CTL_CARI_YANG_SUDAH_ADA

Panggilan balik FIND_CTL dipanggil untuk setiap jenis temuan di atas. Parameter yang diteruskan ke CertFindCTLInStore disalin langsung ke struktur CERT_STORE_PROV_FIND_INFO sebelum panggilan balik FIND_CTL dipanggil. Untuk detail tentang nilai-nilai bidang untuk berbagai tipe pencarian dari struktur CERT_STORE_PROV_FIND_INFO, lihat CertFindCTLInStore.

Jenis pencarian CTL_FIND_EXISTING membantu menentukan apakah CTL sudah ada di toko sebelum melakukan penambahan CTL.

Untuk CTL_FIND_EXISTING, pvFindPara adalah penunjuk ke struktur CTL_CONTEXT CTL untuk menentukan apakah sudah ada di toko.