PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET función de devolución de llamada (wincrypt.h)

  • Artículo

La función de devolución de llamada PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET recupera un objeto . Debe implementar esta función como parte del proveedor personalizado. Actualmente, solo el paquete de seguridad del canal seguro (Schannel) llama a esta función.

Sintaxis

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

Puntero a un búfer opcional definido por este proveedor y devuelto por la función PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE . El autor de la llamada no modifica el búfer. El proveedor puede usar los datos para ayudarle a determinar qué acciones realizar o mantener información adicional.

[in, optional] pIdentifier

Puntero a una estructura CRYPTOAPI_BLOB que contiene el identificador de objeto. Este valor siempre debe ser NULL en la primera llamada a esta función.

[in] dwNameType

Formato de nombre del parámetro pNameBlob . Los valores posibles se enumeran a continuación. La implementación de esta función debe ser capaz de procesar CRYPT_OBJECT_LOCATOR_SPN_NAME_TYPE, que Schannel pasa.

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

Puntero a una estructura de CRYPTOAPI_BLOB que contiene el nombre que usa la aplicación que realiza la llamada para identificar el objeto de forma única. El proveedor usa este nombre para buscar el objeto solicitado. Schannel envía actualmente un nombre de host DNS (sistema de nombres de dominio) codificado en UTF8 con nombres IDN convertidos a partir de punycode.

[out] ppbContent

Puntero a una matriz de bytes que contiene el objeto que se va a devolver.

[out] pcbContent

Tamaño, en bytes, del objeto al que apunta el parámetro ppbContent .

[out] ppwszPassword

Cadena Unicode terminada en NULL que contiene la contraseña, si existe, utilizada para cifrar el objeto. Si el objeto es un archivo de intercambio de información personal (PFX), normalmente se usará una contraseña para realizar el cifrado. Este valor puede ser NULL si no se requiere ninguna contraseña.

[out] ppIdentifier

Dirección que recibe un puntero a un identificador opcional que se puede usar durante las llamadas posteriores a esta función y para las notificaciones de cambio. Para obtener más información, vea la sección Comentarios. Si el proveedor establece este valor en NULL, Schannel usa internamente el valor del parámetro pNameBlob .

Valor devuelto

Si la función se realiza correctamente, devuelva un valor distinto de cero (TRUE).

Si se produce un error en la función, devuelva cero (FALSE) y especifique un error adecuado en la función SetLastError . La mayoría de los errores se pasan a través de Schannel sin modificar, pero este comportamiento no está garantizado. Algunos errores se pueden asignar a otros errores.

Si no se puede devolver un objeto para un nombre DNS determinado (pNameBlob) o identificador (pIdentifier), devuelva FALSE y especifique CRYPT_E_OBJECT_LOCATOR_OBJECT_NOT_FOUND en la función SetLastError .

Comentarios

Actualmente, solo el paquete de seguridad del canal seguro (Schannel) llama a la función de devolución de llamada PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET . Puede devolver un objeto que encapsula uno de los siguientes elementos:

  • Matriz de bytes de intercambio de información personal (PFX)
  • Un almacén de certificados.
  • Un BLOB genérico. Actualmente, Schannel no admite esto.
Cuando se llama a esta función por primera vez, Schannel envía un nombre de host DNS en el argumento pNameBlob para especificar el host para el que está previsto el objeto. El proveedor debe procesar el nombre (coincidir con caracteres comodín, crear una ruta de acceso de archivo, etc.) para determinar qué objeto buscar.

Dado que muchos nombres de host se pueden asignar a un objeto, el proveedor puede usar el parámetro ppIdentifier para devolver un identificador definido internamente que las funciones de la API de criptografía (CAPI) pueden usar en las llamadas posteriores al proveedor. A continuación, el proveedor puede usar el identificador para ayudar a encontrar el objeto adecuado.

Requisitos

Requisito Value
Cliente mínimo compatible Windows 8 [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2012 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado wincrypt.h

Consulte también

CRYPT_OBJECT_LOCATOR_PROVIDER_TABLE

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_RELEASE