Função CryptRetrieveObjectByUrlA (wincrypt.h)

A função CryptRetrieveObjectByUrl recupera o objeto PKI (infraestrutura de chave pública) de um local especificado por uma URL.

Esses objetos remotos estão em formato codificado e são recuperados em um formulário de "contexto".

Sintaxe

BOOL CryptRetrieveObjectByUrlA(
  [in]           LPCSTR                   pszUrl,
  [in]           LPCSTR                   pszObjectOid,
  [in]           DWORD                    dwRetrievalFlags,
  [in]           DWORD                    dwTimeout,
  [out]          LPVOID                   *ppvObject,
  [in]           HCRYPTASYNC              hAsyncRetrieve,
  [in, optional] PCRYPT_CREDENTIALS       pCredentials,
  [in, optional] LPVOID                   pvVerify,
  [in]           PCRYPT_RETRIEVE_AUX_INFO pAuxInfo
);

Parâmetros

[in] pszUrl

O endereço de um objeto PKI a ser recuperado. Há suporte para os seguintes esquemas:

[in] pszObjectOid

O endereço de uma cadeia de caracteres ANSI terminada em nulo que identifica o tipo de objeto a ser recuperado. Esse pode ser um dos valores a seguir.

Valor Significado
NULL
BLOB
Recuperar um ou mais BLOBs de dados. Os bits codificados são retornados em uma matriz de BLOBs. ppvObject é o endereço de um ponteiro de estrutura CRYPT_BLOB_ARRAY que recebe a matriz BLOB. Quando essa estrutura não for mais necessária, você deverá liberá-la passando o endereço dessa estrutura para a função CryptMemFree .
CONTEXT_OID_CERTIFICATE
certificado
Recupere um ou mais certificados.

Se um único objeto estiver sendo recuperado, ppvObject será o endereço de um ponteiro de estrutura CERT_CONTEXT que recebe o contexto. Quando esse contexto não for mais necessário, você deverá liberá-lo passando o ponteiro de estrutura CERT_CONTEXT para a função CertFreeCertificateContext .

Se vários objetos estiverem sendo recuperados, ppvObject será o endereço de uma variável HCERTSTORE que recebe o identificador de um repositório que contém os certificados. Quando esse repositório não for mais necessário, você deverá fechá-lo passando esse identificador para a função CertCloseStore .

CONTEXT_OID_CRL
CRL
Recupere uma ou mais CRLs (listas de revogação de certificados ).

Se um único objeto estiver sendo recuperado, ppvObject será o endereço de um ponteiro de estrutura CRL_CONTEXT que recebe o contexto. Quando esse contexto não for mais necessário, você deverá liberá-lo passando o ponteiro de estrutura CRL_CONTEXT para a função CertFreeCRLContext .

Se vários objetos estiverem sendo recuperados, ppvObject será o endereço de uma variável HCERTSTORE que recebe o identificador de um repositório que contém as CRLs. Quando esse repositório não for mais necessário, você deverá fechá-lo passando esse identificador para a função CertCloseStore .

CONTEXT_OID_CTL
CTL
Recuperar uma ou mais CTLs ( listas de confiança de certificado ).

Se um único objeto estiver sendo recuperado, ppvObject será o endereço de um ponteiro de estrutura CTL_CONTEXT que recebe o contexto. Quando esse contexto não for mais necessário, você deverá liberá-lo passando o ponteiro de estrutura CTL_CONTEXT para a função CertFreeCTLContext .

Se vários objetos estiverem sendo recuperados, ppvObject será o endereço de uma variável HCERTSTORE que recebe o identificador de um repositório que contém as CTLs. Quando esse repositório não for mais necessário, você deverá fechá-lo passando esse identificador para a função CertCloseStore .

CONTEXT_OID_PKCS7
PKCS7
ppvObject é o endereço de uma variável HCERTSTORE que recebe o identificador de um repositório que contém os objetos da mensagem. Quando esse repositório não for mais necessário, você deverá fechá-lo passando esse identificador para a função CertCloseStore .
CONTEXT_OID_CAPI2_ANY
A função determinará o item apropriado
ppvObject é o endereço de uma variável HCERTSTORE que recebe o identificador de um repositório que contém os objetos. Quando esse repositório não for mais necessário, você deverá fechá-lo passando esse identificador para a função CertCloseStore .
CONTEXT_OID_OCSP_RESP
Resposta OCSP
ppvObject é o endereço de um ponteiro para uma estrutura CRYPT_BLOB_ARRAY .

