PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET fonction de rappel (wincrypt.h)

Article
03/06/2024

La fonction de rappel PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET récupère un objet. Vous devez implémenter cette fonction dans le cadre de votre fournisseur personnalisé. Cette fonction est actuellement appelée uniquement par le package de sécurité Schannel (Secure Channel).

Syntaxe

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
)
{...}

Paramètres

[in, optional] pPluginContext

Pointeur vers une mémoire tampon facultative définie par ce fournisseur et retournée par la fonction PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE . La mémoire tampon n’est pas modifiée par l’appelant. Votre fournisseur peut utiliser les données pour l’aider à déterminer les actions à effectuer ou à conserver des informations supplémentaires.

[in, optional] pIdentifier

Pointeur vers une structure CRYPTOAPI_BLOB qui contient l’identificateur d’objet. Cette valeur doit toujours être NULL lors du premier appel à cette fonction.

[in] dwNameType

Format de nom du paramètre pNameBlob . Les valeurs possibles sont répertoriées ci-dessous. L’implémentation de cette fonction doit être en mesure de traiter CRYPT_OBJECT_LOCATOR_SPN_NAME_TYPE transmis par 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

Pointeur vers une structure CRYPTOAPI_BLOB qui contient le nom que l’application appelante utilise pour identifier l’objet de manière unique. Votre fournisseur utilise ce nom pour localiser l’objet demandé. Schannel envoie actuellement un nom d’hôte DNS (système de noms de domaine) encodé en UTF8 avec des noms IDN convertis à partir de punycode.

[out] ppbContent

Pointeur vers un tableau d’octets qui contient l’objet à retourner.

[out] pcbContent

Taille, en octets, de l’objet pointé vers le paramètre ppbContent .

[out] ppwszPassword

Chaîne Unicode terminée par null qui contient le mot de passe, le cas échéant, utilisé pour chiffrer l’objet. Si l’objet est un fichier d’échange d’informations personnelles (PFX), un mot de passe est généralement utilisé pour effectuer le chiffrement. Cette valeur peut être NULL si aucun mot de passe n’est requis.

[out] ppIdentifier

Adresse qui reçoit un pointeur vers un identificateur facultatif qui peut être utilisé lors des appels suivants à cette fonction et pour les notifications de modification. Pour plus d'informations, consultez la section Notes. Si votre fournisseur définit cette valeur sur NULL, Schannel utilise en interne la valeur du paramètre pNameBlob .

Valeur retournée

Si la fonction réussit, retournez une valeur différente de zéro (TRUE).

Si la fonction échoue, retourne zéro (FALSE) et spécifiez une erreur appropriée dans la fonction SetLastError . La plupart des erreurs sont transmises via Schannel sans changement, mais ce comportement n’est pas garanti. Certaines erreurs peuvent être mappées à d’autres erreurs.

Si un objet ne peut pas être retourné pour un nom DNS donné (pNameBlob) ou un identificateur (pIdentifier), retournez FALSE et spécifiez CRYPT_E_OBJECT_LOCATOR_OBJECT_NOT_FOUND dans la fonction SetLastError .

Remarques

La fonction de rappel PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET est actuellement appelée uniquement par le package de sécurité Du canal sécurisé (Schannel). Vous pouvez retourner un objet qui encapsule l’un des éléments suivants :

Tableau d’octets d’échange d’informations personnelles (PFX)
Magasin de certificats.
Objet BLOB générique. Cette opération n’est actuellement pas prise en charge par Schannel.

Lorsque cette fonction est appelée pour la première fois, Schannel envoie un nom d’hôte DNS dans l’argument pNameBlob pour spécifier l’hôte pour lequel l’objet est destiné. Votre fournisseur doit traiter le nom (mettre en correspondance des caractères génériques, générer un chemin d’accès de fichier, etc.) pour déterminer l’objet à rechercher.

Étant donné que de nombreux noms d’hôtes peuvent être mappés à un seul objet, votre fournisseur peut utiliser le paramètre ppIdentifier pour renvoyer un identificateur défini en interne qui peut être utilisé dans les appels suivants par les fonctions d’API de chiffrement (CAPI) au fournisseur. Le fournisseur peut ensuite utiliser l’identificateur pour faciliter la recherche de l’objet approprié.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2012 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	wincrypt.h

Voir aussi

CRYPT_OBJECT_LOCATOR_PROVIDER_TABLE

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_RELEASE

Partager via