Compartilhar via

Função CryptRetrieveObjectByUrlA (wincrypt.h)

  • Artigo

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 dados BLOBs. 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 da 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 de CertCloseStore.
CONTEXT_OID_CRL
CRL
 Recupere um ou mais listas de revogação de certificados (CRLs).

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 da 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 de CertCloseStore.
CONTEXT_OID_CTL
CTL
 Recupere uma ou mais listas de confiança de certificado (CTLs).

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 da 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 de 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 de 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 de CertCloseStore.
CONTEXT_OID_OCSP_RESP
Resposta OCSP
 ppvObject é o endereço de um ponteiro para uma estrutura de 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:

/ OptionalURLEscaped&Base64EncodedAdditionalData? OptionalAdditionalHTTPHeaders

O exemplo a seguir mostra os dados binários adicionais delimitados pela última marca de barra (/) e um cabeçalho Content-Type 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 delimitadores de última 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 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 emdecimal \0nome do atributo\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 está definido como NULL. Se pAuxInfo não estiver NULL, dwHttpStatusCode será definido como HTTP_STATUS_NOT_MODIFIED. Caso contrário, ppvObject é 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 é apenas para recuperação de fio.
CRYPT_PROXY_CACHE_RETRIEVAL
 Habilita a recuperação de cache de proxy de um objeto. Se um cache de proxy não foi explicitamente ignorado, fProxyCacheRetrieval está definido como TRUE em 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 do identificador de objeto (OID) 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 NULL nãoe pvVerify aponta para o contexto do 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 atingiu 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

Esse 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 í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 NULL e se o cbSize membro da estrutura estiver definido, esse parâmetro retornará a hora da última recuperação de fio bem-sucedida.

Valor de retorno

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

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

Observações

O gerenciador de recuperação de objeto remoto expõe dois modelos de provedor. Um deles é o modelo de 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 que criadores instaláveis dos identificadores de contexto (objetos) com base nos bits codificados recuperados. Eles são enviados com base no OID ( de identificador de objeto) especificado na chamada para CryptRetrieveObjectByUrl.

Objetos PKI individuais, como certificados, listas de confiabilidade, 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 protegida. 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.

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

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito Valor
de cliente com suporte mínimo Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino Windows
cabeçalho wincrypt.h
biblioteca Cryptnet.lib
de DLL Cryptnet.dll

Consulte também

CryptGetObjectUrl