LSA_AP_LOGON_USER_EX funzione di callback (ntsecpkg.h)

Articolo
03/13/2024

Autentica le credenziali di accesso di un utente.

Questa funzione viene chiamata dall'Autorità di sicurezza locale (LSA) solo per l'accesso iniziale di un utente. Le richieste di autenticazione successive devono usare LsaCallAuthenticationPackage. Se LsaApLogonUserEx ha esito positivo, crea una sessione di accesso e restituisce informazioni usate per compilare il token che rappresenta l'utente appena connesso.

Questa funzione differisce da LsaApLogonUser in quanto il nome del computer viene aggiunto al record di controllo per il tentativo di accesso.

Sintassi

LSA_AP_LOGON_USER_EX LsaApLogonUserEx;

NTSTATUS LsaApLogonUserEx(
  [in]  PLSA_CLIENT_REQUEST ClientRequest,
  [in]  SECURITY_LOGON_TYPE LogonType,
  [in]  PVOID AuthenticationInformation,
  [in]  PVOID ClientAuthenticationBase,
  [in]  ULONG AuthenticationInformationLength,
  [out] PVOID *ProfileBuffer,
  [out] PULONG ProfileBufferLength,
  [out] PLUID LogonId,
  [out] PNTSTATUS SubStatus,
  [out] PLSA_TOKEN_INFORMATION_TYPE TokenInformationType,
  [out] PVOID *TokenInformation,
  [out] PUNICODE_STRING *AccountName,
  [out] PUNICODE_STRING *AuthenticatingAuthority,
  [out] PUNICODE_STRING *MachineName
)
{...}

Parametri

[in] ClientRequest

Puntatore a un tipo di dati LSA_CLIENT_REQUEST opaco che rappresenta la richiesta del client LSA.

[in] LogonType

Struttura SECURITY_LOGON_TYPE che identifica il tipo di tentativo di accesso.

[in] AuthenticationInformation

Fornisce le informazioni di autenticazione specifiche per il pacchetto di autenticazione. L'LSA libera questo buffer.

[in] ClientAuthenticationBase

Fornisce l'indirizzo delle informazioni di autenticazione all'interno del processo client. Potrebbe essere necessario eseguire il mapping di tutti i puntatori all'interno del buffer AuthenticationInformation .

[in] AuthenticationInformationLength

Indica la lunghezza del buffer AuthenticationInformation .

[out] ProfileBuffer

Puntatore che riceve l'indirizzo del buffer del profilo nel processo client. Il pacchetto di autenticazione è responsabile dell'allocazione del buffer ProfileBuffer all'interno del processo client chiamando la funzione AllocateClientBuffer . Tuttavia, se l'LSA rileva successivamente un errore che impedisce un accesso corretto, l'LSA si occupa di liberare questo buffer.

Il contenuto di questo buffer è determinato dal pacchetto di autenticazione. L'LSA non modifica questo buffer; restituisce semplicemente il valore alla funzione LsaLogonUser .

[out] ProfileBufferLength

Puntatore a un ULONG che riceve la lunghezza del buffer ProfileBuffer , in byte.

[out] LogonId

Puntatore a una variabile LUID che riceve il nuovo ID di accesso che identifica in modo univoco questa sessione di accesso. Il pacchetto di autenticazione è responsabile dell'allocazione di questo LUID e della creazione della sessione di accesso LSA per questo accesso.

[out] SubStatus

Puntatore a un NTSTATUS che riceve il motivo degli errori dovuti alle restrizioni dell'account. I valori restituiti in SubStatus sono determinati dal pacchetto di autenticazione.

Di seguito sono riportati i valori SubStatus per i pacchetti di autenticazione MSV1_0 e Kerberos.

Valore	Significato
STATUS_INVALID_LOGON_HOURS	L'account utente ha restrizioni di tempo e non può essere usato per accedere in questo momento.
STATUS_INVALID_WORKSTATION	L'account utente ha restrizioni sulla workstation e non può essere usato per accedere dalla workstation corrente.
STATUS_PASSWORD_EXPIRED	La password dell'account utente è scaduta.
STATUS_ACCOUNT_DISABLED	L'account utente è attualmente disabilitato e non può essere usato per accedere.