[in] dwRetrievalFlags

Determina se é necessário usar a URL armazenada em cache ou uma URL recuperada da URL de transmissão. O formulário no qual os objetos são retornados é determinado pelo valor de pszObjectOid.

Valor Significado
CRYPT_AIA_RETRIEVAL
Valida o conteúdo recuperado por uma URL de transmissão antes de gravar a URL no cache.

O provedor padrão não dá suporte ao protocolo HTTPS para recuperações do AIA.

CRYPT_ASYNC_RETRIEVAL
Não há suporte para esse valor.
CRYPT_CACHE_ONLY_RETRIEVAL
Recupera os bits codificados somente do cache de URL. Não use o fio para recuperar a URL.
CRYPT_DONT_CACHE_RESULT
Não armazena os bits codificados recuperados no cache de URL. Se esse sinalizador não estiver definido, a URL recuperada será armazenada em cache.
CRYPT_HTTP_POST_RETRIEVAL
Usa o método POST em vez do método GET padrão para recuperações HTTP.

Em uma URL POST, os dados binários adicionais e as cadeias de caracteres de cabeçalho são acrescentados à URL base no seguinte formato:

Baseurl/OptionalURLEscaped&Base64EncodedAdditionalData?OptionalAdditionalHTTPHeaders

O exemplo a seguir mostra os dados binários adicionais delimitados pela última barra (/) e um cabeçalho Tipo de Conteúdo delimitado por um ponto de interrogação (?) acrescentado a uma URL base.

http://ocsp.openvalidation.org/MEIwQDA%2BMDwwOjAJBgUrDgMCGgUABBQdKNEwjytjKBQADcgM61jfflNpyQQUv1NDgnjQnsOA5RtnygUA37lIg6UCAQI%3D?Content-Type: application/ocsp-request

Quando esse sinalizador é definido, a função CryptRetrieveObjectByUrl analisa a URL usando os últimos delimitadores de barra (/) e ponto de interrogação (?). A cadeia de caracteres, que é delimitada por uma marca de barra (/), contém uma URL sem escape (ou seja, uma URL de texto sem formatação sem caracteres de escape ou sequências de escape) e dados Base64 decodificados no formulário binário antes de serem passados para a função WinHttpSendRequest como o parâmetro lpOptional . A cadeia de caracteres delimitada por um ponto de interrogação (?) é passada para a função WinHttpSendRequest como o parâmetro pwszHeaders .

CRYPT_LDAP_AREC_EXCLUSIVE_RETRIEVAL
Executa a pesquisa DNS somente registro A na cadeia de caracteres de host fornecida, impedindo a geração de consultas DNS falsas ao resolver nomes de host. Esse sinalizador deve ser usado ao passar um nome de host em vez de um nome de domínio.
CRYPT_LDAP_INSERT_ENTRY_ATTRIBUTE
Recupera o índice de entrada e o nome do atributo para cada objeto LDAP. O início de cada BLOB retornado contém a seguinte cadeia de caracteres ANSI:

"índice de entrada no nome do atributo decimal\0\0"

Quando esse sinalizador é definido, pszObjectOid deve ser NULL para que um BLOB seja retornado. Esse sinalizador só se aplica ao esquema ldap.

