Funzione CredUnPackAuthenticationBufferA (wincred.h)

Articolo
08/27/2023

La funzione CredUnPackAuthenticationBuffer converte un buffer di autenticazione restituito da una chiamata alla funzione CredUIPromptForWindowsCredentials in un nome utente e una password stringa.

Sintassi

CREDUIAPI BOOL CredUnPackAuthenticationBufferA(
  [in]      DWORD dwFlags,
  [in]      PVOID pAuthBuffer,
  [in]      DWORD cbAuthBuffer,
  [out]     LPSTR pszUserName,
  [in, out] DWORD *pcchlMaxUserName,
  [out]     LPSTR pszDomainName,
  [in, out] DWORD *pcchMaxDomainName,
  [out]     LPSTR pszPassword,
  [in, out] DWORD *pcchMaxPassword
);

Parametri

[in] dwFlags

L'impostazione del valore di questo parametro su CRED_PACK_PROTECTED_CREDENTIALS specifica che la funzione tenta di decrittografare le credenziali nel buffer di autenticazione. Se non è possibile decrittografare le credenziali, la funzione restituisce FALSE e una chiamata alla funzione GetLastError restituirà il valore ERROR_NOT_CAPABLE.

La modalità di decrittografia dipende dal formato del buffer di autenticazione.

Se il buffer di autenticazione è una struttura SEC_WINNT_AUTH_IDENTITY_EX2 , la funzione può decrittografare il buffer se è crittografato usando SspiEncryptAuthIdentityEx con l'opzione SEC_WINNT_AUTH_IDENTITY_ENCRYPT_SAME_LOGON.

Se il buffer di autenticazione è una delle strutture di KERB_*_LOGON di marshalling, la funzione decrittografa la password prima di restituirla nel buffer pszPassword .

[in] pAuthBuffer

Puntatore al buffer di autenticazione da convertire.

Questo buffer è in genere l'output della funzione CredUIPromptForWindowsCredentials o CredPackAuthenticationBuffer . Deve essere uno dei tipi seguenti:

Struttura SEC_WINNT_AUTH_IDENTITY_EX2 per le credenziali di identità. La funzione non accetta altre strutture SEC_WINNT_AUTH_IDENTITY .
Struttura di KERB_INTERACTIVE_LOGON o di KERB_INTERACTIVE_UNLOCK_LOGON per le credenziali della password.
Struttura di KERB_CERTIFICATE_LOGON o di KERB_CERTIFICATE_UNLOCK_LOGON per le credenziali del certificato della smart card.
GENERIC_CRED per le credenziali generice.

[in] cbAuthBuffer

Dimensioni, in byte, del buffer pAuthBuffer .

[out] pszUserName

Puntatore a una stringa con terminazione Null che riceve il nome utente.

Questa stringa può essere una credenziale di marshalling. Vedere la sezione Osservazioni.

[in, out] pcchlMaxUserName

Puntatore a un valore DWORD che specifica le dimensioni, in caratteri, del buffer pszUserName . Nell'output, se il buffer non è di dimensioni sufficienti, specifica le dimensioni richieste, in caratteri, del buffer pszUserName . La dimensione include il carattere null di terminazione.

[out] pszDomainName

Puntatore a una stringa con terminazione Null che riceve il nome del dominio dell'utente.

[in, out] pcchMaxDomainName

Puntatore a un valore DWORD che specifica le dimensioni, in caratteri, del buffer pszDomainName . Nell'output, se il buffer non è di dimensioni sufficienti, specifica le dimensioni richieste, in caratteri, del buffer pszDomainName . La dimensione include il carattere Null di terminazione. Le dimensioni necessarie possono essere pari a zero se non è presente alcun nome di dominio.

[out] pszPassword

Puntatore a una stringa con terminazione Null che riceve la password.

[in, out] pcchMaxPassword

Puntatore a un valore DWORD che specifica le dimensioni, in caratteri, del buffer pszPassword . Nell'output, se il buffer non è di dimensioni sufficienti, specifica le dimensioni richieste, in caratteri, del buffer pszPassword . La dimensione include il carattere Null di terminazione.

Questa stringa può essere una credenziale di marshalling. Vedere la sezione Osservazioni.

Valore restituito

TRUE se la funzione ha esito positivo; in caso contrario, FALSE.

Per informazioni sugli errori estesi, chiamare la funzione GetLastError . La tabella seguente mostra i valori comuni per la funzione GetLastError .

Codice/valore restituito	Descrizione
ERROR_NOT_CAPABLE	CRED_PACK_PROTECTED_CREDENTIALS è stato passato come valore del parametro dwFlags , ma questa funzione non può decrittografare le credenziali perché il contesto di sicurezza usato per proteggere la password è diverso dal contesto di sicurezza del chiamante.
ERROR_INSUFFICIENT_BUFFER	Uno dei buffer di output, pszUserName, pszDomainName o pszPassword, era di dimensioni insufficienti.
ERROR_NOT_SUPPORTED	Il buffer di autenticazione non è di un tipo supportato.

Commenti

A partire da Windows 8 e Windows Server 2012, il buffer di autenticazione può essere una struttura di SEC_WINNT_AUTH_IDENTITY_EX2, che può essere crittografata facoltativamente usando la funzione SspiEncryptAuthIdentityEx con l'opzione SEC_WINNT_AUTH_IDENTITY_ENCRYPT_SAME_LOGON. Questo formato di credenziali viene restituito da un provider di credenziali di un provider di identità usando la funzione CredUIPromptForWindowsCredentials o SspiPromptForCredentials . Questa struttura può essere costruita anche usando la funzione CredPackAuthenticationBuffer . Se il buffer di autenticazione pAuthBuffer rappresenta una credenziale non password, ad esempio KERB_CERTIFICATE_LOGON o SEC_WINNT_AUTH_IDENTITY_EX2, la funzione deve effettuare il marshalling delle credenziali come stringhe di caratteri, restituite come nome utente, nome di dominio e stringhe password. Il marshalling viene eseguito usando una procedura specifica. Quando dwFlags contiene il flag CRED_PACK_PROTECTED_CREDENTIALS, il chiamante deve essere eseguito nella stessa sessione di accesso in cui è stata crittografata la credenziale.

Nota

L'intestazione wincred.h definisce CredUnPackAuthenticationBuffer come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	wincred.h
Libreria	Credui.lib
DLL	Credui.dll

Condividi tramite