Altre informazioni sui codici NTSTATUS sono disponibili nel file di intestazione Subauth.h fornito con Platform SDK.

[out] TokenInformationType

Puntatore che riceve l'indirizzo di un valore di LSA_TOKEN_INFORMATION_TYPE che indica il tipo di informazioni restituite per l'inclusione nel token da creare. Le informazioni vengono restituite tramite il parametro TokenInformation .

[out] TokenInformation

Puntatore che riceve l'indirizzo delle informazioni da includere nel token. Il formato e il contenuto di TokenInformation sono indicati dal parametro TokenInformationType . Il pacchetto di autenticazione è responsabile dell'allocazione della memoria usata da TokenInformation; tuttavia, questa memoria verrà liberata dall'LSA.

[out] AccountName

Puntatore a una struttura LSA_UNICODE_STRING che riceve il nome dell'account utente. AccountName deve sempre essere restituito indipendentemente dall'esito positivo o negativo della chiamata; la stringa è inclusa nel record di controllo per un tentativo di autenticazione. Il pacchetto di autenticazione è responsabile dell'allocazione della memoria usata da AccountName Verrà liberato dall'LSA.

[out] AuthenticatingAuthority

facoltativo. Puntatore a una struttura LSA_UNICODE_STRING che riceve la descrizione dell'autorità di autenticazione per l'accesso. Questo parametro può essere NULL. Questa stringa è inclusa nel record di controllo per un tentativo di autenticazione. Il pacchetto di autenticazione è responsabile dell'allocazione della memoria usata da AuthenticatingAuthority; tuttavia, questa memoria verrà liberata dall'LSA.

Il pacchetto di autenticazione MSV1_0 restituisce il nome di dominio del dominio convalidando l'account. Il pacchetto di autenticazione Kerberos restituisce il nome di dominio NetBIOS.

[out] MachineName

facoltativo. Puntatore che riceve l'indirizzo di una struttura di LSA_UNICODE_STRING contenente il nome della workstation del client. Queste informazioni sono incluse nel record di controllo per un tentativo di autenticazione. Il pacchetto di autenticazione è responsabile dell'allocazione della memoria usata da MachineName; tuttavia, questa memoria verrà liberata dall'LSA.

Il pacchetto di autenticazione MSV1_0 restituisce il nome NetBIOS della workstation del client.

Valore restituito

Se la funzione ha esito positivo, deve restituire STATUS_SUCCESS.

In caso contrario, deve restituire un codice di errore NTSTATUS, che può essere uno dei valori seguenti o uno dei valori restituiti della funzione criteri LSA.

Codice restituito	Descrizione
STATUS_NO_MEMORY	Impossibile completare l'accesso perché la quota di memoria del client non è sufficiente per allocare il buffer restituito.
STATUS_NO_LOGON_SERVERS	Nessun controller di dominio è disponibile per il servizio della richiesta di autenticazione.
STATUS_LOGON_FAILURE	Il tentativo di accesso ha avuto esito negativo. Il motivo dell'errore non è specificato; i motivi tipici includono nomi utente e password sbagliati.
STATUS_ACCOUNT_RESTRICTION	L'account utente e la password sono legittimi, ma le restrizioni dell'account utente impediscono l'accesso riuscito in questo momento.
STATUS_BAD_VALIDATION_CLASS	Le informazioni di autenticazione fornite vengono riconosciute dal pacchetto di autenticazione.

Le applicazioni chiamanti possono usare la funzione LsaNtStatusToWinError per convertire il codice NTSTATUS in un codice di errore di Windows.

Commenti

I pacchetti di autenticazione devono implementare una delle funzioni seguenti: LsaApLogonUser, LsaApLogonUserEx o LsaApLogonUserEx2.

LsaApLogonUserEx è stato aggiunto per la certificazione C2. C2 è una classificazione di sicurezza definita dal governo Stati Uniti.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	ntsecpkg.h