funzione Msv1_0SubAuthenticationFilter (subauth.h)

Articolo
03/02/2024

La funzione Msv1_0SubAuthenticationFilter esegue l'autenticazione di accesso utente specifica per i controller di dominio.

La funzione riceve i dati di accesso dell'utente e tutte le informazioni trovate per l'utente nel database Sam ( Security Accounts Manager ) del controller di dominio.

Questa funzione viene implementata dalle DLL del pacchetto di sottoutenticazione personalizzate da usare con i pacchetti di autenticazione Kerberos e MSV1_0.

Sintassi

NTSTATUS Msv1_0SubAuthenticationFilter(
  [in]  NETLOGON_LOGON_INFO_CLASS LogonLevel,
  [in]  PVOID                     LogonInformation,
  [in]  ULONG                     Flags,
  [in]  PUSER_ALL_INFORMATION     UserAll,
  [out] PULONG                    WhichFields,
  [out] PULONG                    UserFlags,
  [out] PBOOLEAN                  Authoritative,
  [out] PLARGE_INTEGER            LogoffTime,
  [out] PLARGE_INTEGER            KickoffTime
);

Parametri

[in] LogonLevel

Specifica il livello di informazioni specificate in LogonInformation. Questo parametro è in genere impostato su NetlogonInteractiveInformation.

[in] LogonInformation

Puntatore a una struttura NETLOGON_LOGON_IDENTITY_INFO . I membri di questa struttura contengono informazioni sull'utente che esegue l'accesso. Il membro LogonDomainName viene ignorato.

[in] Flags

facoltativo. Contiene flag che descrivono le circostanze dell'accesso. Questo parametro può avere uno dei valori seguenti.

Valore	Significato
MSV1_0_PASSTHRU	Autenticazione pass-through. L'utente non si connette a questo computer.
MSV1_0_GUEST_LOGON	Si tratta di un nuovo tentativo dell'accesso usando l'account Guest.

[in] UserAll

Puntatore a una struttura USER_ALL_INFORMATION che contiene la descrizione dell'utente come restituito dal database SAM.

[out] WhichFields

Restituisce i membri della struttura USER_ALL_INFORMATION che devono essere scritti nel database SAM. Questi membri verranno scritti solo se Msv1_0SubAuthenticationFilter restituisce esito positivo. Solo il valore seguente è valido.

Valore	Significato
USER_ALL_PARAMETERS	Scrivere i dati contenuti nel membro Parametri della struttura UserAll nel database SAM. Se le dimensioni del buffer UNICODE_STRING del membro Parametri vengono modificate, Msv1_0SubAuthenticationFilter deve eliminare il buffer usando la funzione MIDL_user_free e riallocarla usando la funzione MIDL_user_allocate.

[out] UserFlags

Valori da restituire dalla funzione LsaLogonUser nel parametro ProfileBuffer della funzione. Questo parametro può avere uno dei valori seguenti.

Valore	Significato
LOGON_GUEST	Questo è stato un accesso guest.
LOGON_NOENCRYPTION	Il chiamante non ha specificato le credenziali crittografate.

Nota Per convenzione, i pacchetti di sottoutenticazione restituiscono bit solo nell'ordine elevato del parametro UserFlags .

[out] Authoritative

Puntatore a un valore booleano che indica se lo stato restituito è uno stato autorevole che deve essere restituito al chiamante originale. Se il valore restituito è FALSE, la richiesta di accesso può essere riprovata su un altro controller di dominio. Questo parametro deve restituire informazioni valide indipendentemente dal valore restituito della chiamata alla funzione. Questo parametro non viene usato con il pacchetto di autenticazione Kerberos.

[out] LogoffTime

Puntatore a un valore che riceve il momento in cui l'utente deve disconnettersi dal sistema. Questa volta viene usata per controllare la durata dell'accesso e viene specificata come ora di sistema DI Windows relativa a GMT.

[out] KickoffTime

Puntatore a un valore che riceve il momento in cui l'utente deve essere disconnesso dal sistema. Questa volta viene usata per controllare la durata dell'accesso e viene specificata come ora di sistema gmt-relativa. Se l'utente non deve essere disconnesso automaticamente, specificare un valore positivo di grandi dimensioni, come indicato di seguito:

KickoffTime->HighPart = 0x7FFFFFFF;
KickoffTime->LowPart = 0xFFFFFFFF;

Valore restituito

Questa funzione deve restituire uno dei valori seguenti.

Codice restituito	Descrizione
STATUS_SUCCESS	Non è stato visualizzato alcun errore.
STATUS_ACCOUNT_DISABLED	L'account è disabilitato.
STATUS_ACCOUNT_EXPIRED	L'account è scaduto.
STATUS_ACCOUNT_LOCKED_OUT	L'account è bloccato.
STATUS_INVALID_INFO_CLASS	LogonLevel non è valido.
STATUS_INVALID_LOGON_HOURS	L'utente non è autorizzato ad accedere in questo momento.
STATUS_INVALID_WORKSTATION	L'utente non è autorizzato ad accedere alla workstation specificata.
STATUS_NO_SUCH_USER	L'utente specificato non ha alcun account.
STATUS_PASSWORD_EXPIRED	La password è scaduta.
STATUS_PASSWORD_MUST_CHANGE	La password deve cambiare nell'accesso successivo.
STATUS_WRONG_PASSWORD	La password non è valida.

Quando la funzione Msv1_0SubAuthenticationFilter viene usata con il pacchetto di autenticazione Kerberos, se la chiamata alla funzione restituisce STATUS_SUCCESS e uno dei due parametri LogoffTime o KickoffTime ha un valore diverso da zero, questo valore viene usato come durata del ticket. Se, d'altra parte, i valori di entrambi i parametri non sono zero, viene usato il valore inferiore di questi due valori.

Se il valore utilizzato per la durata del ticket (il prima di LogoffTime e KickoffTime) è maggiore della durata predefinita del ticket, tale valore verrà usato come tempo di rinnovo massimo per il ticket. Al contrario, se il valore più grande dei due valori (più avanti di LogoffTime e KickoffTime) è minore della durata predefinita del ticket, questo valore verrà usato come durata del ticket. Per altre informazioni, vedere Microsoft Kerberos.

Quando viene usato con il pacchetto di autenticazione Kerberos, se questa funzione restituisce un errore, il Centro distribuzione chiavi restituirà l'errore Kerberos KDC_ERR_POLICY, con il valore di stato come codice di errore esteso.

Commenti

Le implementazioni di questa funzione non devono eseguire operazioni che causano il traffico LDAP ( Lightweight Directory Access Protocol ). Ad esempio, non connettersi e eseguire query sul database di Active Directory .

Dopo aver convalidato il pacchetto di autenticazione MSV1_0 o Kerberos, la funzione Msv1_0SubAuthenticationFilter può eseguire una convalida aggiuntiva per determinare se un utente può accedere a un account di rete. Questa funzione viene chiamata se la DLL del pacchetto di sottoutenticazione viene registrata correttamente come 'Auth0' nel Registro di sistema del controller di dominio. Il percorso del Registro di sistema è diverso a seconda che la funzione si trova in una DLL del pacchetto di MSV1_0 o della sottoutenticazione Kerberos.

Questa routine di filtro può restituire STATUS_SUCCESS, che indica che l'accesso deve procedere o un codice di errore, che indica che la convalida aggiuntiva non è riuscita.

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	subauth.h