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:
- ldap (Lightweight Directory Access Protocol)
- http
- https (CRL (lista de certificados revogados) ou somente recuperações de protocolo OCSP (status certificado online)
- file
[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 |
|---|---|
|
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 . |
|
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 . |
|
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 . |
|
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 . |
|
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 . |
|
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 . |
|
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 |
|---|---|
|
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. |
|
Não há suporte para esse valor. |
|
Recupera os bits codificados somente do cache de URL. Não use o fio para recuperar a URL. |
|
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. |
|
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.
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 . |
|
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. |
|
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. |
|
Falhará se o escopo de pesquisa LDAP não estiver definido como base na URL. Use somente com LDAP. |
|
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. |
|
Inibe o tratamento automático de autenticação. |
|
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. |
|
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. |
|
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. |
|
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. |
|
Marca a URL como isenta de ser liberada do cache. Para obter mais informações, consulte STICKY_CACHE_ENTRY no INTERNET_CACHE_ENTRY_INFO. |
|
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. |
|
Esse sinalizador não é implementado. Não o use. |
|
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.
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 |