CryptGetObjectUrl function (wincrypt.h)

Article
10/13/2021

The CryptGetObjectUrl function acquires the URL of the remote object from a certificate, certificate trust list (CTL), or certificate revocation list (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 of URLs would be in the array.

Syntax

BOOL CryptGetObjectUrl(
  [in]      LPCSTR           pszUrlOid,
  [in]      LPVOID           pvPara,
  [in]      DWORD            dwFlags,
  [out]     PCRYPT_URL_ARRAY pUrlArray,
  [in, out] DWORD            *pcbUrlArray,
  [out]     PCRYPT_URL_INFO  pUrlInfo,
  [in, out] DWORD            *pcbUrlInfo,
            LPVOID           pvReserved
);

Parameters

[in] pszUrlOid

A pointer to an object identifier (OID) that identifies the URL being requested. If the HIWORD of the pszUrlOid parameter is zero, the LOWORD specifies the integer identifier for the type of the specified structure.

This parameter can be one of the following values. For information about how these values affect the pvPara parameter, see the heading "For the pvPara parameter" in the Meaning column.

Value	Meaning
URL_OID_CERTIFICATE_ISSUER	Provides the URL of the certificate issuer retrieved from the authority information access extension or property of a certificate. For the pvPara parameter: A pointer to a CERT_CONTEXT structure that was issued by the issuer whose URL is being requested.
URL_OID_CERTIFICATE_CRL_DIST_POINT	Provides a list of URLs of the CRL distribution points retrieved from the CRL distribution point extension or property of a certificate. For the pvPara parameter: A pointer to a CERT_CONTEXT structure whose CRL distribution point is requested.
URL_OID_CERTIFICATE_CRL_DIST_POINT_AND_OCSP	Provides a list of OCSP and CRL distribution point URLs from the authority information access (AIA) and CRL distribution point extensions or properties of a certificate. The function returns any CRL distribution point URLs first. Before using any OCSP URLs, you must remove the L"ocsp:" prefix. For the pvPara parameter: A pointer to a CERT_CONTEXT structure whose OCSP and CRL distribution point URLs are requested.
URL_OID_CERTIFICATE_OCSP	Provides an OCSP URL from the authority information access (AIA) extension or property of a certificate. For the pvPara parameter: A pointer to a CERT_CONTEXT structure whose OCSP URL is requested.
URL_OID_CERTIFICATE_OCSP_AND_CRL_DIST_POINT	Provides a list of OCSP and CRL distribution point URLs from the authority information access (AIA) and CRL distribution point extensions or properties of a certificate. The function returns any OCSP URLs first. Before using any OCSP URLs, you must remove the L"ocsp:" prefix. For the pvPara parameter: A pointer to a CERT_CONTEXT structure whose OCSP and CRL distribution point URLs are requested.
URL_OID_CERTIFICATE_ONLY_OCSP	Provides a list of OCSP URLs from the authority information access (AIA) extension or property of a certificate. Before using any OCSP URLs, you must remove the L"ocsp:" prefix. For the pvPara parameter: A pointer to a CERT_CONTEXT structure whose OCSP URLs are requested.
URL_OID_CTL_ISSUER	Provides the URL of the CTL issuer retrieved from an authority information access attribute method encoded in each signer information in the PKCS #7 CTL. For the pvPara parameter: A pointer to a Signer Index CTL_CONTEXT structure that was issued by the issuer whose URL, identified by the signer index, is requested.
URL_OID_CTL_NEXT_UPDATE	Provides the URL of the next update of that CTL retrieved from an authority information access CTL extension, property, or signer information attribute method. For the pvPara parameter: A pointer to a Signer Index CTL_CONTEXT structure whose next update URL is requested, and an optional signer index, in case it is needed to check the signer information attributes.
URL_OID_CRL_ISSUER	Provides the URL of the CRL issuer retrieved from a property on a 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 information access extension method. For the pvPara parameter: A pointer to a CRL_CONTEXT structure that was issued by the issuer whose URL is requested.
URL_OID_CERTIFICATE_FRESHEST_CRL	Retrieves the most recent CRL extension or property of the certificate. For the pvPara parameter: The PCCERT_CONTEXT of a certificate whose most recent CRL distribution point is being requested.
URL_OID_CRL_FRESHEST_CRL	Retrieves the most recent CRL extension or property of the CRL. For the pvPara parameter: A pointer to a CERT_CRL_CONTEXT_PAIR structure that contains the base CRL of a certificate whose most recent CRL distribution point is being requested.
URL_OID_CROSS_CERT_DIST_POINT	Retrieves the cross certificate distribution point extension or property of the certificate. For the pvPara parameter: The PCCERT_CONTEXT of a certificate whose cross certificate distribution point is being requested.
URL_OID_CROSS_CERT_SUBJECT_INFO_ACCESS	Retrieves the cross certificate Subject Information Access extension or property of the certificate. For the pvPara parameter: The PCCERT_CONTEXT of a certificate whose cross certificate Subject Information Access is being requested.

[in] pvPara

A structure determined by the value of pszUrlOid. For details, see the description for the pszUrlOid parameter.

[in] dwFlags

A set of flags used to get the URL locator for an object. This can be zero or a combination of one or more of the following values.

Value	Meaning
CRYPT_GET_URL_FROM_PROPERTY	Locates the URL from the property of the object (the location of the data).
CRYPT_GET_URL_FROM_EXTENSION	Locates the URL from the extension of the object.
CRYPT_GET_URL_FROM_UNAUTH_ATTRIBUTE	Locates the URL from an unauthenticated attribute from the signer information data.
CRYPT_GET_URL_FROM_AUTH_ATTRIBUTE	Locates the URL from an authenticated attribute from the signer information data.

[out] pUrlArray

A pointer to a buffer to receive the data for the value entry. This parameter can be NULL to find the length of the buffer required to hold the data.

For more information, see Retrieving Data of Unknown Length.

[in, out] pcbUrlArray

A pointer to a DWORD that specifies the size, in bytes, of the buffer pointed to by the pUrlArray parameter. When the function returns, the DWORD contains the number of bytes stored in the buffer. This parameter can be NULL only if pUrlArray is NULL.

[out] pUrlInfo

An optional pointer to a CRYPT_URL_INFO structure that receives the data for the value entry.

[in, out] pcbUrlInfo

Note When processing the data returned in the buffer, applications must use the actual size of the data returned. The actual size can 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.

pvReserved

Reserved for future use and must be NULL.

Return value

If the function succeeds, the function returns nonzero (TRUE).

If the function fails, it returns zero (FALSE). For extended error information, call GetLastError.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	wincrypt.h
Library	Cryptnet.lib
DLL	Cryptnet.dll

Share via

CryptGetObjectUrl function (wincrypt.h)

Syntax

Parameters

Return value

Requirements

See also

Feedback

Additional resources