função de retorno de chamada PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET (wincrypt.h)

  • Artigo

A função de retorno de chamada PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET recupera um objeto . Você deve implementar essa função como parte do provedor personalizado. Atualmente, essa função é chamada apenas pelo pacote de segurança do Canal Seguro (Schannel).

Sintaxe

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET PfnCryptObjectLocatorProviderGet;

BOOL PfnCryptObjectLocatorProviderGet(
  [in, optional] LPVOID pPluginContext,
  [in, optional] PCRYPT_DATA_BLOB pIdentifier,
  [in]           DWORD dwNameType,
  [in]           PCERT_NAME_BLOB pNameBlob,
  [out]          PBYTE *ppbContent,
  [out]          DWORD *pcbContent,
  [out]          PCWSTR *ppwszPassword,
  [out]          PCRYPT_DATA_BLOB *ppIdentifier
)
{...}

Parâmetros

[in, optional] pPluginContext

Ponteiro para um buffer opcional definido por esse provedor e retornado pela função PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE . O buffer não é modificado pelo chamador. Seu provedor pode usar os dados para ajudá-lo a determinar quais ações executar ou manter informações adicionais.

[in, optional] pIdentifier

Ponteiro para uma estrutura CRYPTOAPI_BLOB que contém o identificador de objeto. Esse valor sempre deve ser NULL na primeira chamada para essa função.

[in] dwNameType

O formato de nome do parâmetro pNameBlob . Os valores possíveis são listados abaixo. A implementação dessa função deve ser capaz de processar CRYPT_OBJECT_LOCATOR_SPN_NAME_TYPE, que é passada pelo Schannel.

CRYPT_OBJECT_LOCATOR_SPN_NAME_TYPE (1 (0x1))

CRYPT_OBJECT_LOCATOR_LAST_RESERVED_NAME_TYPE (32 (0x20))

CRYPT_OBJECT_LOCATOR_FIRST_RESERVED_USER_NAME_TYPE (33 (0x21))

CRYPT_OBJECT_LOCATOR_LAST_RESERVED_USER_NAME_TYPE (0x0000FFFF)

[in] pNameBlob

Ponteiro para uma estrutura CRYPTOAPI_BLOB que contém o nome que o aplicativo de chamada está usando para identificar exclusivamente o objeto. Seu provedor usa esse nome para localizar o objeto solicitado. Atualmente, o Schannel envia um nome de host DNS (sistema de nomes de domínio) codificado em UTF8 com nomes de IDN convertidos de punycode.

[out] ppbContent

Ponteiro para uma matriz de bytes que contém o objeto a ser retornado.

[out] pcbContent

O tamanho, em bytes, do objeto apontado pelo parâmetro ppbContent .

[out] ppwszPassword

Cadeia de caracteres Unicode terminada em nulo que contém a senha, se houver, usada para criptografar o objeto. Se o objeto for um arquivo PFX (troca de informações pessoais), uma senha normalmente será usada para executar a criptografia. Esse valor poderá ser NULL se nenhuma senha for necessária.

[out] ppIdentifier

Endereço que recebe um ponteiro para um identificador opcional que pode ser usado durante chamadas subsequentes para essa função e para notificações de alteração. Para obter mais informações, consulte Comentários. Se o provedor definir esse valor como NULL, o Schannel usará internamente o valor do parâmetro pNameBlob .

Retornar valor

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

Se a função falhar, retorne zero (FALSE) e especifique um erro apropriado na função SetLastError . A maioria dos erros é passada por meio do Schannel inalterado, mas esse comportamento não é garantido. Alguns erros podem ser mapeados para outros erros.

Se um objeto não puder ser retornado para um determinado nome DNS (pNameBlob) ou identificador (pIdentifier), retorne FALSE e especifique CRYPT_E_OBJECT_LOCATOR_OBJECT_NOT_FOUND na função SetLastError .

Comentários

A função de retorno de chamada PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET atualmente é chamada apenas pelo pacote de segurança do Canal Seguro (Schannel). Você pode retornar um objeto que encapsula um dos seguintes:

  • Uma matriz de bytes PFX (troca de informações pessoais)
  • Um repositório de certificados.
  • Um BLOB genérico. No momento, não há suporte para isso no Schannel.
Quando essa função é chamada pela primeira vez, o Schannel envia um nome de host DNS no argumento pNameBlob para especificar o host para o qual o objeto se destina. Seu provedor deve processar o nome (corresponder a curingas, criar um caminho de arquivo e assim por diante) para determinar qual objeto encontrar.

Como muitos nomes de host podem ser mapeados para um objeto, seu provedor pode usar o parâmetro ppIdentifier para retornar um identificador definido internamente que pode ser usado em chamadas subsequentes pelas funções de CAPI (API de criptografia) para o provedor. Em seguida, o provedor pode usar o identificador para ajudar a localizar o objeto apropriado.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 8 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2012 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho wincrypt.h

Confira também

CRYPT_OBJECT_LOCATOR_PROVIDER_TABLE

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_RELEASE