[This is preliminary documentation and subject to change.]
The CryptRetrieveObjectByUrl function retrieves the PKI object where the location is given by an URL.
These remote objects are in encoded format and are retrieved in a "context" form.
#include <wincrypt.h>
BOOL WINAPI CryptRetrieveObjectByUrl(
LPCTSTR pszUrl, // in
LPCSTR pszObjectOid, // in
DWORD dwRetrievalFlags, // in
DWORD dwTimeout, // in
LPVOID *ppvObject, // out
HCRYPTASYNC hAsyncRetrieve, // in
PCRYPT_CREDENTIALS pCredentials, // in/optional
LPVOID pvVerify, // in/optional
LPVOID pvReserved // in/optional
);
| OID Value | Description | Returned ppvObject type |
|---|---|---|
| NULL | blob | Encoded bits are returned in a single buffer with a count, array of pointers, and data which must be freed with CryptMemFree. |
| CONTEXT_OID_ CERTIFICATE |
certificate | PCERT_CONTEXT for single object retrieval. HCERTSTORE, which contains the certificates, for multiple object retrieval. |
| CONTEXT_OID_ CRL |
CRL | PCRL_CONTEXT for single object retrieval. HCERTSTORE, which contains the CRLs, for multiple object retrieval. |
| CONTEXT_OID_ CTL |
CTL | PCTL_CONTEXT for single object retrieval. HCERTSTORE, which contains the CTLs, for multiple object retrieval. |
| CONTEXT_OID_ PKCS7 |
PKCS7 | HCERTSTORE containing the object from the message. |
| CONTEXT_OID_ CAPI2_ANY |
Function will determine appropriate item | HCERTSTORE containing the object. |
| Flag value | Description |
|---|---|
| CRYPT_RETRIEVE_ MULTIPLE_OBJECTS |
Retrieves multiple objects if available. All objects must be of a homogeneous object type as determined by the pszObjectOid, unless the OID Value is CONTEXT_OID_CAPI2_ANY. |
| CRYPT_CACHE_ ONLY_RETRIEVAL |
Retrieves the encoded bits from the URL cache only. Do not use the wire to retrieve the URL. |
| CRYPT_WIRE_ONLY_ RETRIEVAL |
Retrieves the encoded bits from the wire only. Does not use the URL cache. |
| CRYPT_DONT_ CACHE_RESULT |
Does not store the retrieved encoded bits to the URL cache. If this flag is not set, the retrieved URL is cached. |
| CRYPT_ASYNC_ RETRIEVAL |
Retrieves the object(s) asynchronously. If this flag is not set, hAsyncRetrieve must be NULL. (This flag is not supported in Windows NT® 5.0 Beta). |
| CRYPT_VERIFY_ CONTEXT_ SIGNATURE |
Gets signature verification on the context created. In this case pszObjectOid must be non-NULL and pvVerify points to the signer certificate context. |
| CRYPT_VERIFY_ DATA_HASH |
Gets verification of the blob data retrieved by the protocol. The pvVerify points to an URL_DATA_HASH structure (This flag is not supported in Windows NT 5.0 Beta). |
If the function succeeds, the return value is TRUE. If it does not succeed, the return value is FALSE. To retrieve extended error information, use the GetLastError function.
The remote object retrieval manager exposes two provider models. One is the "Scheme Provider" model which allows for installable protocol providers as defined by the URL scheme e.g. ldap, http, ftp, file. The scheme provider entry point is the same as the CryptRetrieveObjectByUrl; however, the *ppvObject returned is ALWAYS a counted array of encoded bits (one per object retrieved).
The second provider model is the "Context Provider" model that allows for installable creators of the context handles (objects) based on the retrieved encoded bits. These are dispatched based on the object OID given in the call to CryptRetrieveObjectByUrl.
This functions supports multiple URL schemes such as "http:", "ftp:", "ldap:", "file:" as well as newly defined schemes.
Retrieval of individual PKI objects, such as certificates, trusts lists, revocation lists, PKCS #7 messages, and multiple homogenous objects is possible.
// EXAMPLE CODE FOR USING CryptRetrieveObjectByUrl().
// Assume that a pointer to the URL (pszUrl) and the credentials
// structure (pCredentials) is already known.
// Set up the variables.
LPCTSTR pszUrl; // Pointer to a valid URL
LPCSTR pszObjectOid; // Pointer to an OID
DWORD dwRetrievalFlags; // Retrieval flag
DWORD dwTimeout; // Timeout value (milliseconds)
LPVOID* ppvObject; // Return address
HCRYPTASYNC hAsyncRetrieve; // Set to NULL- not utilized in
// Windows NT 5.0 Beta
PCRYPT_CREDENTIALS pCredentials;// Pointer to Credentials structure
PCRL_CONTEXT pvVerify; // Pointer to Verification object
LPVOID pvReserved; // NULL- reserved for future use
BOOL fResult; // Return value- True if function
// successful
// False if function fails
// call to CryptRetrieveObjectByUrl to get the URL object
fResult= CryptRetrieveObjectByUrl(
pszUrl, // in- pszUrl- initialized elsewhere
CONTEXT_OID_CRL, // in- OID
CRYPT_CACHE_ONLY_RETRIEVAL,
// in- Use the cache only. Do not go
// onto the wire to retrieve the
// URL.
0, // in- timeout set 0
ppvObject, // out- Address of returned object
NULL, // in- hAsyncRetrieve- set to NULL
NULL, // in/optional- pCredentials set to
// NULL, using cache only
NULL, // in/optional- pvVerify- not
// interested in getting signer's
// verification
NULL); // in/optional- pvReserved
if (fResult){ // returned value is TRUE
// CryptGetObjectUrl is successful
cout<< "Call to CryptRetrieveObjectByUrl successful"<< endl
<< "The object, "<< ppvObject<< endl
<< "is at "<< &ppvObject<< endl;
}
else { // returned value is FALSE
cout<< "Call to CryptRetrieveObjectByUrl failed"<< endl
<< "error code = "<< GetLastError<< endl;
}
Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in wincrypt.h.
Import Library: Use cryptnet.lib.