PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET funzione di callback (wincrypt.h)

Articolo
03/03/2024

La funzione di callback PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET recupera un oggetto. È necessario implementare questa funzione come parte del provider personalizzato. Questa funzione è attualmente chiamata solo dal pacchetto di sicurezza Secure Channel (Schannel).

Sintassi

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

Parametri

[in, optional] pPluginContext

Puntatore a un buffer facoltativo definito da questo provider e restituito dalla funzione PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE . Il buffer non viene modificato dal chiamante. Il provider può usare i dati per determinare quali azioni eseguire o mantenere informazioni aggiuntive.

[in, optional] pIdentifier

Puntatore a una struttura CRYPTOAPI_BLOB contenente l'identificatore dell'oggetto. Questo valore deve sempre essere NULL nella prima chiamata a questa funzione.

[in] dwNameType

Formato del nome del parametro pNameBlob . I valori possibili sono elencati di seguito. L'implementazione di questa funzione deve essere in grado di elaborare CRYPT_OBJECT_LOCATOR_SPN_NAME_TYPE, che viene passata da 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

Puntatore a una struttura CRYPTOAPI_BLOB contenente il nome che l'applicazione chiamante usa per identificare in modo univoco l'oggetto. Il provider usa questo nome per individuare l'oggetto richiesto. Schannel invia attualmente un nome host DNS (domain name system) codificato in UTF8 con nomi IDN convertiti da punycode.

[out] ppbContent

Puntatore a una matrice di byte che contiene l'oggetto da restituire.

[out] pcbContent

Dimensioni, in byte, dell'oggetto a cui punta il parametro ppbContent .

[out] ppwszPassword

Stringa Unicode con terminazione null contenente la password, se presente, usata per crittografare l'oggetto. Se l'oggetto è un file PFX (Personal Information Exchange), una password verrà in genere usata per eseguire la crittografia. Questo valore può essere NULL se non è necessaria alcuna password.

[out] ppIdentifier

Indirizzo che riceve un puntatore a un identificatore facoltativo che può essere usato durante le chiamate successive a questa funzione e per le notifiche di modifica. Per altre informazioni, vedere la sezione Osservazioni. Se il provider imposta questo valore su NULL, Schannel usa internamente il valore del parametro pNameBlob .

Valore restituito

Se la funzione ha esito positivo, restituisce non zero (TRUE).

Se la funzione ha esito negativo, restituire zero (FALSE) e specificare un errore appropriato nella funzione SetLastError . La maggior parte degli errori viene passata tramite Schannel non modificata, ma questo comportamento non è garantito. Alcuni errori possono essere mappati ad altri errori.

Se non è possibile restituire un oggetto per un determinato nome DNS (pNameBlob) o un identificatore (pIdentifier), restituire FALSE e specificare CRYPT_E_OBJECT_LOCATOR_OBJECT_NOT_FOUND nella funzione SetLastError .

Commenti

La funzione di callback PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET è attualmente chiamata solo dal pacchetto di sicurezza Secure Channel (Schannel). È possibile restituire un oggetto che incapsula uno dei seguenti elementi:

Matrice di byte pfX (Personal Information Exchange)
Archivio certificati.
BLOB generico. Attualmente non è supportato da Schannel.

Quando questa funzione viene chiamata per la prima volta, Schannel invia un nome host DNS nell'argomento pNameBlob per specificare l'host per cui è previsto l'oggetto. Il provider deve elaborare il nome (corrisponde a schede jolly, compilare un percorso file e così via) per determinare l'oggetto da trovare.

Poiché molti nomi host possono essere mappati a un oggetto, il provider può usare il parametro ppIdentifier per restituire un identificatore definito internamente che può essere usato nelle chiamate successive dalle funzioni DELL'API di crittografia (CAPI) al provider. Il provider può quindi usare l'identificatore per facilitare la ricerca dell'oggetto appropriato.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8 [solo app desktop]
Server minimo supportato	Windows Server 2012 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	wincrypt.h

Vedi anche

CRYPT_OBJECT_LOCATOR_PROVIDER_TABLE

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_RELEASE

Condividi tramite