使用“api-monitor工具”及應用程式讀取smart card 資訊
PCCERT_CONTEXT WINAPI CertCreateCertificateContext(
__in DWORD dwCertEncodingType,
__in const BYTE* pbCertEncoded,
__in DWORD cbCertEncoded
);
Parameters
- dwCertEncodingType
-
Specifies the type of encoding used. It is always acceptable to specify both the certificate andmessage encoding types
X509_ASN_ENCODING | PKCS_7_ASN_ENCODING
Currently defined encoding types are:
- X509_ASN_ENCODING
- PKCS_7_ASN_ENCODING
- pbCertEncoded
-
A pointer to a buffer that contains the encoded certificate from which the context is to be created.
- cbCertEncoded
-
The size, in bytes, of the pbCertEncoded buffer.
Return Value
If the function succeeds, the function returns a pointer to a read-only CERT_CONTEXT. When you have finished using the certificate context, free it by calling theCertFreeCertificateContext function.
If the function is unable to decode and create the certificate context
Return code | Description |
---|---|
E_INVALIDARG |
A certificate encoding type that is not valid was specified. Currently, only the X509_ASN_ENCODING type is supported. |
If the function fails, GetLastError may return an Abstract Syntax Notation One (ASN.1) encoding/decoding error. For information about these errors, seeASN.1 Encoding/Decoding Return Values.
Remarks
The CERT_CONTEXT must be freed by calling CertFreeCertificateContext.CertDuplicateCertificateContext can be called to make a duplicate.CertSetCertificateContextProperty andCertGetCertificateContextProperty can be called to store and read properties for the certificate.
Example Code [C++]
The following example shows creating a certificate context from an encoded certificate. The created context is not put in a certificate store. For another example that uses this function, seeExample C Program: Certificate Store Operations.
#define MY_ENCODING_TYPE (PKCS_7_ASN_ENCODING | X509_ASN_ENCODING)
PCCERT_CONTEXT pCertContext = NULL;
//------------------------------------------------------------------
// Create a new certificate from the encoded part of
// an available certificate. pDesiredCert is a previously
// assigned PCCERT_CONTEXT variable.
if(pCertContext = CertCreateCertificateContext(
MY_ENCODING_TYPE, // The encoding type
pDesiredCert->pbCertEncoded, // The encoded data from
// the certificate retrieved
pDesiredCert->cbCertEncoded)) // The length of the encoded data
{
printf("A new certificate as been created.\n");
// Use the certificate context as needed.
// ...
// When finished, free the certificate context.
CertFreeCertificateContext(pCertContext);
}
else
{
printf("A new certificate could not be created.\n");
exit(1);
}
CertAddCertificateContextToStore Function
The CertAddCertificateContextToStore function adds a certificate context to the certificate store.
Syntax
BOOL WINAPI CertAddCertificateContextToStore(
__in HCERTSTORE hCertStore,
__in PCCERT_CONTEXT pCertContext,
__in DWORD dwAddDisposition,
__out_opt PCCERT_CONTEXT* ppStoreContext
);
Parameters
- hCertStore
-
Handle of a certificate store.
- pCertContext
-
A pointer to the CERT_CONTEXT structure to be added to the store.
- dwAddDisposition
-
Specifies the action to take if a matching certificate or a link to a matching certificate already exists in the store. Currently defined disposition values and their uses are as follows.
Value Meaning CERT_STORE_ADD_ALWAYS
The function makes no check for an existing matching certificate or link to a matching certificate. A new certificate is always added to the store. This can lead to duplicates in a store.
CERT_STORE_ADD_NEW
If a matching certificate or a link to a matching certificate exists, the operation fails.GetLastError returns the CRYPT_E_EXISTS code.
CERT_STORE_ADD_REPLACE_EXISTING
If a link to a matching certificate exists, that existing certificate or link is deleted and a new certificate is created and added to the store. If a matching certificate or a link to a matching certificate does not exist, a new link is added.
CERT_STORE_ADD_REPLACE_EXISTING_INHERIT_PROPERTIES
If a matching certificate exists in the store, the existing context is deleted before creating and adding the new context. The new added context inherits properties from the existing certificate.
CERT_STORE_ADD_USE_EXISTING
If a matching certificate or a link to a matching certificate exists, that existing certificate or link is used and properties from the new certificate are added. The function does not fail, but it does not add a new context. IfppCertContext is not NULL, the existing context is duplicated.
If a matching certificate or a link to a matching certificate does not exist, a new certificate is added.
- ppStoreContext
-
A pointer to a pointer to the copy to be made of the certificate that was added to the store.
The ppStoreContext parameter can be NULL, indicating that the calling application does not require a copy of the added certificate. If a copy is made, it must be freed by usingCertFreeCertificateContext.
Return Value
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. For extended error information, callGetLastError. Some possible error codes follow.
CertEnumCertificatesInStore Function
The CertEnumCertificatesInStore function retrieves the first or next certificate in a certificate store. Used in a loop, this function can retrieve in sequence all certificates in a certificate store.
Syntax
PCCERT_CONTEXT WINAPI CertEnumCertificatesInStore(
__in HCERTSTORE hCertStore,
__in PCCERT_CONTEXT pPrevCertContext
);
Parameters
- hCertStore
-
A handle of a certificate store.
- pPrevCertContext
-
A pointer to the CERT_CONTEXT of the previouscertificate context found.
This parameter must be NULL to begin the enumeration and get the first certificate in the store. Successive certificates are enumerated by settingpPrevCertContext to the pointer returned by a previous call to the function. This function frees theCERT_CONTEXT referenced by non-NULL values of this parameter.
For logical stores, including collection stores, a duplicate of the pCertContext returned by this function cannot be used to begin a new subsequence of enumerations because the duplicated certificate loses the initial enumerationstate. The enumeration skips any certificate previously deleted by CertDeleteCertificateFromStore.
Return Value
If the function succeeds, the function returns a pointer to the next CERT_CONTEXT in the store. If no more certificates exist in the store, the function returns NULL.
For extended error information, call GetLastError. Some possible error codes follow.
Remarks
The returned pointer is freed when passed as the pPrevCertContext parameter on a subsequent call. Otherwise, the pointer must be freed by callingCertFreeCertificateContext. A non-NULLpPrevCertContext passed toCertEnumCertificatesInStore is always freed even for an error.
A duplicate of the currently enumerated certificate can be made by calling CertDuplicateCertificateContext.
Example Code [C++]
The following example lists the certificate contexts in the certificate store. For another example that uses this function, seeExample C Program: Deleting Certificates from a Certificate Store.
void TestCertEnumCertificatesInStore()
{
// Declare and initialize variables.
HANDLE hStoreHandle = NULL;
PCCERT_CONTEXT pCertContext = NULL;
char * pszStoreName = "CA";
//--------------------------------------------------------------------
// Open a system certificate store.
if (hStoreHandle = CertOpenSystemStore(
NULL,
pszStoreName))
{
printf("The %s store has been opened. \n", pszStoreName);
}
else
{
printf("The store was not opened.\n");
exit(1);
}
//-------------------------------------------------------------------
// Find the certificates in the system store.
while(pCertContext= CertEnumCertificatesInStore(
hStoreHandle,
pCertContext)) // on the first call to the function,
// this parameter is NULL
// on all subsequent calls,
// this parameter is the last pointer
// returned by the function
{
//----------------------------------------------------------------
// Do whatever is needed for a current certificate.
// ...
} // End of while.
//--------------------------------------------------------------------
// Clean up.
if (!CertCloseStore(
hStoreHandle,
0))
{
printf("Failed CertCloseStore\n");
exit(1);
}
}