模拟服务器

开发平台：

C/C++

WinCrypt.h：源码内容

// also copied. Note, the CERT_KEY_CONTEXT_PROP_ID property (and its
// CERT_KEY_PROV_HANDLE_PROP_ID or CERT_KEY_SPEC_PROP_ID) isn't copied.
//
// Makes a copy of the certificate context before adding to the store.
//
// dwAddDispostion specifies the action to take if the certificate
// already exists in the store. This parameter must be one of the following
// values:
// CERT_STORE_ADD_NEW
// Fails if the certificate already exists in the store. LastError
// is set to CRYPT_E_EXISTS.
// CERT_STORE_ADD_USE_EXISTING
// If the certifcate already exists, then, its used and if ppStoreContext
// is non-NULL, the existing context is duplicated. Iterates
// through pCertContext's properties and only copies the properties
// that don't already exist. The SHA1 and MD5 hash properties aren't
// copied.
// CERT_STORE_ADD_REPLACE_EXISTING
// If the certificate already exists, then, the existing certificate
// context is deleted before creating and adding a new context.
// Properties are copied before doing the add.
// CERT_STORE_ADD_ALWAYS
// No check is made to see if the certificate already exists. A
// new certificate context is always created and added. This may lead to
// duplicates in the store. Properties are
// copied before doing the add.
// CERT_STORE_ADD_REPLACE_EXISTING_INHERIT_PROPERTIES
// If the certificate already exists, then, the existing certificate
// context is used. Properties from the added context are copied and
// replace existing properties. However, any existing properties not
// in the added context remain and aren't deleted.
// CERT_STORE_ADD_NEWER
// Fails if the certificate already exists in the store AND the NotBefore
// time of the existing context is equal to or greater than the
// NotBefore time of the new context being added. LastError
// is set to CRYPT_E_EXISTS.
//
// If an older context is replaced, same as
// CERT_STORE_ADD_REPLACE_EXISTING.
//
// For CRLs or CTLs compares the ThisUpdate times.
//
// CERT_STORE_ADD_NEWER_INHERIT_PROPERTIES
// Same as CERT_STORE_ADD_NEWER. However, if an older context is
// replaced, same as CERT_STORE_ADD_REPLACE_EXISTING_INHERIT_PROPERTIES.
//
// CertGetSubjectCertificateFromStore is called to determine if the
// certificate already exists in the store.
//
// ppStoreContext can be NULL, indicating the caller isn't interested
// in getting the CERT_CONTEXT of the added or existing certificate.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertAddCertificateContextToStore(
IN HCERTSTORE hCertStore,
IN PCCERT_CONTEXT pCertContext,
IN DWORD dwAddDisposition,
OUT OPTIONAL PCCERT_CONTEXT *ppStoreContext
);
//+-------------------------------------------------------------------------
// Certificate Store Context Types
//--------------------------------------------------------------------------
#define CERT_STORE_CERTIFICATE_CONTEXT 1
#define CERT_STORE_CRL_CONTEXT 2
#define CERT_STORE_CTL_CONTEXT 3
//+-------------------------------------------------------------------------
// Certificate Store Context Bit Flags
//--------------------------------------------------------------------------
#define CERT_STORE_ALL_CONTEXT_FLAG (~0UL)
#define CERT_STORE_CERTIFICATE_CONTEXT_FLAG
(1 << CERT_STORE_CERTIFICATE_CONTEXT)
#define CERT_STORE_CRL_CONTEXT_FLAG
(1 << CERT_STORE_CRL_CONTEXT)
#define CERT_STORE_CTL_CONTEXT_FLAG
(1 << CERT_STORE_CTL_CONTEXT)
//+-------------------------------------------------------------------------
// Add the serialized certificate or CRL element to the store.
//
// The serialized element contains the encoded certificate, CRL or CTL and
// its properties, such as, CERT_KEY_PROV_INFO_PROP_ID.
//
// If hCertStore is NULL, creates a certificate, CRL or CTL context not
// residing in any store.
//
// dwAddDispostion specifies the action to take if the certificate or CRL
// already exists in the store. See CertAddCertificateContextToStore for a
// list of and actions taken.
//
// dwFlags currently isn't used and should be set to 0.
//
// dwContextTypeFlags specifies the set of allowable contexts. For example, to
// add either a certificate or CRL, set dwContextTypeFlags to:
// CERT_STORE_CERTIFICATE_CONTEXT_FLAG | CERT_STORE_CRL_CONTEXT_FLAG
//
// *pdwContextType is updated with the type of the context returned in
// *ppvContxt. pdwContextType or ppvContext can be NULL, indicating the
// caller isn't interested in getting the output. If *ppvContext is
// returned it must be freed by calling CertFreeCertificateContext or
// CertFreeCRLContext.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertAddSerializedElementToStore(
IN HCERTSTORE hCertStore,
IN const BYTE *pbElement,
IN DWORD cbElement,
IN DWORD dwAddDisposition,
IN DWORD dwFlags,
IN DWORD dwContextTypeFlags,
OUT OPTIONAL DWORD *pdwContextType,
OUT OPTIONAL const void **ppvContext
);
//+-------------------------------------------------------------------------
// Delete the specified certificate from the store.
//
// All subsequent gets or finds for the certificate will fail. However,
// memory allocated for the certificate isn't freed until all of its contexts
// have also been freed.
//
// The pCertContext is obtained from a get, enum, find or duplicate.
//
// Some store provider implementations might also delete the issuer's CRLs
// if this is the last certificate for the issuer in the store.
//
// NOTE: the pCertContext is always CertFreeCertificateContext'ed by
// this function, even for an error.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertDeleteCertificateFromStore(
IN PCCERT_CONTEXT pCertContext
);
//+-------------------------------------------------------------------------
// Add the encoded CRL to the store according to the specified
// disposition option.
//
// Makes a copy of the encoded CRL before adding to the store.
//
// dwAddDispostion specifies the action to take if the CRL
// already exists in the store. See CertAddEncodedCertificateToStore for a
// list of and actions taken.
//
// Compares the CRL's Issuer to determine if the CRL already exists in the
// store.
//
// ppCrlContext can be NULL, indicating the caller isn't interested
// in getting the CRL_CONTEXT of the added or existing CRL.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertAddEncodedCRLToStore(
IN HCERTSTORE hCertStore,
IN DWORD dwCertEncodingType,
IN const BYTE *pbCrlEncoded,
IN DWORD cbCrlEncoded,
IN DWORD dwAddDisposition,
OUT OPTIONAL PCCRL_CONTEXT *ppCrlContext
);
//+-------------------------------------------------------------------------
// Add the CRL context to the store according to the specified
// disposition option.
//
// In addition to the encoded CRL, the context's properties are
// also copied. Note, the CERT_KEY_CONTEXT_PROP_ID property (and its
// CERT_KEY_PROV_HANDLE_PROP_ID or CERT_KEY_SPEC_PROP_ID) isn't copied.
//
// Makes a copy of the encoded CRL before adding to the store.
//
// dwAddDispostion specifies the action to take if the CRL
// already exists in the store. See CertAddCertificateContextToStore for a
// list of and actions taken.
//
// Compares the CRL's Issuer, ThisUpdate and NextUpdate to determine
// if the CRL already exists in the store.
//
// ppStoreContext can be NULL, indicating the caller isn't interested
// in getting the CRL_CONTEXT of the added or existing CRL.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertAddCRLContextToStore(
IN HCERTSTORE hCertStore,
IN PCCRL_CONTEXT pCrlContext,
IN DWORD dwAddDisposition,
OUT OPTIONAL PCCRL_CONTEXT *ppStoreContext
);
//+-------------------------------------------------------------------------
// Delete the specified CRL from the store.
//
// All subsequent gets for the CRL will fail. However,
// memory allocated for the CRL isn't freed until all of its contexts
// have also been freed.
//
// The pCrlContext is obtained from a get or duplicate.
//
// NOTE: the pCrlContext is always CertFreeCRLContext'ed by
// this function, even for an error.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertDeleteCRLFromStore(
IN PCCRL_CONTEXT pCrlContext
);
//+-------------------------------------------------------------------------
// Serialize the certificate context's encoded certificate and its
// properties.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertSerializeCertificateStoreElement(
IN PCCERT_CONTEXT pCertContext,
IN DWORD dwFlags,
OUT BYTE *pbElement,
IN OUT DWORD *pcbElement
);
//+-------------------------------------------------------------------------
// Serialize the CRL context's encoded CRL and its properties.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertSerializeCRLStoreElement(
IN PCCRL_CONTEXT pCrlContext,
IN DWORD dwFlags,
OUT BYTE *pbElement,
IN OUT DWORD *pcbElement
);
//+=========================================================================
// Certificate Trust List (CTL) Store Data Structures and APIs
//==========================================================================
//+-------------------------------------------------------------------------
// Duplicate a CTL context
//--------------------------------------------------------------------------
WINCRYPT32API
PCCTL_CONTEXT
WINAPI
CertDuplicateCTLContext(
IN PCCTL_CONTEXT pCtlContext
);
//+-------------------------------------------------------------------------
// Create a CTL context from the encoded CTL. The created
// context isn't put in a store.
//
// Makes a copy of the encoded CTL in the created context.
//
// If unable to decode and create the CTL context, NULL is returned.
// Otherwise, a pointer to a read only CTL_CONTEXT is returned.
// CTL_CONTEXT must be freed by calling CertFreeCTLContext.
// CertDuplicateCTLContext can be called to make a duplicate.
//
// CertSetCTLContextProperty and CertGetCTLContextProperty can be called
// to store properties for the CTL.
//--------------------------------------------------------------------------
WINCRYPT32API
PCCTL_CONTEXT
WINAPI
CertCreateCTLContext(
IN DWORD dwMsgAndCertEncodingType,
IN const BYTE *pbCtlEncoded,
IN DWORD cbCtlEncoded
);
//+-------------------------------------------------------------------------
// Free a CTL context
//
// There needs to be a corresponding free for each context obtained by a
// get, duplicate or create.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertFreeCTLContext(
IN PCCTL_CONTEXT pCtlContext
);
//+-------------------------------------------------------------------------
// Set the property for the specified CTL context.
//
// Same Property Ids and semantics as CertSetCertificateContextProperty.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertSetCTLContextProperty(
IN PCCTL_CONTEXT pCtlContext,
IN DWORD dwPropId,
IN DWORD dwFlags,
IN const void *pvData
);
//+-------------------------------------------------------------------------
// Get the property for the specified CTL context.
//
// Same Property Ids and semantics as CertGetCertificateContextProperty.
//
// CERT_SHA1_HASH_PROP_ID or CERT_NEXT_UPDATE_LOCATION_PROP_ID are the
// predefined properties of most interest.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertGetCTLContextProperty(
IN PCCTL_CONTEXT pCtlContext,
IN DWORD dwPropId,
OUT void *pvData,
IN OUT DWORD *pcbData
);
//+-------------------------------------------------------------------------
// Enumerate the properties for the specified CTL context.
//--------------------------------------------------------------------------
WINCRYPT32API
DWORD
WINAPI
CertEnumCTLContextProperties(
IN PCCTL_CONTEXT pCtlContext,
IN DWORD dwPropId
);
//+-------------------------------------------------------------------------
// Enumerate the CTL contexts in the store.
//
// If a CTL isn't found, NULL is returned.
// Otherwise, a pointer to a read only CTL_CONTEXT is returned. CTL_CONTEXT
// must be freed by calling CertFreeCTLContext or is freed when passed as the
// pPrevCtlContext on a subsequent call. CertDuplicateCTLContext
// can be called to make a duplicate.
//
// pPrevCtlContext MUST BE NULL to enumerate the first
// CTL in the store. Successive CTLs are enumerated by setting
// pPrevCtlContext to the CTL_CONTEXT returned by a previous call.
//
// NOTE: a NON-NULL pPrevCtlContext is always CertFreeCTLContext'ed by
// this function, even for an error.
//--------------------------------------------------------------------------
WINCRYPT32API
PCCTL_CONTEXT
WINAPI
CertEnumCTLsInStore(
IN HCERTSTORE hCertStore,
IN PCCTL_CONTEXT pPrevCtlContext
);
//+-------------------------------------------------------------------------
// Attempt to find the specified subject in the CTL.
//
// For CTL_CERT_SUBJECT_TYPE, pvSubject points to a CERT_CONTEXT. The CTL's
// SubjectAlgorithm is examined to determine the representation of the
// subject's identity. Initially, only SHA1 or MD5 hash will be supported.
// The appropriate hash property is obtained from the CERT_CONTEXT.
//
// For CTL_ANY_SUBJECT_TYPE, pvSubject points to the CTL_ANY_SUBJECT_INFO
// structure which contains the SubjectAlgorithm to be matched in the CTL
// and the SubjectIdentifer to be matched in one of the CTL entries.
//
// The certificate's hash or the CTL_ANY_SUBJECT_INFO's SubjectIdentifier
// is used as the key in searching the subject entries. A binary
// memory comparison is done between the key and the entry's SubjectIdentifer.
//
// dwEncodingType isn't used for either of the above SubjectTypes.
//--------------------------------------------------------------------------
WINCRYPT32API
PCTL_ENTRY
WINAPI
CertFindSubjectInCTL(
IN DWORD dwEncodingType,
IN DWORD dwSubjectType,
IN void *pvSubject,
IN PCCTL_CONTEXT pCtlContext,
IN DWORD dwFlags
);
// Subject Types:
// CTL_ANY_SUBJECT_TYPE, pvSubject points to following CTL_ANY_SUBJECT_INFO.
// CTL_CERT_SUBJECT_TYPE, pvSubject points to CERT_CONTEXT.
#define CTL_ANY_SUBJECT_TYPE 1
#define CTL_CERT_SUBJECT_TYPE 2
typedef struct _CTL_ANY_SUBJECT_INFO {
CRYPT_ALGORITHM_IDENTIFIER SubjectAlgorithm;
CRYPT_DATA_BLOB SubjectIdentifier;
} CTL_ANY_SUBJECT_INFO, *PCTL_ANY_SUBJECT_INFO;
//+-------------------------------------------------------------------------
// Find the first or next CTL context in the store.
//
// The CTL is found according to the dwFindType and its pvFindPara.
// See below for a list of the find types and its parameters.
//
// Currently dwFindFlags isn't used and must be set to 0.
//
// Usage of dwMsgAndCertEncodingType depends on the dwFindType.
//
// If the first or next CTL isn't found, NULL is returned.
// Otherwise, a pointer to a read only CTL_CONTEXT is returned. CTL_CONTEXT
// must be freed by calling CertFreeCTLContext or is freed when passed as the
// pPrevCtlContext on a subsequent call. CertDuplicateCTLContext
// can be called to make a duplicate.
//
// pPrevCtlContext MUST BE NULL on the first
// call to find the CTL. To find the next CTL, the
// pPrevCtlContext is set to the CTL_CONTEXT returned by a previous call.
//
// NOTE: a NON-NULL pPrevCtlContext is always CertFreeCTLContext'ed by
// this function, even for an error.
//--------------------------------------------------------------------------
WINCRYPT32API
PCCTL_CONTEXT
WINAPI
CertFindCTLInStore(
IN HCERTSTORE hCertStore,
IN DWORD dwMsgAndCertEncodingType,
IN DWORD dwFindFlags,
IN DWORD dwFindType,
IN const void *pvFindPara,
IN PCCTL_CONTEXT pPrevCtlContext
);
#define CTL_FIND_ANY 0
#define CTL_FIND_SHA1_HASH 1
#define CTL_FIND_MD5_HASH 2
#define CTL_FIND_USAGE 3
#define CTL_FIND_SUBJECT 4
#define CTL_FIND_EXISTING 5
typedef struct _CTL_FIND_USAGE_PARA {
DWORD cbSize;
CTL_USAGE SubjectUsage; // optional
CRYPT_DATA_BLOB ListIdentifier; // optional
PCERT_INFO pSigner; // optional
} CTL_FIND_USAGE_PARA, *PCTL_FIND_USAGE_PARA;
#define CTL_FIND_NO_LIST_ID_CBDATA 0xFFFFFFFF
#define CTL_FIND_NO_SIGNER_PTR ((PCERT_INFO) -1)
#define CTL_FIND_SAME_USAGE_FLAG 0x1
typedef struct _CTL_FIND_SUBJECT_PARA {
DWORD cbSize;
PCTL_FIND_USAGE_PARA pUsagePara; // optional
DWORD dwSubjectType;
void *pvSubject;
} CTL_FIND_SUBJECT_PARA, *PCTL_FIND_SUBJECT_PARA;
//+-------------------------------------------------------------------------
// CTL_FIND_ANY
//
// Find any CTL.
//
// pvFindPara isn't used.
//--------------------------------------------------------------------------
//+-------------------------------------------------------------------------
// CTL_FIND_SHA1_HASH
// CTL_FIND_MD5_HASH
//
// Find a CTL with the specified hash.
//
// pvFindPara points to a CRYPT_HASH_BLOB.
//--------------------------------------------------------------------------
//+-------------------------------------------------------------------------
// CTL_FIND_USAGE
//
// Find a CTL having the specified usage identifiers, list identifier or
// signer. The CertEncodingType of the signer is obtained from the
// dwMsgAndCertEncodingType parameter.
//
// pvFindPara points to a CTL_FIND_USAGE_PARA data structure. The
// SubjectUsage.cUsageIdentifer can be 0 to match any usage. The
// ListIdentifier.cbData can be 0 to match any list identifier. To only match
// CTLs without a ListIdentifier, cbData must be set to
// CTL_FIND_NO_LIST_ID_CBDATA. pSigner can be NULL to match any signer. Only
// the Issuer and SerialNumber fields of the pSigner's PCERT_INFO are used.
// To only match CTLs without a signer, pSigner must be set to
// CTL_FIND_NO_SIGNER_PTR.
//
// The CTL_FIND_SAME_USAGE_FLAG can be set in dwFindFlags to
// only match CTLs with the same usage identifiers. CTLs having additional
// usage identifiers aren't matched. For example, if only "1.2.3" is specified
// in CTL_FIND_USAGE_PARA, then, for a match, the CTL must only contain
// "1.2.3" and not any additional usage identifers.
//--------------------------------------------------------------------------
//+-------------------------------------------------------------------------
// CTL_FIND_SUBJECT
//
// Find a CTL having the specified subject. CertFindSubjectInCTL can be
// called to get a pointer to the subject's entry in the CTL. pUsagePara can
// optionally be set to enable the above CTL_FIND_USAGE matching.
//
// pvFindPara points to a CTL_FIND_SUBJECT_PARA data structure.
//--------------------------------------------------------------------------
//+-------------------------------------------------------------------------
// Add the encoded CTL to the store according to the specified
// disposition option.
//
// Makes a copy of the encoded CTL before adding to the store.
//
// dwAddDispostion specifies the action to take if the CTL
// already exists in the store. See CertAddEncodedCertificateToStore for a
// list of and actions taken.
//
// Compares the CTL's SubjectUsage, ListIdentifier and any of its signers
// to determine if the CTL already exists in the store.
//
// ppCtlContext can be NULL, indicating the caller isn't interested
// in getting the CTL_CONTEXT of the added or existing CTL.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertAddEncodedCTLToStore(
IN HCERTSTORE hCertStore,
IN DWORD dwMsgAndCertEncodingType,
IN const BYTE *pbCtlEncoded,
IN DWORD cbCtlEncoded,
IN DWORD dwAddDisposition,
OUT OPTIONAL PCCTL_CONTEXT *ppCtlContext
);
//+-------------------------------------------------------------------------
// Add the CTL context to the store according to the specified
// disposition option.
//
// In addition to the encoded CTL, the context's properties are
// also copied. Note, the CERT_KEY_CONTEXT_PROP_ID property (and its
// CERT_KEY_PROV_HANDLE_PROP_ID or CERT_KEY_SPEC_PROP_ID) isn't copied.
//
// Makes a copy of the encoded CTL before adding to the store.
//
// dwAddDispostion specifies the action to take if the CTL
// already exists in the store. See CertAddCertificateContextToStore for a
// list of and actions taken.
//
// Compares the CTL's SubjectUsage, ListIdentifier and any of its signers
// to determine if the CTL already exists in the store.
//
// ppStoreContext can be NULL, indicating the caller isn't interested
// in getting the CTL_CONTEXT of the added or existing CTL.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertAddCTLContextToStore(
IN HCERTSTORE hCertStore,
IN PCCTL_CONTEXT pCtlContext,
IN DWORD dwAddDisposition,
OUT OPTIONAL PCCTL_CONTEXT *ppStoreContext
);
//+-------------------------------------------------------------------------
// Serialize the CTL context's encoded CTL and its properties.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertSerializeCTLStoreElement(
IN PCCTL_CONTEXT pCtlContext,
IN DWORD dwFlags,
OUT BYTE *pbElement,
IN OUT DWORD *pcbElement
);
//+-------------------------------------------------------------------------
// Delete the specified CTL from the store.
//
// All subsequent gets for the CTL will fail. However,
// memory allocated for the CTL isn't freed until all of its contexts
// have also been freed.
//
// The pCtlContext is obtained from a get or duplicate.
//
// NOTE: the pCtlContext is always CertFreeCTLContext'ed by
// this function, even for an error.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertDeleteCTLFromStore(
IN PCCTL_CONTEXT pCtlContext
);
WINCRYPT32API
BOOL
WINAPI
CertAddCertificateLinkToStore(
IN HCERTSTORE hCertStore,
IN PCCERT_CONTEXT pCertContext,
IN DWORD dwAddDisposition,
OUT OPTIONAL PCCERT_CONTEXT *ppStoreContext
);
WINCRYPT32API
BOOL
WINAPI
CertAddCRLLinkToStore(
IN HCERTSTORE hCertStore,
IN PCCRL_CONTEXT pCrlContext,
IN DWORD dwAddDisposition,
OUT OPTIONAL PCCRL_CONTEXT *ppStoreContext
);
WINCRYPT32API
BOOL
WINAPI
CertAddCTLLinkToStore(
IN HCERTSTORE hCertStore,
IN PCCTL_CONTEXT pCtlContext,
IN DWORD dwAddDisposition,
OUT OPTIONAL PCCTL_CONTEXT *ppStoreContext
);
WINCRYPT32API
BOOL
WINAPI
CertAddStoreToCollection(
IN HCERTSTORE hCollectionStore,
IN OPTIONAL HCERTSTORE hSiblingStore,
IN DWORD dwUpdateFlags,
IN DWORD dwPriority
);
WINCRYPT32API
void
WINAPI
CertRemoveStoreFromCollection(
IN HCERTSTORE hCollectionStore,
IN HCERTSTORE hSiblingStore
);
WINCRYPT32API
BOOL
WINAPI
CertControlStore(
IN HCERTSTORE hCertStore,
IN DWORD dwFlags,
IN DWORD dwCtrlType,
IN void const *pvCtrlPara
);
//+-------------------------------------------------------------------------
// Certificate Store control types
//--------------------------------------------------------------------------
#define CERT_STORE_CTRL_RESYNC 1
#define CERT_STORE_CTRL_NOTIFY_CHANGE 2
#define CERT_STORE_CTRL_COMMIT 3
#define CERT_STORE_CTRL_AUTO_RESYNC 4
#define CERT_STORE_CTRL_CANCEL_NOTIFY 5
#define CERT_STORE_CTRL_INHIBIT_DUPLICATE_HANDLE_FLAG 0x1
//+-------------------------------------------------------------------------
// CERT_STORE_CTRL_RESYNC
//
// Re-synchronize the store.
//
// The pvCtrlPara points to the event HANDLE to be signaled on
// the next store change. Normally, this would be the same
// event HANDLE passed to CERT_STORE_CTRL_NOTIFY_CHANGE during initialization.
//
// If pvCtrlPara is NULL, no events are re-armed.
//
// By default the event HANDLE is DuplicateHandle'd.
// CERT_STORE_CTRL_INHIBIT_DUPLICATE_HANDLE_FLAG can be set in dwFlags
// to inhibit a DupicateHandle of the event HANDLE. If this flag
// is set, then, CertControlStore(CERT_STORE_CTRL_CANCEL_NOTIFY) must be
// called for this event HANDLE before closing the hCertStore.
//--------------------------------------------------------------------------
//+-------------------------------------------------------------------------
// CERT_STORE_CTRL_NOTIFY_CHANGE
//
// Signal the event when the underlying store is changed.
//
// pvCtrlPara points to the event HANDLE to be signaled.
//
// pvCtrlPara can be NULL to inform the store of a subsequent
// CERT_STORE_CTRL_RESYNC and allow it to optimize by only doing a resync
// if the store has changed. For the registry based stores, an internal
// notify change event is created and registered to be signaled.
//
// Recommend calling CERT_STORE_CTRL_NOTIFY_CHANGE once for each event to
// be passed to CERT_STORE_CTRL_RESYNC. This should only happen after
// the event has been created. Not after each time the event is signaled.
//
// By default the event HANDLE is DuplicateHandle'd.
// CERT_STORE_CTRL_INHIBIT_DUPLICATE_HANDLE_FLAG can be set in dwFlags
// to inhibit a DupicateHandle of the event HANDLE. If this flag
// is set, then, CertControlStore(CERT_STORE_CTRL_CANCEL_NOTIFY) must be
// called for this event HANDLE before closing the hCertStore.
//--------------------------------------------------------------------------
//+-------------------------------------------------------------------------
// CERT_STORE_CTRL_CANCEL_NOTIFY
//
// Cancel notification signaling of the event HANDLE passed in a previous
// CERT_STORE_CTRL_NOTIFY_CHANGE or CERT_STORE_CTRL_RESYNC.
//
// pvCtrlPara points to the event HANDLE to be canceled.
//--------------------------------------------------------------------------
//+-------------------------------------------------------------------------
// CERT_STORE_CTRL_AUTO_RESYNC
//
// At the start of every enumeration or find store API call, check if the
// underlying store has changed. If it has changed, re-synchronize.
//
// This check is only done in the enumeration or find APIs when the
// pPrevContext is NULL.
//
// The pvCtrlPara isn't used and must be set to NULL.
//--------------------------------------------------------------------------
//+-------------------------------------------------------------------------
// CERT_STORE_CTRL_COMMIT
//
// If any changes have been to the cached store, they are committed to
// persisted storage. If no changes have been made since the store was
// opened or the last commit, this call is ignored. May also be ignored by
// store providers that persist changes immediately.
//
// CERT_STORE_CTRL_COMMIT_FORCE_FLAG can be set to force the store
// to be committed even if it hasn't been touched.
//
// CERT_STORE_CTRL_COMMIT_CLEAR_FLAG can be set to inhibit a commit on
// store close.
//--------------------------------------------------------------------------
#define CERT_STORE_CTRL_COMMIT_FORCE_FLAG 0x1
#define CERT_STORE_CTRL_COMMIT_CLEAR_FLAG 0x2
//+=========================================================================
// Cert Store Property Defines and APIs
//==========================================================================
//+-------------------------------------------------------------------------
// Store property IDs. This is a property applicable to the entire store.
// Its not a property on an individual certificate, CRL or CTL context.
//
// Currently, no store properties are persisted. (This differs from
// most context properties which are persisted.)
//
// See CertSetStoreProperty or CertGetStoreProperty for usage information.
//
// Note, the range for predefined store properties should be outside
// the range of predefined context properties. We will start at 4096.
//--------------------------------------------------------------------------
#define CERT_STORE_LOCALIZED_NAME_PROP_ID 0x1000
//+-------------------------------------------------------------------------
// Set a store property.
//
// The type definition for pvData depends on the dwPropId value.
// CERT_STORE_LOCALIZED_NAME_PROP_ID - localized name of the store.
// pvData points to a CRYPT_DATA_BLOB. pbData is a pointer to a NULL
// terminated unicode, wide character string.
// cbData = (wcslen((LPWSTR) pbData) + 1) * sizeof(WCHAR).
//
// For all the other PROP_IDs: an encoded PCRYPT_DATA_BLOB is passed in pvData.
//
// If the property already exists, then, the old value is deleted and silently
// replaced. Setting, pvData to NULL, deletes the property.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertSetStoreProperty(
IN HCERTSTORE hCertStore,
IN DWORD dwPropId,
IN DWORD dwFlags,
IN const void *pvData
);
//+-------------------------------------------------------------------------
// Get a store property.
//
// The type definition for pvData depends on the dwPropId value.
// CERT_STORE_LOCALIZED_NAME_PROP_ID - localized name of the store.
// pvData points to a NULL terminated unicode, wide character string.
// cbData = (wcslen((LPWSTR) pvData) + 1) * sizeof(WCHAR).
//
// For all other PROP_IDs, pvData points to an array of bytes.
//
// If the property doesn't exist, returns FALSE and sets LastError to
// CRYPT_E_NOT_FOUND.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertGetStoreProperty(
IN HCERTSTORE hCertStore,
IN DWORD dwPropId,
OUT void *pvData,
IN OUT DWORD *pcbData
);
typedef struct _CERT_CREATE_CONTEXT_PARA {
DWORD cbSize;
PFN_CRYPT_FREE pfnFree; // OPTIONAL
void *pvFree; // OPTIONAL
} CERT_CREATE_CONTEXT_PARA, *PCERT_CREATE_CONTEXT_PARA;
//+-------------------------------------------------------------------------
// Creates the specified context from the encoded bytes. The created
// context isn't put in a store.
//
// dwContextType values:
// CERT_STORE_CERTIFICATE_CONTEXT
// CERT_STORE_CRL_CONTEXT
// CERT_STORE_CTL_CONTEXT
//
// If CERT_CREATE_CONTEXT_NOCOPY_FLAG is set, the created context points
// directly to the pbEncoded instead of an allocated copy. See flag
// definition for more details.
//
// If CERT_CREATE_CONTEXT_SORTED_FLAG is set, the context is created
// with sorted entries. This flag may only be set for CERT_STORE_CTL_CONTEXT.
// Setting this flag implicitly sets CERT_CREATE_CONTEXT_NO_HCRYPTMSG_FLAG and
// CERT_CREATE_CONTEXT_NO_ENTRY_FLAG. See flag definition for
// more details.
//
// If CERT_CREATE_CONTEXT_NO_HCRYPTMSG_FLAG is set, the context is created
// without creating a HCRYPTMSG handle for the context. This flag may only be
// set for CERT_STORE_CTL_CONTEXT. See flag definition for more details.
//
// If CERT_CREATE_CONTEXT_NO_ENTRY_FLAG is set, the context is created
// without decoding the entries. This flag may only be set for
// CERT_STORE_CTL_CONTEXT. See flag definition for more details.
//
// If unable to decode and create the context, NULL is returned.
// Otherwise, a pointer to a read only CERT_CONTEXT, CRL_CONTEXT or
// CTL_CONTEXT is returned. The context must be freed by the appropriate
// free context API. The context can be duplicated by calling the
// appropriate duplicate context API.
//--------------------------------------------------------------------------
WINCRYPT32API
const void *
WINAPI
CertCreateContext(
IN DWORD dwContextType,
IN DWORD dwEncodingType,
IN const BYTE *pbEncoded,
IN DWORD cbEncoded,
IN DWORD dwFlags,
IN OPTIONAL PCERT_CREATE_CONTEXT_PARA pCreatePara
);
// When the following flag is set, the created context points directly to the
// pbEncoded instead of an allocated copy. If pCreatePara and
// pCreatePara->pfnFree are non-NULL, then, pfnFree is called to free
// the pbEncoded when the context is last freed. Otherwise, no attempt is
// made to free the pbEncoded. If pCreatePara->pvFree is non-NULL, then its
// passed to pfnFree instead of pbEncoded.
//
// Note, if CertCreateContext fails, pfnFree is still called.
#define CERT_CREATE_CONTEXT_NOCOPY_FLAG 0x1
// When the following flag is set, a context with sorted entries is created.
// Currently only applicable to a CTL context.
//
// For CTLs: the cCTLEntry in the returned CTL_INFO is always
// 0. CertFindSubjectInSortedCTL and CertEnumSubjectInSortedCTL must be called
// to find or enumerate the CTL entries.
//
// The Sorted CTL TrustedSubjects extension isn't returned in the created
// context's CTL_INFO.
#define CERT_CREATE_CONTEXT_SORTED_FLAG 0x2
// By default when a CTL context is created, a HCRYPTMSG handle to its
// SignedData message is created. This flag can be set to improve performance
// by not creating the HCRYPTMSG handle.
//
// This flag is only applicable to a CTL context.
#define CERT_CREATE_CONTEXT_NO_HCRYPTMSG_FLAG 0x4
// By default when a CTL context is created, its entries are decoded.
// This flag can be set to improve performance by not decoding the
// entries.
//
// This flag is only applicable to a CTL context.
#define CERT_CREATE_CONTEXT_NO_ENTRY_FLAG 0x8
//+=========================================================================
// Certificate System Store Data Structures and APIs
//==========================================================================
//+-------------------------------------------------------------------------
// System Store Information
//
// Currently, no system store information is persisted.
//--------------------------------------------------------------------------
typedef struct _CERT_SYSTEM_STORE_INFO {
DWORD cbSize;
} CERT_SYSTEM_STORE_INFO, *PCERT_SYSTEM_STORE_INFO;
//+-------------------------------------------------------------------------
// Physical Store Information
//
// The Open fields are passed directly to CertOpenStore() to open
// the physical store.
//
// By default all system stores located in the registry have an
// implicit SystemRegistry physical store that is opened. To disable the
// opening of this store, the SystemRegistry
// physical store corresponding to the System store must be registered with
// CERT_PHYSICAL_STORE_OPEN_DISABLE_FLAG set in dwFlags. Alternatively,
// a physical store with the name of ".Default" may be registered.
//
// Depending on the store location and store name, additional predefined
// physical stores may be opened. For example, system stores in
// CURRENT_USER have the predefined physical store, .LocalMachine.
// To disable the opening of these predefined physical stores, the
// corresponding physical store must be registered with
// CERT_PHYSICAL_STORE_OPEN_DISABLE_FLAG set in dwFlags.
//
// The CERT_PHYSICAL_STORE_ADD_ENABLE_FLAG must be set in dwFlags
// to enable the adding of a context to the store.
//
// When a system store is opened via the SERVICES or USERS store location,
// the ServiceName is prepended to the OpenParameters
// for CERT_SYSTEM_STORE_CURRENT_USER or CERT_SYSTEM_STORE_CURRENT_SERVICE
// physical stores and the dwOpenFlags store location is changed to
// CERT_SYSTEM_STORE_USERS or CERT_SYSTEM_STORE_SERVICES.
//
// By default the SYSTEM, SYSTEM_REGISTRY and PHYSICAL provider
// stores are also opened remotely when the outer system store is opened.
// The CERT_PHYSICAL_STORE_REMOTE_OPEN_DISABLE_FLAG may be set in dwFlags
// to disable remote opens.
//
// When opened remotely, the \ComputerName is implicitly prepended to the
// OpenParameters for the SYSTEM, SYSTEM_REGISTRY and PHYSICAL provider types.
// To also prepend the \ComputerName to other provider types, set the
// CERT_PHYSICAL_STORE_INSERT_COMPUTER_NAME_ENABLE_FLAG in dwFlags.
//
// When the system store is opened, its physical stores are ordered
// according to the dwPriority. A larger dwPriority indicates higher priority.
//--------------------------------------------------------------------------
typedef struct _CERT_PHYSICAL_STORE_INFO {
DWORD cbSize;
LPSTR pszOpenStoreProvider; // REG_SZ
DWORD dwOpenEncodingType; // REG_DWORD
DWORD dwOpenFlags; // REG_DWORD
CRYPT_DATA_BLOB OpenParameters; // REG_BINARY
DWORD dwFlags; // REG_DWORD
DWORD dwPriority; // REG_DWORD
} CERT_PHYSICAL_STORE_INFO, *PCERT_PHYSICAL_STORE_INFO;
//+-------------------------------------------------------------------------
// Physical Store Information dwFlags
//--------------------------------------------------------------------------
#define CERT_PHYSICAL_STORE_ADD_ENABLE_FLAG 0x1
#define CERT_PHYSICAL_STORE_OPEN_DISABLE_FLAG 0x2
#define CERT_PHYSICAL_STORE_REMOTE_OPEN_DISABLE_FLAG 0x4
#define CERT_PHYSICAL_STORE_INSERT_COMPUTER_NAME_ENABLE_FLAG 0x8
//+-------------------------------------------------------------------------
// Register a system store.
//
// The upper word of the dwFlags parameter is used to specify the location of
// the system store.
//
// If CERT_SYSTEM_STORE_RELOCATE_FLAG is set in dwFlags, pvSystemStore
// points to a CERT_SYSTEM_STORE_RELOCATE_PARA data structure. Otherwise,
// pvSystemStore points to a null terminated UNICODE string.
//
// The CERT_SYSTEM_STORE_SERVICES or CERT_SYSTEM_STORE_USERS system store
// name must be prefixed with the ServiceName or UserName. For example,
// "ServiceNameTrust".
//
// Stores on remote computers can be registered for the
// CERT_SYSTEM_STORE_LOCAL_MACHINE, CERT_SYSTEM_STORE_SERVICES,
// CERT_SYSTEM_STORE_USERS, CERT_SYSTEM_STORE_LOCAL_MACHINE_GROUP_POLICY
// or CERT_SYSTEM_STORE_LOCAL_MACHINE_ENTERPRISE
// locations by prepending the computer name. For example, a remote
// local machine store is registered via "\ComputerNameTrust" or
// "ComputerNameTrust". A remote service store is registered via
// "\ComputerNameServiceNameTrust". The leading "\" backslashes are
// optional in the ComputerName.
//
// Set CERT_STORE_CREATE_NEW_FLAG to cause a failure if the system store
// already exists in the store location.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertRegisterSystemStore(
IN const void *pvSystemStore,
IN DWORD dwFlags,
IN PCERT_SYSTEM_STORE_INFO pStoreInfo,
IN OPTIONAL void *pvReserved
);
//+-------------------------------------------------------------------------
// Register a physical store for the specified system store.
//
// The upper word of the dwFlags parameter is used to specify the location of
// the system store.
//
// If CERT_SYSTEM_STORE_RELOCATE_FLAG is set in dwFlags, pvSystemStore
// points to a CERT_SYSTEM_STORE_RELOCATE_PARA data structure. Otherwise,
// pvSystemStore points to a null terminated UNICODE string.
//
// See CertRegisterSystemStore for details on prepending a ServiceName
// and/or ComputerName to the system store name.
//
// Set CERT_STORE_CREATE_NEW_FLAG to cause a failure if the physical store
// already exists in the system store.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertRegisterPhysicalStore(
IN const void *pvSystemStore,
IN DWORD dwFlags,
IN LPCWSTR pwszStoreName,
IN PCERT_PHYSICAL_STORE_INFO pStoreInfo,
IN OPTIONAL void *pvReserved
);
//+-------------------------------------------------------------------------
// Unregister the specified system store.
//
// The upper word of the dwFlags parameter is used to specify the location of
// the system store.
//
// If CERT_SYSTEM_STORE_RELOCATE_FLAG is set in dwFlags, pvSystemStore
// points to a CERT_SYSTEM_STORE_RELOCATE_PARA data structure. Otherwise,
// pvSystemStore points to a null terminated UNICODE string.
//
// See CertRegisterSystemStore for details on prepending a ServiceName
// and/or ComputerName to the system store name.
//
// CERT_STORE_DELETE_FLAG can optionally be set in dwFlags.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertUnregisterSystemStore(
IN const void *pvSystemStore,
IN DWORD dwFlags
);
//+-------------------------------------------------------------------------
// Unregister the physical store from the specified system store.
//
// The upper word of the dwFlags parameter is used to specify the location of
// the system store.
//
// If CERT_SYSTEM_STORE_RELOCATE_FLAG is set in dwFlags, pvSystemStore
// points to a CERT_SYSTEM_STORE_RELOCATE_PARA data structure. Otherwise,
// pvSystemStore points to a null terminated UNICODE string.
//
// See CertRegisterSystemStore for details on prepending a ServiceName
// and/or ComputerName to the system store name.
//
// CERT_STORE_DELETE_FLAG can optionally be set in dwFlags.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertUnregisterPhysicalStore(
IN const void *pvSystemStore,
IN DWORD dwFlags,
IN LPCWSTR pwszStoreName
);
//+-------------------------------------------------------------------------
// Enum callbacks
//
// The CERT_SYSTEM_STORE_LOCATION_MASK bits in the dwFlags parameter
// specifies the location of the system store
//
// If CERT_SYSTEM_STORE_RELOCATE_FLAG is set in dwFlags, pvSystemStore
// points to a CERT_SYSTEM_STORE_RELOCATE_PARA data structure. Otherwise,
// pvSystemStore points to a null terminated UNICODE string.
//
// The callback returns FALSE and sets LAST_ERROR to stop the enumeration.
// The LAST_ERROR is returned to the caller of the enumeration.
//
// The pvSystemStore passed to the callback has leading ComputerName and/or
// ServiceName prefixes where appropriate.
//--------------------------------------------------------------------------
typedef BOOL (WINAPI *PFN_CERT_ENUM_SYSTEM_STORE_LOCATION)(
IN LPCWSTR pwszStoreLocation,
IN DWORD dwFlags,
IN OPTIONAL void *pvReserved,
IN OPTIONAL void *pvArg
);
typedef BOOL (WINAPI *PFN_CERT_ENUM_SYSTEM_STORE)(
IN const void *pvSystemStore,
IN DWORD dwFlags,
IN PCERT_SYSTEM_STORE_INFO pStoreInfo,
IN OPTIONAL void *pvReserved,
IN OPTIONAL void *pvArg
);
typedef BOOL (WINAPI *PFN_CERT_ENUM_PHYSICAL_STORE)(
IN const void *pvSystemStore,
IN DWORD dwFlags,
IN LPCWSTR pwszStoreName,
IN PCERT_PHYSICAL_STORE_INFO pStoreInfo,
IN OPTIONAL void *pvReserved,
IN OPTIONAL void *pvArg
);
// In the PFN_CERT_ENUM_PHYSICAL_STORE callback the following flag is
// set if the physical store wasn't registered and is an implicitly created
// predefined physical store.
#define CERT_PHYSICAL_STORE_PREDEFINED_ENUM_FLAG 0x1
// Names of implicitly created predefined physical stores
#define CERT_PHYSICAL_STORE_DEFAULT_NAME L".Default"
#define CERT_PHYSICAL_STORE_GROUP_POLICY_NAME L".GroupPolicy"
#define CERT_PHYSICAL_STORE_LOCAL_MACHINE_NAME L".LocalMachine"
#define CERT_PHYSICAL_STORE_DS_USER_CERTIFICATE_NAME L".UserCertificate"
#define CERT_PHYSICAL_STORE_LOCAL_MACHINE_GROUP_POLICY_NAME
L".LocalMachineGroupPolicy"
#define CERT_PHYSICAL_STORE_ENTERPRISE_NAME L".Enterprise"
#define CERT_PHYSICAL_STORE_AUTH_ROOT_NAME L".AuthRoot"
//+-------------------------------------------------------------------------
// Enumerate the system store locations.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertEnumSystemStoreLocation(
IN DWORD dwFlags,
IN void *pvArg,
IN PFN_CERT_ENUM_SYSTEM_STORE_LOCATION pfnEnum
);
//+-------------------------------------------------------------------------
// Enumerate the system stores.
//
// The upper word of the dwFlags parameter is used to specify the location of
// the system store.
//
// If CERT_SYSTEM_STORE_RELOCATE_FLAG is set in dwFlags,
// pvSystemStoreLocationPara points to a CERT_SYSTEM_STORE_RELOCATE_PARA
// data structure. Otherwise, pvSystemStoreLocationPara points to a null
// terminated UNICODE string.
//
// For CERT_SYSTEM_STORE_LOCAL_MACHINE,
// CERT_SYSTEM_STORE_LOCAL_MACHINE_GROUP_POLICY or
// CERT_SYSTEM_STORE_LOCAL_MACHINE_ENTERPRISE, pvSystemStoreLocationPara can
// optionally be set to a unicode computer name for enumerating local machine
// stores on a remote computer. For example, "\ComputerName" or
// "ComputerName". The leading "\" backslashes are optional in the
// ComputerName.
//
// For CERT_SYSTEM_STORE_SERVICES or CERT_SYSTEM_STORE_USERS,
// if pvSystemStoreLocationPara is NULL, then,
// enumerates both the service/user names and the stores for each service/user
// name. Otherwise, pvSystemStoreLocationPara is a unicode string specifying a
// remote computer name and/or service/user name. For example:
// "ServiceName"
// "\ComputerName" or "ComputerName"
// "ComputerNameServiceName"
// Note, if only the ComputerName is specified, then, it must have either
// the leading "\" backslashes or a trailing backslash. Otherwise, its
// interpretted as the ServiceName or UserName.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertEnumSystemStore(
IN DWORD dwFlags,
IN OPTIONAL void *pvSystemStoreLocationPara,
IN void *pvArg,
IN PFN_CERT_ENUM_SYSTEM_STORE pfnEnum
);
//+-------------------------------------------------------------------------
// Enumerate the physical stores for the specified system store.
//
// The upper word of the dwFlags parameter is used to specify the location of
// the system store.
//
// If CERT_SYSTEM_STORE_RELOCATE_FLAG is set in dwFlags, pvSystemStore
// points to a CERT_SYSTEM_STORE_RELOCATE_PARA data structure. Otherwise,
// pvSystemStore points to a null terminated UNICODE string.
//
// See CertRegisterSystemStore for details on prepending a ServiceName
// and/or ComputerName to the system store name.
//
// If the system store location only supports system stores and doesn't
// support physical stores, LastError is set to ERROR_CALL_NOT_IMPLEMENTED.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertEnumPhysicalStore(
IN const void *pvSystemStore,
IN DWORD dwFlags,
IN void *pvArg,
IN PFN_CERT_ENUM_PHYSICAL_STORE pfnEnum
);
//+-------------------------------------------------------------------------
// Certificate System Store Installable Functions
//
// The CERT_SYSTEM_STORE_LOCATION_MASK bits in the dwFlags parameter passed
// to the CertOpenStore(for "System", "SystemRegistry" or "Physical"
// Provider), CertRegisterSystemStore,
// CertUnregisterSystemStore, CertEnumSystemStore, CertRegisterPhysicalStore,
// CertUnregisterPhysicalStore and CertEnumPhysicalStore APIs is used as the
// constant pszOID value passed to the OID installable functions.
// Therefore, the pszOID is restricted to a constant <= (LPCSTR) 0x0FFF.
//
// The EncodingType is 0.
//--------------------------------------------------------------------------
// Installable System Store Provider OID pszFuncNames.
#define CRYPT_OID_OPEN_SYSTEM_STORE_PROV_FUNC "CertDllOpenSystemStoreProv"
#define CRYPT_OID_REGISTER_SYSTEM_STORE_FUNC "CertDllRegisterSystemStore"
#define CRYPT_OID_UNREGISTER_SYSTEM_STORE_FUNC "CertDllUnregisterSystemStore"
#define CRYPT_OID_ENUM_SYSTEM_STORE_FUNC "CertDllEnumSystemStore"
#define CRYPT_OID_REGISTER_PHYSICAL_STORE_FUNC "CertDllRegisterPhysicalStore"
#define CRYPT_OID_UNREGISTER_PHYSICAL_STORE_FUNC "CertDllUnregisterPhysicalStore"
#define CRYPT_OID_ENUM_PHYSICAL_STORE_FUNC "CertDllEnumPhysicalStore"
// CertDllOpenSystemStoreProv has the same function signature as the
// installable "CertDllOpenStoreProv" function. See CertOpenStore for
// more details.
// CertDllRegisterSystemStore has the same function signature as
// CertRegisterSystemStore.
//
// The "SystemStoreLocation" REG_SZ value must also be set for registered
// CertDllEnumSystemStore OID functions.
#define CRYPT_OID_SYSTEM_STORE_LOCATION_VALUE_NAME L"SystemStoreLocation"
// The remaining Register, Enum and Unregister OID installable functions
// have the same signature as their Cert Store API counterpart.
//+=========================================================================
// Enhanced Key Usage Helper Functions
//==========================================================================
//+-------------------------------------------------------------------------
// Get the enhanced key usage extension or property from the certificate
// and decode.
//
// If the CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAG is set, then, only get the
// extension.
//
// If the CERT_FIND_PROP_ONLY_ENHKEY_USAGE_FLAG is set, then, only get the
// property.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertGetEnhancedKeyUsage(
IN PCCERT_CONTEXT pCertContext,
IN DWORD dwFlags,
OUT PCERT_ENHKEY_USAGE pUsage,
IN OUT DWORD *pcbUsage
);
//+-------------------------------------------------------------------------
// Set the enhanced key usage property for the certificate.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertSetEnhancedKeyUsage(
IN PCCERT_CONTEXT pCertContext,
IN PCERT_ENHKEY_USAGE pUsage
);
//+-------------------------------------------------------------------------
// Add the usage identifier to the certificate's enhanced key usage property.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertAddEnhancedKeyUsageIdentifier(
IN PCCERT_CONTEXT pCertContext,
IN LPCSTR pszUsageIdentifier
);
//+-------------------------------------------------------------------------
// Remove the usage identifier from the certificate's enhanced key usage
// property.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertRemoveEnhancedKeyUsageIdentifier(
IN PCCERT_CONTEXT pCertContext,
IN LPCSTR pszUsageIdentifier
);
//+---------------------------------------------------------------------------
//
//
// Takes an array of certs and returns an array of usages
// which consists of the intersection of the valid usages for each cert.
// If each cert is good for all possible usages then the cNumOIDs is set to -1.
//
//----------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertGetValidUsages(
IN DWORD cCerts,
IN PCCERT_CONTEXT *rghCerts,
OUT int *cNumOIDs,
OUT LPSTR *rghOIDs,
IN OUT DWORD *pcbOIDs);
//+=========================================================================
// Cryptographic Message helper functions for verifying and signing a
// CTL.
//==========================================================================
//+-------------------------------------------------------------------------
// Get and verify the signer of a cryptographic message.
//
// To verify a CTL, the hCryptMsg is obtained from the CTL_CONTEXT's
// hCryptMsg field.
//
// If CMSG_TRUSTED_SIGNER_FLAG is set, then, treat the Signer stores as being
// trusted and only search them to find the certificate corresponding to the
// signer's issuer and serial number. Otherwise, the SignerStores are
// optionally provided to supplement the message's store of certificates.
// If a signer certificate is found, its public key is used to verify
// the message signature. The CMSG_SIGNER_ONLY_FLAG can be set to
// return the signer without doing the signature verify.
//
// If CMSG_USE_SIGNER_INDEX_FLAG is set, then, only get the signer specified
// by *pdwSignerIndex. Otherwise, iterate through all the signers
// until a signer verifies or no more signers.
//
// For a verified signature, *ppSigner is updated with certificate context
// of the signer and *pdwSignerIndex is updated with the index of the signer.
// ppSigner and/or pdwSignerIndex can be NULL, indicating the caller isn't
// interested in getting the CertContext and/or index of the signer.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CryptMsgGetAndVerifySigner(
IN HCRYPTMSG hCryptMsg,
IN DWORD cSignerStore,
IN OPTIONAL HCERTSTORE *rghSignerStore,
IN DWORD dwFlags,
OUT OPTIONAL PCCERT_CONTEXT *ppSigner,
IN OUT OPTIONAL DWORD *pdwSignerIndex
);
#define CMSG_TRUSTED_SIGNER_FLAG 0x1
#define CMSG_SIGNER_ONLY_FLAG 0x2
#define CMSG_USE_SIGNER_INDEX_FLAG 0x4
//+-------------------------------------------------------------------------
// Sign an encoded CTL.
//
// The pbCtlContent can be obtained via a CTL_CONTEXT's pbCtlContent
// field or via a CryptEncodeObject(PKCS_CTL or PKCS_SORTED_CTL).
//
// CMSG_CMS_ENCAPSULATED_CTL_FLAG can be set to encode a CMS compatible
// V3 SignedData message.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CryptMsgSignCTL(
IN DWORD dwMsgEncodingType,
IN BYTE *pbCtlContent,
IN DWORD cbCtlContent,
IN PCMSG_SIGNED_ENCODE_INFO pSignInfo,
IN DWORD dwFlags,
OUT BYTE *pbEncoded,
IN OUT DWORD *pcbEncoded
);
// When set, CTL inner content is encapsulated within an OCTET STRING
#define CMSG_CMS_ENCAPSULATED_CTL_FLAG 0x00008000
//+-------------------------------------------------------------------------
// Encode the CTL and create a signed message containing the encoded CTL.
//
// Set CMSG_ENCODE_SORTED_CTL_FLAG if the CTL entries are to be sorted
// before encoding. This flag should be set, if the
// CertFindSubjectInSortedCTL or CertEnumSubjectInSortedCTL APIs will
// be called. If the identifier for the CTL entries is a hash, such as,
// MD5 or SHA1, then, CMSG_ENCODE_HASHED_SUBJECT_IDENTIFIER_FLAG should
// also be set.
//
// CMSG_CMS_ENCAPSULATED_CTL_FLAG can be set to encode a CMS compatible
// V3 SignedData message.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CryptMsgEncodeAndSignCTL(
IN DWORD dwMsgEncodingType,
IN PCTL_INFO pCtlInfo,
IN PCMSG_SIGNED_ENCODE_INFO pSignInfo,
IN DWORD dwFlags,
OUT BYTE *pbEncoded,
IN OUT DWORD *pcbEncoded
);
// The following flag is set if the CTL is to be encoded with sorted
// trusted subjects and the szOID_SORTED_CTL extension is inserted containing
// sorted offsets to the encoded subjects.
#define CMSG_ENCODE_SORTED_CTL_FLAG 0x1
// If the above sorted flag is set, then, the following flag should also
// be set if the identifier for the TrustedSubjects is a hash,
// such as, MD5 or SHA1.
#define CMSG_ENCODE_HASHED_SUBJECT_IDENTIFIER_FLAG 0x2
//+-------------------------------------------------------------------------
// Returns TRUE if the SubjectIdentifier exists in the CTL. Optionally
// returns a pointer to and byte count of the Subject's encoded attributes.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertFindSubjectInSortedCTL(
IN PCRYPT_DATA_BLOB pSubjectIdentifier,
IN PCCTL_CONTEXT pCtlContext,
IN DWORD dwFlags,
IN void *pvReserved,
OUT OPTIONAL PCRYPT_DER_BLOB pEncodedAttributes
);
//+-------------------------------------------------------------------------
// Enumerates through the sequence of TrustedSubjects in a CTL context
// created with CERT_CREATE_CONTEXT_SORTED_FLAG set.
//
// To start the enumeration, *ppvNextSubject must be NULL. Upon return,
// *ppvNextSubject is updated to point to the next TrustedSubject in
// the encoded sequence.
//
// Returns FALSE for no more subjects or invalid arguments.
//
// Note, the returned DER_BLOBs point directly into the encoded
// bytes (not allocated, and must not be freed).
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertEnumSubjectInSortedCTL(
IN PCCTL_CONTEXT pCtlContext,
IN OUT void **ppvNextSubject,
OUT OPTIONAL PCRYPT_DER_BLOB pSubjectIdentifier,
OUT OPTIONAL PCRYPT_DER_BLOB pEncodedAttributes
);
//+=========================================================================
// Certificate Verify CTL Usage Data Structures and APIs
//==========================================================================
typedef struct _CTL_VERIFY_USAGE_PARA {
DWORD cbSize;
CRYPT_DATA_BLOB ListIdentifier; // OPTIONAL
DWORD cCtlStore;
HCERTSTORE *rghCtlStore; // OPTIONAL
DWORD cSignerStore;
HCERTSTORE *rghSignerStore; // OPTIONAL
} CTL_VERIFY_USAGE_PARA, *PCTL_VERIFY_USAGE_PARA;
typedef struct _CTL_VERIFY_USAGE_STATUS {
DWORD cbSize;
DWORD dwError;
DWORD dwFlags;
PCCTL_CONTEXT *ppCtl; // IN OUT OPTIONAL
DWORD dwCtlEntryIndex;
PCCERT_CONTEXT *ppSigner; // IN OUT OPTIONAL
DWORD dwSignerIndex;
} CTL_VERIFY_USAGE_STATUS, *PCTL_VERIFY_USAGE_STATUS;
#define CERT_VERIFY_INHIBIT_CTL_UPDATE_FLAG 0x1
#define CERT_VERIFY_TRUSTED_SIGNERS_FLAG 0x2
#define CERT_VERIFY_NO_TIME_CHECK_FLAG 0x4
#define CERT_VERIFY_ALLOW_MORE_USAGE_FLAG 0x8
#define CERT_VERIFY_UPDATED_CTL_FLAG 0x1
//+-------------------------------------------------------------------------
// Verify that a subject is trusted for the specified usage by finding a
// signed and time valid CTL with the usage identifiers and containing the
// the subject. A subject can be identified by either its certificate context
// or any identifier such as its SHA1 hash.
//
// See CertFindSubjectInCTL for definition of dwSubjectType and pvSubject
// parameters.
//
// Via pVerifyUsagePara, the caller can specify the stores to be searched
// to find the CTL. The caller can also specify the stores containing
// acceptable CTL signers. By setting the ListIdentifier, the caller
// can also restrict to a particular signer CTL list.
//
// Via pVerifyUsageStatus, the CTL containing the subject, the subject's
// index into the CTL's array of entries, and the signer of the CTL
// are returned. If the caller is not interested, ppCtl and ppSigner can be set
// to NULL. Returned contexts must be freed via the store's free context APIs.
//
// If the CERT_VERIFY_INHIBIT_CTL_UPDATE_FLAG isn't set, then, a time
// invalid CTL in one of the CtlStores may be replaced. When replaced, the
// CERT_VERIFY_UPDATED_CTL_FLAG is set in pVerifyUsageStatus->dwFlags.
//
// If the CERT_VERIFY_TRUSTED_SIGNERS_FLAG is set, then, only the
// SignerStores specified in pVerifyUsageStatus are searched to find
// the signer. Otherwise, the SignerStores provide additional sources
// to find the signer's certificate.
//
// If CERT_VERIFY_NO_TIME_CHECK_FLAG is set, then, the CTLs aren't checked
// for time validity.
//
// If CERT_VERIFY_ALLOW_MORE_USAGE_FLAG is set, then, the CTL may contain
// additional usage identifiers than specified by pSubjectUsage. Otherwise,
// the found CTL will contain the same usage identifers and no more.
//
// CertVerifyCTLUsage will be implemented as a dispatcher to OID installable
// functions. First, it will try to find an OID function matching the first
// usage object identifier in the pUsage sequence. Next, it will dispatch
// to the default CertDllVerifyCTLUsage functions.
//
// If the subject is trusted for the specified usage, then, TRUE is
// returned. Otherwise, FALSE is returned with dwError set to one of the
// following:
// CRYPT_E_NO_VERIFY_USAGE_DLL
// CRYPT_E_NO_VERIFY_USAGE_CHECK
// CRYPT_E_VERIFY_USAGE_OFFLINE
// CRYPT_E_NOT_IN_CTL
// CRYPT_E_NO_TRUSTED_SIGNER
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertVerifyCTLUsage(
IN DWORD dwEncodingType,
IN DWORD dwSubjectType,
IN void *pvSubject,
IN PCTL_USAGE pSubjectUsage,
IN DWORD dwFlags,
IN OPTIONAL PCTL_VERIFY_USAGE_PARA pVerifyUsagePara,
IN OUT PCTL_VERIFY_USAGE_STATUS pVerifyUsageStatus
);
//+=========================================================================
// Certificate Revocation Data Structures and APIs
//==========================================================================
//+-------------------------------------------------------------------------
// This data structure is updated by a CRL revocation type handler
// with the base and possibly the delta CRL used.
//--------------------------------------------------------------------------
typedef struct _CERT_REVOCATION_CRL_INFO {
DWORD cbSize;
PCCRL_CONTEXT pBaseCrlContext;
PCCRL_CONTEXT pDeltaCrlContext;
// When revoked, points to entry in either of the above CRL contexts.
// Don't free.
PCRL_ENTRY pCrlEntry;
BOOL fDeltaCrlEntry; // TRUE if in pDeltaCrlContext
} CERT_REVOCATION_CRL_INFO, *PCERT_REVOCATION_CRL_INFO;
//+-------------------------------------------------------------------------
// The following data structure may be passed to CertVerifyRevocation to
// assist in finding the issuer of the context to be verified.
//
// When pIssuerCert is specified, pIssuerCert is the issuer of
// rgpvContext[cContext - 1].
//
// When cCertStore and rgCertStore are specified, these stores may contain
// an issuer certificate.
//
// When hCrlStore is specified then a handler which uses CRLs can search this
// store for them
//
// When pftTimeToUse is specified then the handler (if possible) must determine
// revocation status relative to the time given otherwise the answer may be
// independent of time or relative to current time
//--------------------------------------------------------------------------
typedef struct _CERT_REVOCATION_PARA {
DWORD cbSize;
PCCERT_CONTEXT pIssuerCert;
DWORD cCertStore;
HCERTSTORE *rgCertStore;
HCERTSTORE hCrlStore;
LPFILETIME pftTimeToUse;
#ifdef CERT_REVOCATION_PARA_HAS_EXTRA_FIELDS
// Note, if you #define CERT_REVOCATION_PARA_HAS_EXTRA_FIELDS, then, you
// must zero all unused fields in this data structure.
// More fields could be added in a future release.
// 0 uses revocation handler's default timeout.
DWORD dwUrlRetrievalTimeout; // milliseconds
// When set, checks and attempts to retrieve a CRL where
// ThisUpdate >= (CurrentTime - dwFreshnessTime). Otherwise, defaults
// to using the CRL's NextUpdate.
BOOL fCheckFreshnessTime;
DWORD dwFreshnessTime; // seconds
// If NULL, revocation handler gets the current time
LPFILETIME pftCurrentTime;
// If nonNULL, a CRL revocation type handler updates with the base and
// possibly the delta CRL used. Note, *pCrlInfo must be initialized
// by the caller. Any nonNULL CRL contexts are freed. Any updated
// CRL contexts must be freed by the caller.
//
// The CRL info is only applicable to the last context checked. If
// interested in this information, then, CertVerifyRevocation should be
// called with cContext = 1.
PCERT_REVOCATION_CRL_INFO pCrlInfo;
#endif
} CERT_REVOCATION_PARA, *PCERT_REVOCATION_PARA;
//+-------------------------------------------------------------------------
// The following data structure is returned by CertVerifyRevocation to
// specify the status of the revoked or unchecked context. Review the
// following CertVerifyRevocation comments for details.
//
// Upon input to CertVerifyRevocation, cbSize must be set to a size
// >= (offsetof(CERT_REVOCATION_STATUS, dwReason) + sizeof(DWORD) ).
// Otherwise, CertVerifyRevocation returns FALSE and sets LastError to
// E_INVALIDARG.
//
// Upon input to the installed or registered CRYPT_OID_VERIFY_REVOCATION_FUNC
// functions, the dwIndex, dwError and dwReason have been zero'ed.
// If present, fHasFreshnessTime and dwFreshnessTime have been zero'ed.
//--------------------------------------------------------------------------
typedef struct _CERT_REVOCATION_STATUS {
DWORD cbSize;
DWORD dwIndex;
DWORD dwError;
DWORD dwReason;
// Depending on cbSize, the following fields may optionally be returned.
// The Freshness time is only applicable to the last context checked. If
// interested in this information, then, CertVerifyRevocation should be
// called with cContext = 1.
//
// fHasFreshnessTime is only set if we are able to retrieve revocation
// information. For a CRL its CurrentTime - ThisUpdate.
BOOL fHasFreshnessTime;
DWORD dwFreshnessTime; // seconds
} CERT_REVOCATION_STATUS, *PCERT_REVOCATION_STATUS;
//+-------------------------------------------------------------------------
// Verifies the array of contexts for revocation. The dwRevType parameter
// indicates the type of the context data structure passed in rgpvContext.
// Currently only the revocation of certificates is defined.
//
// If the CERT_VERIFY_REV_CHAIN_FLAG flag is set, then, CertVerifyRevocation
// is verifying a chain of certs where, rgpvContext[i + 1] is the issuer
// of rgpvContext[i]. Otherwise, CertVerifyRevocation makes no assumptions
// about the order of the contexts.
//
// To assist in finding the issuer, the pRevPara may optionally be set. See
// the CERT_REVOCATION_PARA data structure for details.
//
// The contexts must contain enough information to allow the
// installable or registered revocation DLLs to find the revocation server. For
// certificates, this information would normally be conveyed in an
// extension such as the IETF's AuthorityInfoAccess extension.
//
// CertVerifyRevocation returns TRUE if all of the contexts were successfully
// checked and none were revoked. Otherwise, returns FALSE and updates the
// returned pRevStatus data structure as follows:
// dwIndex
// Index of the first context that was revoked or unable to
// be checked for revocation
// dwError
// Error status. LastError is also set to this error status.
// dwError can be set to one of the following error codes defined
// in winerror.h:
// ERROR_SUCCESS - good context
// CRYPT_E_REVOKED - context was revoked. dwReason contains the
// reason for revocation
// CRYPT_E_REVOCATION_OFFLINE - unable to connect to the
// revocation server
// CRYPT_E_NOT_IN_REVOCATION_DATABASE - the context to be checked
// was not found in the revocation server's database.
// CRYPT_E_NO_REVOCATION_CHECK - the called revocation function
// wasn't able to do a revocation check on the context
// CRYPT_E_NO_REVOCATION_DLL - no installed or registered Dll was
// found to verify revocation
// dwReason
// The dwReason is currently only set for CRYPT_E_REVOKED and contains
// the reason why the context was revoked. May be one of the following
// CRL reasons defined by the CRL Reason Code extension ("2.5.29.21")
// CRL_REASON_UNSPECIFIED 0
// CRL_REASON_KEY_COMPROMISE 1
// CRL_REASON_CA_COMPROMISE 2
// CRL_REASON_AFFILIATION_CHANGED 3
// CRL_REASON_SUPERSEDED 4
// CRL_REASON_CESSATION_OF_OPERATION 5
// CRL_REASON_CERTIFICATE_HOLD 6
//
// For each entry in rgpvContext, CertVerifyRevocation iterates
// through the CRYPT_OID_VERIFY_REVOCATION_FUNC
// function set's list of installed DEFAULT functions.
// CryptGetDefaultOIDFunctionAddress is called with pwszDll = NULL. If no
// installed functions are found capable of doing the revocation verification,
// CryptVerifyRevocation iterates through CRYPT_OID_VERIFY_REVOCATION_FUNC's
// list of registered DEFAULT Dlls. CryptGetDefaultOIDDllList is called to
// get the list. CryptGetDefaultOIDFunctionAddress is called to load the Dll.
//
// The called functions have the same signature as CertVerifyRevocation. A
// called function returns TRUE if it was able to successfully check all of
// the contexts and none were revoked. Otherwise, the called function returns
// FALSE and updates pRevStatus. dwIndex is set to the index of
// the first context that was found to be revoked or unable to be checked.
// dwError and LastError are updated. For CRYPT_E_REVOKED, dwReason
// is updated. Upon input to the called function, dwIndex, dwError and
// dwReason have been zero'ed. cbSize has been checked to be >=
// sizeof(CERT_REVOCATION_STATUS).
//
// If the called function returns FALSE, and dwError isn't set to
// CRYPT_E_REVOKED, then, CertVerifyRevocation either continues on to the
// next DLL in the list for a returned dwIndex of 0 or for a returned
// dwIndex > 0, restarts the process of finding a verify function by
// advancing the start of the context array to the returned dwIndex and
// decrementing the count of remaining contexts.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertVerifyRevocation(
IN DWORD dwEncodingType,
IN DWORD dwRevType,
IN DWORD cContext,
IN PVOID rgpvContext[],
IN DWORD dwFlags,
IN OPTIONAL PCERT_REVOCATION_PARA pRevPara,
IN OUT PCERT_REVOCATION_STATUS pRevStatus
);
//+-------------------------------------------------------------------------
// Revocation types
//--------------------------------------------------------------------------
#define CERT_CONTEXT_REVOCATION_TYPE 1
//+-------------------------------------------------------------------------
// When the following flag is set, rgpvContext[] consists of a chain
// of certificates, where rgpvContext[i + 1] is the issuer of rgpvContext[i].
//--------------------------------------------------------------------------
#define CERT_VERIFY_REV_CHAIN_FLAG 0x00000001
//+-------------------------------------------------------------------------
// CERT_VERIFY_CACHE_ONLY_BASED_REVOCATION prevents the revocation handler from
// accessing any network based resources for revocation checking
//--------------------------------------------------------------------------
#define CERT_VERIFY_CACHE_ONLY_BASED_REVOCATION 0x00000002
//+-------------------------------------------------------------------------
// By default, the dwUrlRetrievalTimeout in pRevPara is the timeout used
// for each URL wire retrieval. When the following flag is set,
// dwUrlRetrievalTimeout is the accumulative timeout across all URL wire
// retrievals.
//--------------------------------------------------------------------------
#define CERT_VERIFY_REV_ACCUMULATIVE_TIMEOUT_FLAG 0x00000004
//+-------------------------------------------------------------------------
// CERT_CONTEXT_REVOCATION_TYPE
//
// pvContext points to a const CERT_CONTEXT.
//--------------------------------------------------------------------------
//+=========================================================================
// Certificate Helper APIs
//==========================================================================
//+-------------------------------------------------------------------------
// Compare two multiple byte integer blobs to see if they are identical.
//
// Before doing the comparison, leading zero bytes are removed from a
// positive number and leading 0xFF bytes are removed from a negative
// number.
//
// The multiple byte integers are treated as Little Endian. pbData[0] is the
// least significant byte and pbData[cbData - 1] is the most significant
// byte.
//
// Returns TRUE if the integer blobs are identical after removing leading
// 0 or 0xFF bytes.
//--------------------------------------------------------------------------
BOOL
WINAPI
CertCompareIntegerBlob(
IN PCRYPT_INTEGER_BLOB pInt1,
IN PCRYPT_INTEGER_BLOB pInt2
);
//+-------------------------------------------------------------------------
// Compare two certificates to see if they are identical.
//
// Since a certificate is uniquely identified by its Issuer and SerialNumber,
// these are the only fields needing to be compared.
//
// Returns TRUE if the certificates are identical.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertCompareCertificate(
IN DWORD dwCertEncodingType,
IN PCERT_INFO pCertId1,
IN PCERT_INFO pCertId2
);
//+-------------------------------------------------------------------------
// Compare two certificate names to see if they are identical.
//
// Returns TRUE if the names are identical.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertCompareCertificateName(
IN DWORD dwCertEncodingType,
IN PCERT_NAME_BLOB pCertName1,
IN PCERT_NAME_BLOB pCertName2
);
//+-------------------------------------------------------------------------
// Compare the attributes in the certificate name with the specified
// Relative Distinguished Name's (CERT_RDN) array of attributes.
// The comparison iterates through the CERT_RDN attributes and looks for an
// attribute match in any of the certificate name's RDNs.
// Returns TRUE if all the attributes are found and match.
//
// The CERT_RDN_ATTR fields can have the following special values:
// pszObjId == NULL - ignore the attribute object identifier
// dwValueType == RDN_ANY_TYPE - ignore the value type
//
// CERT_CASE_INSENSITIVE_IS_RDN_ATTRS_FLAG should be set to do
// a case insensitive match. Otherwise, defaults to an exact, case sensitive
// match.
//
// CERT_UNICODE_IS_RDN_ATTRS_FLAG should be set if the pRDN was initialized
// with unicode strings as for CryptEncodeObject(X509_UNICODE_NAME).
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertIsRDNAttrsInCertificateName(
IN DWORD dwCertEncodingType,
IN DWORD dwFlags,
IN PCERT_NAME_BLOB pCertName,
IN PCERT_RDN pRDN
);
#define CERT_UNICODE_IS_RDN_ATTRS_FLAG 0x1
#define CERT_CASE_INSENSITIVE_IS_RDN_ATTRS_FLAG 0x2
//+-------------------------------------------------------------------------
// Compare two public keys to see if they are identical.
//
// Returns TRUE if the keys are identical.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertComparePublicKeyInfo(
IN DWORD dwCertEncodingType,
IN PCERT_PUBLIC_KEY_INFO pPublicKey1,
IN PCERT_PUBLIC_KEY_INFO pPublicKey2
);
//+-------------------------------------------------------------------------
// Get the public/private key's bit length.
//
// Returns 0 if unable to determine the key's length.
//--------------------------------------------------------------------------
WINCRYPT32API
DWORD
WINAPI
CertGetPublicKeyLength(
IN DWORD dwCertEncodingType,
IN PCERT_PUBLIC_KEY_INFO pPublicKey
);
//+-------------------------------------------------------------------------
// Verify the signature of a subject certificate or a CRL using the
// public key info
//
// Returns TRUE for a valid signature.
//
// hCryptProv specifies the crypto provider to use to verify the signature.
// It doesn't need to use a private key.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CryptVerifyCertificateSignature(
IN HCRYPTPROV hCryptProv,
IN DWORD dwCertEncodingType,
IN const BYTE * pbEncoded,
IN DWORD cbEncoded,
IN PCERT_PUBLIC_KEY_INFO pPublicKey
);
//+-------------------------------------------------------------------------
// Verify the signature of a subject certificate, CRL, certificate request
// or keygen request using the issuer's public key.
//
// Returns TRUE for a valid signature.
//
// The subject can be an encoded blob or a context for a certificate or CRL.
// For a subject certificate context, if the certificate is missing
// inheritable PublicKey Algorithm Parameters, the context's
// CERT_PUBKEY_ALG_PARA_PROP_ID is updated with the issuer's public key
// algorithm parameters for a valid signature.
//
// The issuer can be a pointer to a CERT_PUBLIC_KEY_INFO, certificate
// context or a chain context.
//
// hCryptProv specifies the crypto provider to use to verify the signature.
// Its private key isn't used. If hCryptProv is NULL, a default
// provider is picked according to the PublicKey Algorithm OID.
//
// If the signature algorithm is a hashing algorithm, then, the
// signature is expected to contain the hash octets. Only dwIssuerType
// of CRYPT_VERIFY_CERT_SIGN_ISSUER_NULL may be specified
// to verify this no signature case. If any other dwIssuerType is
// specified, the verify will fail with LastError set to E_INVALIDARG.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CryptVerifyCertificateSignatureEx(
IN OPTIONAL HCRYPTPROV hCryptProv,
IN DWORD dwCertEncodingType,
IN DWORD dwSubjectType,
IN void *pvSubject,
IN DWORD dwIssuerType,
IN void *pvIssuer,
IN DWORD dwFlags,
IN OPTIONAL void *pvReserved
);
// Subject Types
#define CRYPT_VERIFY_CERT_SIGN_SUBJECT_BLOB 1
// pvSubject :: PCRYPT_DATA_BLOB
#define CRYPT_VERIFY_CERT_SIGN_SUBJECT_CERT 2
// pvSubject :: PCCERT_CONTEXT
#define CRYPT_VERIFY_CERT_SIGN_SUBJECT_CRL 3
// pvSubject :: PCCRL_CONTEXT
// Issuer Types
#define CRYPT_VERIFY_CERT_SIGN_ISSUER_PUBKEY 1
// pvIssuer :: PCERT_PUBLIC_KEY_INFO
#define CRYPT_VERIFY_CERT_SIGN_ISSUER_CERT 2
// pvIssuer :: PCCERT_CONTEXT
#define CRYPT_VERIFY_CERT_SIGN_ISSUER_CHAIN 3
// pvIssuer :: PCCERT_CHAIN_CONTEXT
#define CRYPT_VERIFY_CERT_SIGN_ISSUER_NULL 4
// pvIssuer :: NULL
//+-------------------------------------------------------------------------
// Compute the hash of the "to be signed" information in the encoded
// signed content (CERT_SIGNED_CONTENT_INFO).
//
// hCryptProv specifies the crypto provider to use to compute the hash.
// It doesn't need to use a private key.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CryptHashToBeSigned(
IN HCRYPTPROV hCryptProv,
IN DWORD dwCertEncodingType,
IN const BYTE *pbEncoded,
IN DWORD cbEncoded,
OUT BYTE *pbComputedHash,
IN OUT DWORD *pcbComputedHash
);
//+-------------------------------------------------------------------------
// Hash the encoded content.
//
// hCryptProv specifies the crypto provider to use to compute the hash.
// It doesn't need to use a private key.
//
// Algid specifies the CAPI hash algorithm to use. If Algid is 0, then, the
// default hash algorithm (currently SHA1) is used.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CryptHashCertificate(
IN HCRYPTPROV hCryptProv,
IN ALG_ID Algid,
IN DWORD dwFlags,
IN const BYTE *pbEncoded,
IN DWORD cbEncoded,
OUT BYTE *pbComputedHash,
IN OUT DWORD *pcbComputedHash
);
//+-------------------------------------------------------------------------
// Sign the "to be signed" information in the encoded signed content.
//
// hCryptProv specifies the crypto provider to use to do the signature.
// It uses the specified private key.
//
// If the SignatureAlgorithm is a hash algorithm, then, the signature
// contains the hash octets. A private key isn't used to encrypt the hash.
// dwKeySpec isn't used and hCryptProv can be NULL where an appropriate
// default provider will be used for hashing.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CryptSignCertificate(
IN HCRYPTPROV hCryptProv,
IN DWORD dwKeySpec,
IN DWORD dwCertEncodingType,
IN const BYTE *pbEncodedToBeSigned,
IN DWORD cbEncodedToBeSigned,
IN PCRYPT_ALGORITHM_IDENTIFIER pSignatureAlgorithm,
IN OPTIONAL const void *pvHashAuxInfo,
OUT BYTE *pbSignature,
IN OUT DWORD *pcbSignature
);
//+-------------------------------------------------------------------------
// Encode the "to be signed" information. Sign the encoded "to be signed".
// Encode the "to be signed" and the signature.
//
// hCryptProv specifies the crypto provider to use to do the signature.
// It uses the specified private key.
//
// If the SignatureAlgorithm is a hash algorithm, then, the signature
// contains the hash octets. A private key isn't used to encrypt the hash.
// dwKeySpec isn't used and hCryptProv can be NULL where an appropriate
// default provider will be used for hashing.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CryptSignAndEncodeCertificate(
IN HCRYPTPROV hCryptProv,
IN DWORD dwKeySpec,
IN DWORD dwCertEncodingType,
IN LPCSTR lpszStructType, // "to be signed"
IN const void *pvStructInfo,
IN PCRYPT_ALGORITHM_IDENTIFIER pSignatureAlgorithm,
IN OPTIONAL const void *pvHashAuxInfo,
OUT PBYTE pbEncoded,
IN OUT DWORD *pcbEncoded
);
//+-------------------------------------------------------------------------
// Verify the time validity of a certificate.
//
// Returns -1 if before NotBefore, +1 if after NotAfter and otherwise 0 for
// a valid certificate
//
// If pTimeToVerify is NULL, uses the current time.
//--------------------------------------------------------------------------
WINCRYPT32API
LONG
WINAPI
CertVerifyTimeValidity(
IN LPFILETIME pTimeToVerify,
IN PCERT_INFO pCertInfo
);
//+-------------------------------------------------------------------------
// Verify the time validity of a CRL.
//
// Returns -1 if before ThisUpdate, +1 if after NextUpdate and otherwise 0 for
// a valid CRL
//
// If pTimeToVerify is NULL, uses the current time.
//--------------------------------------------------------------------------
WINCRYPT32API
LONG
WINAPI
CertVerifyCRLTimeValidity(
IN LPFILETIME pTimeToVerify,
IN PCRL_INFO pCrlInfo
);
//+-------------------------------------------------------------------------
// Verify that the subject's time validity nests within the issuer's time
// validity.
//
// Returns TRUE if it nests. Otherwise, returns FALSE.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertVerifyValidityNesting(
IN PCERT_INFO pSubjectInfo,
IN PCERT_INFO pIssuerInfo
);
//+-------------------------------------------------------------------------
// Verify that the subject certificate isn't on its issuer CRL.
//
// Returns true if the certificate isn't on the CRL.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertVerifyCRLRevocation(
IN DWORD dwCertEncodingType,
IN PCERT_INFO pCertId, // Only the Issuer and SerialNumber
// fields are used
IN DWORD cCrlInfo,
IN PCRL_INFO rgpCrlInfo[]
);
//+-------------------------------------------------------------------------
// Convert the CAPI AlgId to the ASN.1 Object Identifier string
//
// Returns NULL if there isn't an ObjId corresponding to the AlgId.
//--------------------------------------------------------------------------
WINCRYPT32API
LPCSTR
WINAPI
CertAlgIdToOID(
IN DWORD dwAlgId
);
//+-------------------------------------------------------------------------
// Convert the ASN.1 Object Identifier string to the CAPI AlgId.
//
// Returns 0 if there isn't an AlgId corresponding to the ObjId.
//--------------------------------------------------------------------------
WINCRYPT32API
DWORD
WINAPI
CertOIDToAlgId(
IN LPCSTR pszObjId
);
//+-------------------------------------------------------------------------
// Find an extension identified by its Object Identifier.
//
// If found, returns pointer to the extension. Otherwise, returns NULL.
//--------------------------------------------------------------------------
WINCRYPT32API
PCERT_EXTENSION
WINAPI
CertFindExtension(
IN LPCSTR pszObjId,
IN DWORD cExtensions,
IN CERT_EXTENSION rgExtensions[]
);
//+-------------------------------------------------------------------------
// Find the first attribute identified by its Object Identifier.
//
// If found, returns pointer to the attribute. Otherwise, returns NULL.
//--------------------------------------------------------------------------
WINCRYPT32API
PCRYPT_ATTRIBUTE
WINAPI
CertFindAttribute(
IN LPCSTR pszObjId,
IN DWORD cAttr,
IN CRYPT_ATTRIBUTE rgAttr[]
);
//+-------------------------------------------------------------------------
// Find the first CERT_RDN attribute identified by its Object Identifier in
// the name's list of Relative Distinguished Names.
//
// If found, returns pointer to the attribute. Otherwise, returns NULL.
//--------------------------------------------------------------------------
WINCRYPT32API
PCERT_RDN_ATTR
WINAPI
CertFindRDNAttr(
IN LPCSTR pszObjId,
IN PCERT_NAME_INFO pName
);
//+-------------------------------------------------------------------------
// Get the intended key usage bytes from the certificate.
//
// If the certificate doesn't have any intended key usage bytes, returns FALSE
// and *pbKeyUsage is zeroed. Otherwise, returns TRUE and up through
// cbKeyUsage bytes are copied into *pbKeyUsage. Any remaining uncopied
// bytes are zeroed.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertGetIntendedKeyUsage(
IN DWORD dwCertEncodingType,
IN PCERT_INFO pCertInfo,
OUT BYTE *pbKeyUsage,
IN DWORD cbKeyUsage
);
typedef void *HCRYPTDEFAULTCONTEXT;
//+-------------------------------------------------------------------------
// Install a previously CryptAcquiredContext'ed HCRYPTPROV to be used as
// a default context.
//
// dwDefaultType and pvDefaultPara specify where the default context is used.
// For example, install the HCRYPTPROV to be used to verify certificate's
// having szOID_OIWSEC_md5RSA signatures.
//
// By default, the installed HCRYPTPROV is only applicable to the current
// thread. Set CRYPT_DEFAULT_CONTEXT_PROCESS_FLAG to allow the HCRYPTPROV
// to be used by all threads in the current process.
//
// For a successful install, TRUE is returned and *phDefaultContext is
// updated with the HANDLE to be passed to CryptUninstallDefaultContext.
//
// The installed HCRYPTPROVs are stack ordered (the last installed
// HCRYPTPROV is checked first). All thread installed HCRYPTPROVs are
// checked before any process HCRYPTPROVs.
//
// The installed HCRYPTPROV remains available for default usage until
// CryptUninstallDefaultContext is called or the thread or process exits.
//
// If CRYPT_DEFAULT_CONTEXT_AUTO_RELEASE_FLAG is set, then, the HCRYPTPROV
// is CryptReleaseContext'ed at thread or process exit. However,
// not CryptReleaseContext'ed if CryptUninstallDefaultContext is
// called.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CryptInstallDefaultContext(
IN HCRYPTPROV hCryptProv,
IN DWORD dwDefaultType,
IN const void *pvDefaultPara,
IN DWORD dwFlags,
IN void *pvReserved,
OUT HCRYPTDEFAULTCONTEXT *phDefaultContext
);
// dwFlags
#define CRYPT_DEFAULT_CONTEXT_AUTO_RELEASE_FLAG 0x00000001
#define CRYPT_DEFAULT_CONTEXT_PROCESS_FLAG 0x00000002
// List of dwDefaultType's
#define CRYPT_DEFAULT_CONTEXT_CERT_SIGN_OID 1
#define CRYPT_DEFAULT_CONTEXT_MULTI_CERT_SIGN_OID 2
//+-------------------------------------------------------------------------
// CRYPT_DEFAULT_CONTEXT_CERT_SIGN_OID
//
// Install a default HCRYPTPROV used to verify a certificate
// signature. pvDefaultPara points to the szOID of the certificate
// signature algorithm, for example, szOID_OIWSEC_md5RSA. If
// pvDefaultPara is NULL, then, the HCRYPTPROV is used to verify all
// certificate signatures. Note, pvDefaultPara can't be NULL when
// CRYPT_DEFAULT_CONTEXT_PROCESS_FLAG is set.
//--------------------------------------------------------------------------
//+-------------------------------------------------------------------------
// CRYPT_DEFAULT_CONTEXT_MULTI_CERT_SIGN_OID
//
// Same as CRYPT_DEFAULT_CONTEXT_CERT_SIGN_OID. However, the default
// HCRYPTPROV is to be used for multiple signature szOIDs. pvDefaultPara
// points to a CRYPT_DEFAULT_CONTEXT_MULTI_OID_PARA structure containing
// an array of szOID pointers.
//--------------------------------------------------------------------------
typedef struct _CRYPT_DEFAULT_CONTEXT_MULTI_OID_PARA {
DWORD cOID;
LPSTR *rgpszOID;
} CRYPT_DEFAULT_CONTEXT_MULTI_OID_PARA, *PCRYPT_DEFAULT_CONTEXT_MULTI_OID_PARA;
//+-------------------------------------------------------------------------
// Uninstall a default context previously installed by
// CryptInstallDefaultContext.
//
// For a default context installed with CRYPT_DEFAULT_CONTEXT_PROCESS_FLAG
// set, if any other threads are currently using this context,
// this function will block until they finish.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CryptUninstallDefaultContext(
HCRYPTDEFAULTCONTEXT hDefaultContext,
IN DWORD dwFlags,
IN void *pvReserved
);
//+-------------------------------------------------------------------------
// Export the public key info associated with the provider's corresponding
// private key.
//
// Calls CryptExportPublicKeyInfoEx with pszPublicKeyObjId = NULL,
// dwFlags = 0 and pvAuxInfo = NULL.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CryptExportPublicKeyInfo(
IN HCRYPTPROV hCryptProv,
IN DWORD dwKeySpec,
IN DWORD dwCertEncodingType,
OUT PCERT_PUBLIC_KEY_INFO pInfo,
IN OUT DWORD *pcbInfo
);
//+-------------------------------------------------------------------------
// Export the public key info associated with the provider's corresponding
// private key.
//
// Uses the dwCertEncodingType and pszPublicKeyObjId to call the
// installable CRYPT_OID_EXPORT_PUBLIC_KEY_INFO_FUNC. The called function
// has the same signature as CryptExportPublicKeyInfoEx.
//
// If unable to find an installable OID function for the pszPublicKeyObjId,
// attempts to export as a RSA Public Key (szOID_RSA_RSA).
//
// The dwFlags and pvAuxInfo aren't used for szOID_RSA_RSA.
//--------------------------------------------------------------------------
#define CRYPT_OID_EXPORT_PUBLIC_KEY_INFO_FUNC "CryptDllExportPublicKeyInfoEx"
WINCRYPT32API
BOOL
WINAPI
CryptExportPublicKeyInfoEx(
IN HCRYPTPROV hCryptProv,
IN DWORD dwKeySpec,
IN DWORD dwCertEncodingType,
IN LPSTR pszPublicKeyObjId,
IN DWORD dwFlags,
IN OPTIONAL void *pvAuxInfo,
OUT PCERT_PUBLIC_KEY_INFO pInfo,
IN OUT DWORD *pcbInfo
);
//+-------------------------------------------------------------------------
// Convert and import the public key info into the provider and return a
// handle to the public key.
//
// Calls CryptImportPublicKeyInfoEx with aiKeyAlg = 0, dwFlags = 0 and
// pvAuxInfo = NULL.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CryptImportPublicKeyInfo(
IN HCRYPTPROV hCryptProv,
IN DWORD dwCertEncodingType,
IN PCERT_PUBLIC_KEY_INFO pInfo,
OUT HCRYPTKEY *phKey
);
//+-------------------------------------------------------------------------
// Convert and import the public key info into the provider and return a
// handle to the public key.
//
// Uses the dwCertEncodingType and pInfo->Algorithm.pszObjId to call the
// installable CRYPT_OID_IMPORT_PUBLIC_KEY_INFO_FUNC. The called function
// has the same signature as CryptImportPublicKeyInfoEx.
//
// If unable to find an installable OID function for the pszObjId,
// attempts to import as a RSA Public Key (szOID_RSA_RSA).
//
// For szOID_RSA_RSA: aiKeyAlg may be set to CALG_RSA_SIGN or CALG_RSA_KEYX.
// Defaults to CALG_RSA_KEYX. The dwFlags and pvAuxInfo aren't used.
//--------------------------------------------------------------------------
#define CRYPT_OID_IMPORT_PUBLIC_KEY_INFO_FUNC "CryptDllImportPublicKeyInfoEx"
WINCRYPT32API
BOOL
WINAPI
CryptImportPublicKeyInfoEx(
IN HCRYPTPROV hCryptProv,
IN DWORD dwCertEncodingType,
IN PCERT_PUBLIC_KEY_INFO pInfo,
IN ALG_ID aiKeyAlg,
IN DWORD dwFlags,
IN OPTIONAL void *pvAuxInfo,
OUT HCRYPTKEY *phKey
);
//+-------------------------------------------------------------------------
// Acquire a HCRYPTPROV handle and dwKeySpec for the specified certificate
// context. Uses the certificate's CERT_KEY_PROV_INFO_PROP_ID property.
// The returned HCRYPTPROV handle may optionally be cached using the
// certificate's CERT_KEY_CONTEXT_PROP_ID property.
//
// If CRYPT_ACQUIRE_CACHE_FLAG is set, then, if an already acquired and
// cached HCRYPTPROV exists for the certificate, its returned. Otherwise,
// a HCRYPTPROV is acquired and then cached via the certificate's
// CERT_KEY_CONTEXT_PROP_ID.
//
// The CRYPT_ACQUIRE_USE_PROV_INFO_FLAG can be set to use the dwFlags field of
// the certificate's CERT_KEY_PROV_INFO_PROP_ID property's CRYPT_KEY_PROV_INFO
// data structure to determine if the returned HCRYPTPROV should be cached.
// HCRYPTPROV caching is enabled if the CERT_SET_KEY_CONTEXT_PROP_ID flag was
// set.
//
// If CRYPT_ACQUIRE_COMPARE_KEY_FLAG is set, then,
// the public key in the certificate is compared with the public
// key returned by the cryptographic provider. If the keys don't match, the
// acquire fails and LastError is set to NTE_BAD_PUBLIC_KEY. Note, if
// a cached HCRYPTPROV is returned, the comparison isn't done. We assume the
// comparison was done on the initial acquire.
//
// The CRYPT_ACQUIRE_SILENT_FLAG can be set to suppress any UI by the CSP.
// See CryptAcquireContext's CRYPT_SILENT flag for more details.
//
// *pfCallerFreeProv is returned set to FALSE for:
// - Acquire or public key comparison fails.
// - CRYPT_ACQUIRE_CACHE_FLAG is set.
// - CRYPT_ACQUIRE_USE_PROV_INFO_FLAG is set AND
// CERT_SET_KEY_CONTEXT_PROP_ID flag is set in the dwFlags field of the
// certificate's CERT_KEY_PROV_INFO_PROP_ID property's
// CRYPT_KEY_PROV_INFO data structure.
// When *pfCallerFreeProv is FALSE, the caller must not release. The
// returned HCRYPTPROV will be released on the last free of the certificate
// context.
//
// Otherwise, *pfCallerFreeProv is TRUE and the returned HCRYPTPROV must
// be released by the caller by calling CryptReleaseContext.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CryptAcquireCertificatePrivateKey(
IN PCCERT_CONTEXT pCert,
IN DWORD dwFlags,
IN void *pvReserved,
OUT HCRYPTPROV *phCryptProv,
OUT OPTIONAL DWORD *pdwKeySpec,
OUT OPTIONAL BOOL *pfCallerFreeProv
);
#define CRYPT_ACQUIRE_CACHE_FLAG 0x00000001
#define CRYPT_ACQUIRE_USE_PROV_INFO_FLAG 0x00000002
#define CRYPT_ACQUIRE_COMPARE_KEY_FLAG 0x00000004
#define CRYPT_ACQUIRE_SILENT_FLAG 0x00000040
//+-------------------------------------------------------------------------
// Enumerates the cryptographic providers and their containers to find the
// private key corresponding to the certificate's public key. For a match,
// the certificate's CERT_KEY_PROV_INFO_PROP_ID property is updated.
//
// If the CERT_KEY_PROV_INFO_PROP_ID is already set, then, its checked to
// see if it matches the provider's public key. For a match, the above
// enumeration is skipped.
//
// By default both the user and machine key containers are searched.
// The CRYPT_FIND_USER_KEYSET_FLAG or CRYPT_FIND_MACHINE_KEYSET_FLAG
// can be set in dwFlags to restrict the search to either of the containers.
//
// The CRYPT_FIND_SILENT_KEYSET_FLAG can be set to suppress any UI by the CSP.
// See CryptAcquireContext's CRYPT_SILENT flag for more details.
//
// If a container isn't found, returns FALSE with LastError set to
// NTE_NO_KEY.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CryptFindCertificateKeyProvInfo(
IN PCCERT_CONTEXT pCert,
IN DWORD dwFlags,
IN void *pvReserved
);
#define CRYPT_FIND_USER_KEYSET_FLAG 0x00000001
#define CRYPT_FIND_MACHINE_KEYSET_FLAG 0x00000002
#define CRYPT_FIND_SILENT_KEYSET_FLAG 0x00000040
//+-------------------------------------------------------------------------
// This is the prototype for the installable function which is called to
// actually import a key into a CSP. an installable of this type is called
// from CryptImportPKCS8. the algorithm OID of the private key is used
// to look up the proper installable function to call.
//
// hCryptProv - the provider to import the key to
// pPrivateKeyInfo - describes the key to be imported
// dwFlags - The available flags are:
// CRYPT_EXPORTABLE
// this flag is used when importing private keys, for a full
// explanation please see the documentation for CryptImportKey.
// pvAuxInfo - reserved for future, must be NULL
//--------------------------------------------------------------------------
typedef BOOL (WINAPI *PFN_IMPORT_PRIV_KEY_FUNC) (
HCRYPTPROV hCryptProv, // in
CRYPT_PRIVATE_KEY_INFO *pPrivateKeyInfo, // in
DWORD dwFlags, // in, optional
void *pvAuxInfo // in, optional
);
#define CRYPT_OID_IMPORT_PRIVATE_KEY_INFO_FUNC "CryptDllImportPrivateKeyInfoEx"
//+-------------------------------------------------------------------------
// Convert (from PKCS8 format) and import the private key into a provider
// and return a handle to the provider as well as the KeySpec used to import to.
//
// This function will call the PRESOLVE_HCRYPTPROV_FUNC in the
// privateKeyAndParams to obtain a handle of provider to import the key to.
// if the PRESOLVE_HCRYPTPROV_FUNC is NULL then the default provider will be used.
//
// privateKeyAndParams - private key blob and corresponding parameters
// dwFlags - The available flags are:
// CRYPT_EXPORTABLE
// this flag is used when importing private keys, for a full
// explanation please see the documentation for CryptImportKey.
// phCryptProv - filled in with the handle of the provider the key was
// imported to, the caller is responsible for freeing it
// pvAuxInfo - This parameter is reserved for future use and should be set
// to NULL in the interim.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CryptImportPKCS8(
CRYPT_PKCS8_IMPORT_PARAMS sImportParams, // in
DWORD dwFlags, // in, optional
HCRYPTPROV *phCryptProv, // out, optional
void *pvAuxInfo // in, optional
);
//+-------------------------------------------------------------------------
// this is the prototype for installable functions for exporting the private key
//--------------------------------------------------------------------------
typedef BOOL (WINAPI *PFN_EXPORT_PRIV_KEY_FUNC) (
HCRYPTPROV hCryptProv, // in
DWORD dwKeySpec, // in
LPSTR pszPrivateKeyObjId, // in
DWORD dwFlags, // in
void *pvAuxInfo, // in
CRYPT_PRIVATE_KEY_INFO *pPrivateKeyInfo, // out
DWORD *pcbPrivateKeyBlob // in, out
);
#define CRYPT_OID_EXPORT_PRIVATE_KEY_INFO_FUNC "CryptDllExportPrivateKeyInfoEx"
#define CRYPT_DELETE_KEYSET 0x0001
//+-------------------------------------------------------------------------
// CryptExportPKCS8 -- superseded by CryptExportPKCS8Ex
//
// Export the private key in PKCS8 format
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CryptExportPKCS8(
HCRYPTPROV hCryptProv, // in
DWORD dwKeySpec, // in
LPSTR pszPrivateKeyObjId, // in
DWORD dwFlags, // in
void *pvAuxInfo, // in
BYTE *pbPrivateKeyBlob, // out
DWORD *pcbPrivateKeyBlob // in, out
);
//+-------------------------------------------------------------------------
// CryptExportPKCS8Ex
//
// Export the private key in PKCS8 format
//
//
// Uses the pszPrivateKeyObjId to call the
// installable CRYPT_OID_EXPORT_PRIVATE_KEY_INFO_FUNC. The called function
// has the signature defined by PFN_EXPORT_PRIV_KEY_FUNC.
//
// If unable to find an installable OID function for the pszPrivateKeyObjId,
// attempts to export as a RSA Private Key (szOID_RSA_RSA).
//
// psExportParams - specifies information about the key to export
// dwFlags - The flag values. None currently supported
// pvAuxInfo - This parameter is reserved for future use and should be set to
// NULL in the interim.
// pbPrivateKeyBlob - A pointer to the private key blob. It will be encoded
// as a PKCS8 PrivateKeyInfo.
// pcbPrivateKeyBlob - A pointer to a DWORD that contains the size, in bytes,
// of the private key blob being exported.
//+-------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CryptExportPKCS8Ex(
CRYPT_PKCS8_EXPORT_PARAMS* psExportParams, // in
DWORD dwFlags, // in
void *pvAuxInfo, // in
BYTE *pbPrivateKeyBlob, // out
DWORD *pcbPrivateKeyBlob // in, out
);
//+-------------------------------------------------------------------------
// Compute the hash of the encoded public key info.
//
// The public key info is encoded and then hashed.
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CryptHashPublicKeyInfo(
IN HCRYPTPROV hCryptProv,
IN ALG_ID Algid,
IN DWORD dwFlags,
IN DWORD dwCertEncodingType,
IN PCERT_PUBLIC_KEY_INFO pInfo,
OUT BYTE *pbComputedHash,
IN OUT DWORD *pcbComputedHash
);
//+-------------------------------------------------------------------------
// Convert a Name Value to a null terminated char string
//
// Returns the number of characters converted including the terminating null
// character. If psz is NULL or csz is 0, returns the required size of the
// destination string (including the terminating null char).
//
// If psz != NULL && csz != 0, returned psz is always NULL terminated.
//
// Note: csz includes the NULL char.
//--------------------------------------------------------------------------
WINCRYPT32API
DWORD
WINAPI
CertRDNValueToStrA(
IN DWORD dwValueType,
IN PCERT_RDN_VALUE_BLOB pValue,
OUT OPTIONAL LPSTR psz,
IN DWORD csz
);
//+-------------------------------------------------------------------------
// Convert a Name Value to a null terminated char string
//
// Returns the number of characters converted including the terminating null
// character. If psz is NULL or csz is 0, returns the required size of the
// destination string (including the terminating null char).
//
// If psz != NULL && csz != 0, returned psz is always NULL terminated.
//
// Note: csz includes the NULL char.
//--------------------------------------------------------------------------
WINCRYPT32API
DWORD
WINAPI
CertRDNValueToStrW(
IN DWORD dwValueType,
IN PCERT_RDN_VALUE_BLOB pValue,
OUT OPTIONAL LPWSTR psz,
IN DWORD csz
);
#ifdef UNICODE
#define CertRDNValueToStr CertRDNValueToStrW
#else
#define CertRDNValueToStr CertRDNValueToStrA
#endif // !UNICODE
//+-------------------------------------------------------------------------
// Convert the certificate name blob to a null terminated char string.
//
// Follows the string representation of distinguished names specified in
// RFC 1779. (Note, added double quoting "" for embedded quotes, quote
// empty strings and don't quote strings containing consecutive spaces).
// RDN values of type CERT_RDN_ENCODED_BLOB or CERT_RDN_OCTET_STRING are
// formatted in hexadecimal (e.g. #0A56CF).
//
// The name string is formatted according to the dwStrType:
// CERT_SIMPLE_NAME_STR
// The object identifiers are discarded. CERT_RDN entries are separated
// by ", ". Multiple attributes per CERT_RDN are separated by " + ".
// For example:
// Microsoft, Joe Cool + Programmer
// CERT_OID_NAME_STR
// The object identifiers are included with a "=" separator from their
// attribute value. CERT_RDN entries are separated by ", ".
// Multiple attributes per CERT_RDN are separated by " + ". For example:
// 2.5.4.11=Microsoft, 2.5.4.3=Joe Cool + 2.5.4.12=Programmer
// CERT_X500_NAME_STR
// The object identifiers are converted to their X500 key name. Otherwise,
// same as CERT_OID_NAME_STR. If the object identifier doesn't have
// a corresponding X500 key name, then, the object identifier is used with
// a "OID." prefix. For example:
// OU=Microsoft, CN=Joe Cool + T=Programmer, OID.1.2.3.4.5.6=Unknown
//
// We quote the RDN value if it contains leading or trailing whitespace
// or one of the following characters: ",", "+", "=", """, "n", "<", ">",
// "#" or ";". The quoting character is ". If the the RDN Value contains
// a " it is double quoted (""). For example:
// OU=" Microsoft", CN="Joe ""Cool""" + T="Programmer, Manager"
//
// CERT_NAME_STR_SEMICOLON_FLAG can be or'ed into dwStrType to replace
// the ", " separator with a "; " separator.
//
// CERT_NAME_STR_CRLF_FLAG can be or'ed into dwStrType to replace
// the ", " separator with a "rn" separator.
//
// CERT_NAME_STR_NO_PLUS_FLAG can be or'ed into dwStrType to replace the
// " + " separator with a single space, " ".
//
// CERT_NAME_STR_NO_QUOTING_FLAG can be or'ed into dwStrType to inhibit
// the above quoting.
//
// CERT_NAME_STR_REVERSE_FLAG can be or'ed into dwStrType to reverse the
// order of the RDNs before converting to the string.
//
// By default, CERT_RDN_T61_STRING encoded values are initially decoded
// as UTF8. If the UTF8 decoding fails, then, decoded as 8 bit characters.
// CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG can be or'ed into dwStrType to
// skip the initial attempt to decode as UTF8.
//
// Returns the number of characters converted including the terminating null
// character. If psz is NULL or csz is 0, returns the required size of the
// destination string (including the terminating null char).
//
// If psz != NULL && csz != 0, returned psz is always NULL terminated.
//
// Note: csz includes the NULL char.
//--------------------------------------------------------------------------
//+-------------------------------------------------------------------------
//--------------------------------------------------------------------------
WINCRYPT32API
DWORD
WINAPI
CertNameToStrA(
IN DWORD dwCertEncodingType,
IN PCERT_NAME_BLOB pName,
IN DWORD dwStrType,
OUT OPTIONAL LPSTR psz,
IN DWORD csz
);
//+-------------------------------------------------------------------------
//--------------------------------------------------------------------------
WINCRYPT32API
DWORD
WINAPI
CertNameToStrW(
IN DWORD dwCertEncodingType,
IN PCERT_NAME_BLOB pName,
IN DWORD dwStrType,
OUT OPTIONAL LPWSTR psz,
IN DWORD csz
);
#ifdef UNICODE
#define CertNameToStr CertNameToStrW
#else
#define CertNameToStr CertNameToStrA
#endif // !UNICODE
//+-------------------------------------------------------------------------
// Certificate name string types
//--------------------------------------------------------------------------
#define CERT_SIMPLE_NAME_STR 1
#define CERT_OID_NAME_STR 2
#define CERT_X500_NAME_STR 3
//+-------------------------------------------------------------------------
// Certificate name string type flags OR'ed with the above types
//--------------------------------------------------------------------------
#define CERT_NAME_STR_SEMICOLON_FLAG 0x40000000
#define CERT_NAME_STR_NO_PLUS_FLAG 0x20000000
#define CERT_NAME_STR_NO_QUOTING_FLAG 0x10000000
#define CERT_NAME_STR_CRLF_FLAG 0x08000000
#define CERT_NAME_STR_COMMA_FLAG 0x04000000
#define CERT_NAME_STR_REVERSE_FLAG 0x02000000
#define CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG 0x00010000
#define CERT_NAME_STR_ENABLE_T61_UNICODE_FLAG 0x00020000
#define CERT_NAME_STR_ENABLE_UTF8_UNICODE_FLAG 0x00040000
//+-------------------------------------------------------------------------
// Convert the null terminated X500 string to an encoded certificate name.
//
// The input string is expected to be formatted the same as the output
// from the above CertNameToStr API.
//
// The CERT_SIMPLE_NAME_STR type isn't supported. Otherwise, when dwStrType
// is set to 0, CERT_OID_NAME_STR or CERT_X500_NAME_STR, allow either a
// case insensitive X500 key (CN=), case insensitive "OID." prefixed
// object identifier (OID.1.2.3.4.5.6=) or an object identifier (1.2.3.4=).
//
// If no flags are OR'ed into dwStrType, then, allow "," or ";" as RDN
// separators and "+" as the multiple RDN value separator. Quoting is
// supported. A quote may be included in a quoted value by double quoting,
// for example (CN="Joe ""Cool"""). A value starting with a "#" is treated
// as ascii hex and converted to a CERT_RDN_OCTET_STRING. Embedded whitespace
// is skipped (1.2.3 = # AB CD 01 is the same as 1.2.3=#ABCD01).
//
// Whitespace surrounding the keys, object identifers and values is removed.
//
// CERT_NAME_STR_COMMA_FLAG can be or'ed into dwStrType to only allow the
// "," as the RDN separator.
//
// CERT_NAME_STR_SEMICOLON_FLAG can be or'ed into dwStrType to only allow the
// ";" as the RDN separator.
//
// CERT_NAME_STR_CRLF_FLAG can be or'ed into dwStrType to only allow
// "r" or "n" as the RDN separator.
//
// CERT_NAME_STR_NO_PLUS_FLAG can be or'ed into dwStrType to ignore "+"
// as a separator and not allow multiple values per RDN.
//
// CERT_NAME_STR_NO_QUOTING_FLAG can be or'ed into dwStrType to inhibit
// quoting.
//
// CERT_NAME_STR_REVERSE_FLAG can be or'ed into dwStrType to reverse the
// order of the RDNs after converting from the string and before encoding.
//
// CERT_NAME_STR_ENABLE_T61_UNICODE_FLAG can be or'ed into dwStrType to
// to select the CERT_RDN_T61_STRING encoded value type instead of
// CERT_RDN_UNICODE_STRING if all the UNICODE characters are <= 0xFF.
//
// CERT_NAME_STR_ENABLE_UTF8_UNICODE_FLAG can be or'ed into dwStrType to
// to select the CERT_RDN_UTF8_STRING encoded value type instead of
// CERT_RDN_UNICODE_STRING.
//
// Support the following X500 Keys:
//
// Key Object Identifier RDN Value Type(s)
// --- ----------------- -----------------
// CN szOID_COMMON_NAME Printable, Unicode
// L szOID_LOCALITY_NAME Printable, Unicode
// O szOID_ORGANIZATION_NAME Printable, Unicode
// OU szOID_ORGANIZATIONAL_UNIT_NAME Printable, Unicode
// E szOID_RSA_emailAddr Only IA5
// Email szOID_RSA_emailAddr Only IA5
// C szOID_COUNTRY_NAME Only Printable
// S szOID_STATE_OR_PROVINCE_NAME Printable, Unicode
// ST szOID_STATE_OR_PROVINCE_NAME Printable, Unicode
// STREET szOID_STREET_ADDRESS Printable, Unicode
// T szOID_TITLE Printable, Unicode
// Title szOID_TITLE Printable, Unicode
// G szOID_GIVEN_NAME Printable, Unicode
// GivenName szOID_GIVEN_NAME Printable, Unicode
// I szOID_INITIALS Printable, Unicode
// Initials szOID_INITIALS Printable, Unicode
// SN szOID_SUR_NAME Printable, Unicode
// DC szOID_DOMAIN_COMPONENT IA5, UTF8
//
// Note, T61 is selected instead of Unicode if
// CERT_NAME_STR_ENABLE_T61_UNICODE_FLAG is set and all the unicode
// characters are <= 0xFF.
//
// Note, UTF8 is selected instead of Unicode if
// CERT_NAME_STR_ENABLE_UTF8_UNICODE_FLAG is set.
//
// Returns TRUE if successfully parsed the input string and encoded
// the name.
//
// If the input string is detected to be invalid, *ppszError is updated
// to point to the beginning of the invalid character sequence. Otherwise,
// *ppszError is set to NULL. *ppszError is updated with a non-NULL pointer
// for the following errors:
// CRYPT_E_INVALID_X500_STRING
// CRYPT_E_INVALID_NUMERIC_STRING
// CRYPT_E_INVALID_PRINTABLE_STRING
// CRYPT_E_INVALID_IA5_STRING
//
// ppszError can be set to NULL if not interested in getting a pointer
// to the invalid character sequence.
//--------------------------------------------------------------------------
//+-------------------------------------------------------------------------
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertStrToNameA(
IN DWORD dwCertEncodingType,
IN LPCSTR pszX500,
IN DWORD dwStrType,
IN OPTIONAL void *pvReserved,
OUT BYTE *pbEncoded,
IN OUT DWORD *pcbEncoded,
OUT OPTIONAL LPCSTR *ppszError
);
//+-------------------------------------------------------------------------
//--------------------------------------------------------------------------
WINCRYPT32API
BOOL
WINAPI
CertStrToNameW(
IN DWORD dwCertEncodingType,
IN LPCWSTR pszX500,
IN DWORD dwStrType,
IN OPTIONAL void *pvReserved,
OUT BYTE *pbEncoded,
IN OUT DWORD *pcbEncoded,
OUT OPTIONAL LPCWSTR *ppszError
);
#ifdef UNICODE
#define CertStrToName CertStrToNameW
#else
#define CertStrToName CertStrToNameA
#endif // !UNICODE
//+-------------------------------------------------------------------------
// Get the subject or issuer name from the certificate and
// according to the specified format type, convert to a null terminated
// character string.
//
// CERT_NAME_ISSUER_FLAG can be set to get the issuer's name. Otherwise,
// gets the subject's name.
//
// By default, CERT_RDN_T61_STRING encoded values are initially decoded
// as UTF8. If the UTF8 decoding fails, then, decoded as 8 bit characters.
// CERT_NAME_DISABLE_IE4_UTF8_FLAG can be set in dwFlags to
// skip the initial attempt to decode as UTF8.
//
// The name string is formatted according to the dwType:
// CERT_NAME_EMAIL_TYPE
// If the certificate has a Subject Alternative Name extension (for
// issuer, Issuer Alternative Name), searches for first rfc822Name choice.
// If the rfc822Name choice isn't found in the extension, searches the
// Subject Name field for the Email OID, "1.2.840.113549.1.9.1".
// If the rfc822Name or Email OID is found, returns the string. Otherwise,
// returns an empty string (returned character count is 1).
// CERT_NAME_DNS_TYPE
// If the certificate has a Subject Alternative Name extension (for
// issuer, Issuer Alternative Name), searches for first DNSName choice.
// If the DNSName choice isn't found in the extension, searches the
// Subject Name field for the CN OID, "2.5.4.3".
// If the DNSName or CN OID is found, returns the string. Otherwise,
// returns an empty string.
// CERT_NAME_URL_TYPE
// If the certificate has a Subject Alternative Name extension (for
// issuer, Issuer Alternative Name), searches for first URL choice.
// If the URL choice is found, returns the string. Otherwise,
// returns an empty string.
// CERT_NAME_UPN_TYPE
// If the certificate has a Subject Alternative Name extension,
// searches the OtherName choices looking for a
// pszObjId == szOID_NT_PRINCIPAL_NAME, "1.3.6.1.4.1.311.20.2.3".
// If the UPN OID is found, the blob is decoded as a
// X509_UNICODE_ANY_STRING and the decoded string is returned.
// Otherwise, returns an empty string.
// CERT_NAME_RDN_TYPE
// Converts the Subject Name blob by calling CertNameToStr. pvTypePara
// points to a DWORD containing the dwStrType passed to CertNameToStr.
// If the Subject Name field is empty and the certificate has a
// Subject Alternative Name extension, searches for and converts
// the first directoryName choice.
// CERT_NAME_ATTR_TYPE
// pvTypePara points to the Object Identifier specifying the name attribute
// to be returned. For example, to get the CN,
// pvTypePara = szOID_COMMON_NAME ("2.5.4.3"). Searches, the Subject Name
// field for the attribute.
// If the Subject Name field is empty and the certificate has a
// Subject Alternative Name extension, checks for
// the first directoryName choice and searches it.
//
// Note, searches the RDNs in reverse order.
//
// CERT_NAME_SIMPLE_DISPLAY_TYPE
// Iterates through the following list of name attributes and searches
// the Subject Name and then the Subject Alternative Name extension
// for the first occurrence of:
// szOID_COMMON_NAME ("2.5.4.3")
// szOID_ORGANIZATIONAL_UNIT_NAME ("2.5.4.11")
// szOID_ORGANIZATION_NAME ("2.5.4.10")
// szOID_RSA_emailAddr ("1.2.840.113549.1.9.1")
//
// If none of the above attributes is found, then, searches the
// Subject Alternative Name extension for a rfc822Name choice.
//
// If still no match, then, returns the first attribute.
//
// Note, like CERT_NAME_ATTR_TYPE, searches the RDNs in reverse order.
//
// CERT_NAME_FRIENDLY_DISPLAY_TYPE
// First checks if the certificate has a CERT_FRIENDLY_NAME_PROP_ID
// property. If it does, then, this property is returned. Otherwise,
// returns the above CERT_NAME_SIMPLE_DISPLAY_TYPE.
//
// Returns the number of characters converted including the terminating null
// character. If pwszNameString is NULL or cchNameString is 0, returns the
// required size of the destination string (including the terminating null
// char). If the specified name type isn't found. returns an empty string
// with a returned character count of 1.
//
// If pwszNameString != NULL && cwszNameString != 0, returned pwszNameString
// is always NULL terminated.
//
// Note: cchNameString includes the NULL char.
//--------------------------------------------------------------------------
//+-------------------------------------------------------------------------
//--------------------------------------------------------------------------
WINCRYPT32API
DWORD
WINAPI
CertGetNameStringA(
IN PCCERT_CONTEXT pCertContext,
IN DWORD dwType,
IN DWORD dwFlags,
IN void *pvTypePara,
OUT OPTIONAL LPSTR pszNameString,
IN DWORD cchNameString
);
//+-------------------------------------------------------------------------
//--------------------------------------------------------------------------
WINCRYPT32API
DWORD
WINAPI
CertGetNameStringW(
IN PCCERT_CONTEXT pCertContext,
IN DWORD dwType,
IN DWORD dwFlags,
IN void *pvTypePara,
OUT OPTIONAL LPWSTR pszNameString,
IN DWORD cchNameString
);
#ifdef UNICODE
#define CertGetNameString CertGetNameStringW
#else
#define CertGetNameString CertGetNameStringA
#endif // !UNICODE
//+-------------------------------------------------------------------------
// Certificate name types
//--------------------------------------------------------------------------
#define CERT_NAME_EMAIL_TYPE 1
#define CERT_NAME_RDN_TYPE 2
#define CERT_NAME_ATTR_TYPE 3
#define CERT_NAME_SIMPLE_DISPLAY_TYPE 4
#define CERT_NAME_FRIENDLY_DISPLAY_TYPE 5
#define CERT_NAME_DNS_TYPE 6
#define CERT_NAME_URL_TYPE 7
#define CERT_NAME_UPN_TYPE 8
//+-------------------------------------------------------------------------
// Certificate name flags
//--------------------------------------------------------------------------
#define CERT_NAME_ISSUER_FLAG 0x1
#define CERT_NAME_DISABLE_IE4_UTF8_FLAG 0x00010000
//+=========================================================================
// Simplified Cryptographic Message Data Structures and APIs
//==========================================================================
//+-------------------------------------------------------------------------
// Conventions for the *pb and *pcb output parameters:
//
// Upon entry to the function:
// if pcb is OPTIONAL && pcb == NULL, then,
// No output is returned
// else if pb == NULL && pcb != NULL, then,
// Length only determination. No length error is
// returned.
// otherwise where (pb != NULL && pcb != NULL && *pcb != 0)
// Output is returned. If *pcb isn't big enough a
// length error is returned. In all cases *pcb is updated
// with the actual length needed/returned.
//--------------------------------------------------------------------------
//+-------------------------------------------------------------------------
// Type definitions of the parameters used for doing the cryptographic
// operations.
//--------------------------------------------------------------------------
//+-------------------------------------------------------------------------
// Callback to get and verify the signer's certificate.
//
// Passed the CertId of the signer (its Issuer and SerialNumber) and a
// handle to its cryptographic signed message's cert store.
//
// For CRYPT_E_NO_SIGNER, called with pSignerId == NULL.
//
// For a valid signer certificate, returns a pointer to a read only
// CERT_CONTEXT. The returned CERT_CONTEXT is either obtained from a
// cert store or was created via CertCreateCertificateContext. For either case,
// its freed via CertFreeCertificateContext.
//
// If a valid certificate isn't found, this callback returns NULL with
// LastError set via SetLastError().
//
// The NULL implementation tries to get the Signer certificate from the
// message cert store. It doesn't verify the certificate.
//
// Note, if the KEYID choice was selected for a CMS SignerId, then, the
// SerialNumber is 0 and the Issuer is encoded containing a single RDN with a
// single Attribute whose OID is szOID_KEYID_RDN, value type is
// CERT_RDN_OCTET_STRING and value is the KEYID. When the
// CertGetSubjectCertificateFromStore and
// CertFindCertificateInStore(CERT_FIND_SUBJECT_CERT) APIs see this
// special KEYID Issuer and SerialNumber, they do a KEYID match.
//--------------------------------------------------------------------------
typedef PCCERT_CONTEXT (WINAPI *PFN_CRYPT_GET_SIGNER_CERTIFICATE)(
IN void *pvGetArg,
IN DWORD dwCertEncodingType,
IN PCERT_INFO pSignerId, // Only the Issuer and SerialNumber
// fields have been updated
IN HCERTSTORE hMsgCertStore
);
//+-------------------------------------------------------------------------
// The CRYPT_SIGN_MESSAGE_PARA are used for signing messages using the
// specified signing certificate context.
//
// Either the CERT_KEY_PROV_HANDLE_PROP_ID or CERT_KEY_PROV_INFO_PROP_ID must
// be set for each rgpSigningCert[]. Either one specifies the private
// signature key to use.
//
// If any certificates and/or CRLs are to be included in the signed message,
// then, the MsgCert and MsgCrl parameters need to be updated. If the
// rgpSigningCerts are to be included, then, they must also be in the
// rgpMsgCert array.
//