[This is preliminary documentation and subject to change.]
The CryptGetObjectUrl function gets the URL of the remote object from a certificate, CTL, or CRL.
The function takes the object, decodes it, and provides a pointer to an array of URLs from the object. For example; from a certificate, a CRL distribution list (URLs) would be in the array.
#include <wincrypt.h>
BOOL WINAPI CryptGetObjectUrl(
LPCSTR pszUrlOid, // in
LPVOID pvPara, // in
DWORD dwFlags, // in
PCRYPT_URL_ARRAY pUrlArray, // out/optional
DWORD* pcbUrlArray, // in/out
PCRYPT_URL_INFO pUrlInfo, // out/optional
DWORD* pcbUrlInfo, // in/out/optional
LPVOID pvReserved // in/optional
);
OIDs extend the functionality of the CryptoAPI. See OID Overview for additional information.
Support for registering the new functionality in a system registry must be provided in the new DLL along with the new function. See Registering the New Functionality.
See The following table is a list of currently supported OIDs:
| OID | OID value | Meaning |
|---|---|---|
| URL_OID_ CERTIFICATE_ ISSUER |
(LPCSTR)1 | Given a certificate, provides the URL of the certificate issuer. This will be retrieved from the authority info access extension or property on the certificate. |
| URL_OID_ CERTIFICATE_CRL_ DIST_POINT |
(LPCSTR)2 | Given a certificate, provides a list URLs of the CRL distribution points. This will be retrieved from the CRL distribution point extension or property on the certificate. |
| URL_OID_CTL_ ISSUER |
(LPCSTR)3 | Given a CTL, provides the URL of the CTL issuer. This will be retrieved from an authority info access attribute method encoded in each signer info in the PKCS #7 (CTL). |
| URL_OID_CTL_ NEXT_UPDATE |
(LPCSTR)4 | Given a CTL, provides the URL of the next update of that CTL. This is retrieved from an authority info access CTL extension, property, or signer info attribute method. |
| URL_OID_CRL_ ISSUER |
(LPCSTR)5 | Given a CRL, provides the URL of the CRL issuer. This is retrieved from a property on the CRL that was inherited from the subject certificate (either from the subject certificate issuer or the subject certificate distribution point extension). It is encoded as an authority info access extension method. |
| Flag value | Description |
|---|---|
| CRYPT_GET_URL_ FROM_PROPERTY |
Locates the URL from the object's property (the location of the data). |
| CRYPT_GET_URL_ FROM_EXTENSION |
Locates the URL from the object's extension. |
| CRYPT_GET_URL_ FROM_UNAUTH_ ATTRIBUTE |
Locates the URL from an unauthenticated attribute from the signer info data. |
| CRYPT_GET_URL_ FROM_AUTH_ ATTRIBUTE |
Locates the URL from an authenticated attribute from the signer info data. |
For more information, see Common In/Out Parameter Conventions.
For more information, see Common In/Out Parameter Conventions.
Note When processing the data returned in the buffer, applications need to use the actual size of the data returned. The actual size may be slightly smaller than the size of the buffer specified on input. (On input, buffer sizes are usually specified large enough to ensure that the largest possible output data will fit in the buffer.) On output, the variable pointed to by this parameter is updated to reflect the actual size of the data copied to the buffer.
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.
CryptGetObjectUrl has the same signature as UrlDllGetObjectUrl. The developer can implement a UrlDllGetObjectUrl with the signature of CryptGetObjectUrl and install it for the OID.
// EXAMPLE CODE FOR USING CryptGetObjectUrl().
// Assume that a pointer to URL in a PCCTL_CONTEXT
// (pvPara) is already known.
// Set up the variables.
LPCSTR pszUrlOid; // Pointer to object identifier
PCCTL_CONTEXT *pvPara; // Pointer to URL
DWORD dwFlags; // Flag values
PCRYPT_URL_ARRAY pUrlArray= NULL;
// Pointer to URl array- initialize to NULL
DWORD cbUrlArray;
PCRYPT_URL_INFO pUrlInfo= NULL;
// Pointer to URL buffer- initialize to NULL
DWORD cbUrlInfo;
LPVOID *pvReserved; // Reserved for future use
BOOL fResult; // Return value- True if function successful
// False if function fails
// first call to CryptGetObjectUrl to get the size of array length
fResult= CryptGetObjectUrl(
URL_OID_CTL_ISSUER,// in- pszUrlOid- Get the URL from a CTL
// ISSUER
pvPara, // in- Pointer to a signer index
// initialized elsewhere
CRYPT_GET_URL_FROM_PROPERTY,
// in- dwFlags
NULL, // out/optional- pUrlArray- set to NULL
// to allocate memory
&cbUrlArray, // in/out- pUrlArray array length
NULL, // out/optional- pUrlInfo- set to NULL
// to allocate memory
&cbUrlInfo, // in/out/optional- pUrlInfo size
NULL); // in/optional- pvReserved
if (fResult){ // returned value is TRUE
// CryptGetObjectUrl is successful
cout<< "First call to CryptGetObjectUrl successful"<< endl;
pUrlArray = (PCRYPT_URL_ARRAY)malloc (cbUrlArray);
pUrlInfo = (PCRYPT_URL_INFO)malloc (cbUrlInfo);
cout<< "memory allocated" << endl;
}
else { // returned value is FALSE
cout<< "First call to CryptGetObjectUrl failed"<< endl;
}
// Function call to get the URL
fResult= CryptGetObjectUrl(
URL_OID_CTL_ISSUER,// in- pszUrlOid- Get the URL from a CTL
// ISSUER
pvPara, // in- Pointer to a signer index
// initialized elsewhere
CRYPT_GET_URL_FROM_PROPERTY,
// in- dwFlags
pUrlArray, // out/optional- pUrlArray
&cbUrlArray, // in/out- pUrlArray array length
pUrlInfo, // out/optional- pUrlInfo
&cbUrlInfo, // in/out/optional- pUrlInfo size
NULL); // in/optional- pvReserved
if (fResult){ // returned value is TRUE
// CryptGetObjectUrl is successful
cout<< "Second call to CryptGetObjectUrl successful"<< endl
<< "The URL is "<< pUrlInfo<< endl;
}
else { // returned value is FALSE
cout<< "Second call to CryptGetObjectUrl failed"<< endl
<< "error code = "<< GetLastError<< endl;
}
// free memory
free(pUrlArray);
free(pUrlInfo);
Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in wincrypt.h.
Import Library: Use cryptnet.lib.