CRYPT_LDAP_SCOPE_BASE_ONLY_RETRIEVAL
Falhará se o escopo de pesquisa LDAP não estiver definido como base na URL. Use somente com LDAP.
CRYPT_LDAP_SIGN_RETRIEVAL
Assina digitalmente todo o tráfego LDAP de e para um servidor usando o protocolo de autenticação Kerberos. Esse recurso fornece integridade exigida por alguns aplicativos.
CRYPT_NO_AUTH_RETRIEVAL
Inibe o tratamento automático de autenticação.
CRYPT_NOT_MODIFIED_RETRIEVAL
Habilita uma recuperação de URL HTTP condicional. Quando esse sinalizador é definido, para uma recuperação condicional que retorna HTTP_STATUS_NOT_MODIFIED, CryptRetrieveObjectByUrl retorna TRUE e ppvObject é definido como NULL. Se pAuxInfo não for NULL, dwHttpStatusCode será definido como HTTP_STATUS_NOT_MODIFIED. Caso contrário, ppvObject será atualizado para uma recuperação bem-sucedida.
CRYPT_OFFLINE_CHECK_RETRIEVAL
Mantém o controle de falhas e atrasos offline antes de atingir o fio em recuperações subsequentes. Esse valor destina-se apenas à recuperação eletrônica.
CRYPT_PROXY_CACHE_RETRIEVAL
Habilita a recuperação de cache de proxy de um objeto . Se um cache de proxy não tiver sido explicitamente ignorado, fProxyCacheRetrieval será definido como TRUE no pAuxInfo. Esse valor só se aplica às recuperações de URL HTTP.
CRYPT_RETRIEVE_MULTIPLE_OBJECTS
Recupera vários objetos, se disponível. Todos os objetos devem ser de um tipo de objeto homogêneo, conforme determinado pelo valor de pszObjectOid, a menos que o valor OID ( identificador de objeto ) seja CONTEXT_OID_CAPI2_ANY.
CRYPT_STICKY_CACHE_RETRIEVAL
Marca a URL como isenta de ser liberada do cache. Para obter mais informações, consulte STICKY_CACHE_ENTRY no INTERNET_CACHE_ENTRY_INFO.
CRYPT_VERIFY_CONTEXT_SIGNATURE
Adquire a verificação de assinatura no contexto criado. Nesse caso , pszObjectOid deve ser não NULL e pvVerify aponta para o contexto de certificado do signatário.
CRYPT_VERIFY_DATA_HASH
Esse sinalizador não é implementado. Não o use.
CRYPT_WIRE_ONLY_RETRIEVAL
Recupera os bits codificados somente do fio. Não usa o cache de URL.

[in] dwTimeout

Especifica o número máximo de milissegundos a aguardar a recuperação. Se um valor igual a zero for especificado, essa função não atingirá o tempo limite. Esse parâmetro não será usado se o esquema de URL for file:///.

[out] ppvObject

O endereço de um ponteiro para o objeto retornado. O tipo de retorno pode ser um dos tipos com suporte mostrados em pszObjectOid.

[in] hAsyncRetrieve

Esse parâmetro é reservado e deve ser definido como NULL.

[in, optional] pCredentials

Este parâmetro não é usado.

[in, optional] pvVerify

Um ponteiro para um objeto de verificação. Esse objeto é uma função do parâmetro dwRetrievalFlags . Pode ser NULL para indicar que o chamador não está interessado em obter o contexto ou o índice do certificado do signatário se dwRetrievalFlags estiver CRYPT_VERIFY_CONTEXT_SIGNATURE.

[in] pAuxInfo

Um ponteiro opcional para uma estrutura CRYPT_RETRIEVE_AUX_INFO . Se não for NULL e se o membro cbSize da estrutura estiver definido, esse parâmetro retornará a hora da última recuperação de fio bem-sucedida.

Retornar valor

Se a função for bem-sucedida, o valor retornado será diferente de zero (TRUE).

Se a função falhar, o valor retornado será zero (FALSE).

Comentários

O gerenciador de recuperação de objeto remoto expõe dois modelos de provedor. Um deles é o modelo provedor de esquema que permite provedores de protocolo instaláveis conforme definido pelo esquema de URL, ou seja, ldap, http, ftp ou arquivo. O ponto de entrada do provedor de esquema é o mesmo que a função CryptRetrieveObjectByUrl ; no entanto, o *ppvObject retornado é sempre uma matriz contada de bits codificados (um por objeto recuperado).

O segundo modelo de provedor é o modelo provedor de contexto que permite criadores instaláveis dos identificadores de contexto (objetos) com base nos bits codificados recuperados. Eles são enviados com base no OID (identificador de objeto ) especificado na chamada para CryptRetrieveObjectByUrl.

Objetos PKI individuais, como certificados, listas de relações de confiança, listas de revogação, mensagens PKCS nº 7 e vários objetos homogêneos podem ser recuperados. A partir do Windows Vista com o Service Pack 1 (SP1) e o Windows Server 2008, a segurança das recuperações "http:" e "ldap:" foi endurecida. Essa função dá suporte a esquemas de URL "http:" e "ldap:", bem como esquemas recém-definidos.

Windows XP: não há suporte para "ftp:" para recuperação de rede.

Nota Por padrão, não há suporte para "file:" para recuperação de rede.
 

Observação

O cabeçalho wincrypt.h define CryptRetrieveObjectByUrl como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

   
Cliente mínimo com suporte Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho wincrypt.h
Biblioteca Cryptnet.lib
DLL Cryptnet.dll

Confira também

CryptGetObjectUrl