Funzione NetValidatePasswordPolicy (lmaccess.h)

Articolo
08/24/2023

La funzione NetValidatePasswordPolicy consente a un'applicazione di controllare la conformità delle password rispetto a un database account fornito dall'applicazione e verificare che le password soddisfino la complessità, l'invecchiamento, la lunghezza minima e i requisiti di riutilizzo della cronologia di un criterio password.

Sintassi

NET_API_STATUS NET_API_FUNCTION NetValidatePasswordPolicy(
  [in]  LPCWSTR                    ServerName,
  [in]  LPVOID                     Qualifier,
  [in]  NET_VALIDATE_PASSWORD_TYPE ValidationType,
  [in]  LPVOID                     InputArg,
  [out] LPVOID                     *OutputArg
);

Parametri

[in] ServerName

Puntatore a una stringa Unicode costante che specifica il nome del server remoto in cui eseguire la funzione. Questa stringa deve iniziare con \ seguita dal nome del server remoto. Se questo parametro è NULL, viene usato il computer locale.

[in] Qualifier

Riservato per utilizzi futuri. Questo parametro deve essere NULL.

[in] ValidationType

Tipo di convalida della password da eseguire. Questo parametro deve essere uno dei valori costanti enumerati seguenti.

typedef enum _NET_VALIDATE_PASSWORD_TYPE {

    NetValidateAuthentication = 1,
    NetValidatePasswordChange,
    NetValidatePasswordReset,

} NET_VALIDATE_PASSWORD_TYPE, *PNET_VALIDATE_PASSWORD_TYPE;

Questi valori hanno i significati seguenti.

Valore	Significato
NetValidateAuthentication	L'applicazione richiede la convalida della password durante l'autenticazione. Il parametro InputArg punta a una struttura NET_VALIDATE_AUTHENTICATION_INPUT_ARG . Questo tipo di convalida impone la scadenza della password e i criteri di blocco dell'account.
NetValidatePasswordChange	L'applicazione richiede la convalida della password durante un'operazione di modifica della password. Il parametro InputArg punta a una struttura NET_VALIDATE_PASSWORD_CHANGE_INPUT_ARG .
NetValidatePasswordReset	L'applicazione richiede la convalida della password durante un'operazione di reimpostazione della password. Il parametro InputArg punta a una struttura NET_VALIDATE_PASSWORD_RESET_INPUT_ARG . È anche possibile reimpostare lo stato di blocco di un account utente specificando questa struttura.

[in] InputArg

Puntatore a una struttura che dipende dal tipo di convalida della password da eseguire. Il tipo di struttura dipende dal valore del parametro ValidationType . Per altre informazioni, vedere la descrizione del parametro ValidationType .

[out] OutputArg

Se la funzione NetValidatePasswordPolicy ha esito positivo (il valore restituito è Nerr_Success), la funzione alloca un buffer contenente i risultati dell'operazione. Il parametro OutputArg contiene un puntatore a una struttura NET_VALIDATE_OUTPUT_ARG . L'applicazione deve esaminare il membro ValidationStatus nella struttura NET_VALIDATE_OUTPUT_ARG a cui punta il parametro OutputArg per determinare i risultati del controllo di convalida dei criteri password. La struttura NET_VALIDATE_OUTPUT_ARG contiene una struttura NET_VALIDATE_PERSISTED_FIELDS con modifiche alle informazioni correlate alle password persistenti e i risultati della convalida della password. L'applicazione deve pianificare di rendere persistenti tutti i campi nella struttura NET_VALIDATE_PERSISTED_FIELDS , oltre al membro ValidationStatus come informazioni sull'oggetto utente e fornire i campi necessari dalle informazioni persistenti quando si chiama questa funzione nello stesso oggetto utente.

Se la funzione NetValidatePasswordPolicy ha esito negativo (il valore restituito è diverso da zero), il parametro OutputArg è impostato su un puntatore NULL e i criteri password non possono essere esaminati.

Per altre informazioni, vedere le sezioni Restituiti valori e osservazioni.

Valore restituito

Se la funzione ha esito positivo e la password viene autenticata, modificata o reimpostata, il valore restituito è NERR_Success e la funzione alloca un parametro OutputArg .

Se la funzione ha esito negativo, il parametro OutputArg è NULL e il valore restituito è un codice di errore di sistema che può essere uno dei codici di errore seguenti. Per un elenco di tutti i codici di errore possibili, vedere Codici di errore di sistema.

Codice restituito	Descrizione
ERROR_INVALID_PARAMETER	Un parametro non è corretto. Questo errore viene restituito se i parametri InputArg o OutputArg sono NULL. Questo errore viene restituito anche se il parametro Qualifier non è NULL o se il parametro ValidationType non è uno dei valori consentiti.
ERROR_NOT_ENOUGH_MEMORY	Memoria insufficiente per completare l’operazione.

Commenti

La funzione NetValidatePasswordPolicy è progettata per consentire alle applicazioni di convalidare le password per gli utenti che si trovano in un database account fornito dall'applicazione. Questa funzione può essere usata anche per verificare che le password soddisfino la complessità, l'invecchiamento, la lunghezza minima e i requisiti di riutilizzo della cronologia di un criterio password. Questa funzione fornisce anche i mezzi per un'applicazione per implementare un meccanismo di blocco dell'account.

La funzione NetValidatePasswordPolicy non convalida le password negli account Active Directory e non può essere usata per questo scopo. L'unico criterio che questa funzione controlla una password rispetto agli account Di Active Directory è la complessità della password (forza password).

Uno scenario tipico per l'uso della funzione NetValidatePasswordPolicy applica la scelta di password complesse da parte degli utenti per applicazioni Web e applicazioni che consentono documenti protetti da password. Un altro uso di questa funzione potrebbe controllare la complessità della password in una situazione in cui una password è associata a un'operazione funzionale anziché a un account utente; Ad esempio, le password usate con le chiavi pubbliche basate su certificati S/MIME (Secure Multipurpose Internet Mail Extensions).

Se la funzione NetValidatePasswordPolicy viene chiamata su un controller di dominio che esegue Active Directory, l'accesso è consentito o negato in base all'ACL per l'oggetto a protezione diretta. L'elenco di controllo di accesso predefinito consente a tutti gli utenti autenticati e ai membri del gruppo "Accesso compatibile con Windows 2000" di pre-Windows 2000 per visualizzare le informazioni. Se si chiama questa funzione in un server membro o in una workstation, tutti gli utenti autenticati possono visualizzare le informazioni. Per informazioni sull'accesso anonimo e sulla limitazione dell'accesso anonimo in queste piattaforme, vedere Requisiti di sicurezza per le funzioni di gestione della rete. Per altre informazioni sugli elenchi di controllo di accesso, sugli ACL e sui token di accesso, vedere Controllo di accesso Modello.

Il descrittore di sicurezza dell'oggetto Domain viene usato per eseguire il controllo di accesso per la funzione NetValidatePasswordPolicy .

Per chiamare NetValidatePasswordPolicy in un contesto di sicurezza non predefinito, chiamare prima la funzione LogonUser , specificando LOGON32_LOGON_NEW_CREDENTIALS nel parametro dwLogonType e quindi chiamare NetValidatePasswordPolicy in rappresentazione. Per altre informazioni sulla rappresentazione, vedere Rappresentazione client.

Se il codice restituito della funzione NetValidatePasswordPolicy è Nerr_Success la funzione alloca un buffer a cui punta il parametro OutputArg che contiene una struttura NET_VALIDATE_OUTPUT_ARG con i risultati dell'operazione. L'applicazione deve esaminare il membro ValidationStatus nella struttura NET_VALIDATE_OUTPUT_ARG per determinare i risultati del controllo di convalida dei criteri password. Per altre informazioni, vedere NET_VALIDATE_OUTPUT_ARG.

Si noti che è responsabilità dell'applicazione salvare tutti i dati nel membro ChangedPersistedFields della struttura NET_VALIDATE_OUTPUT_ARG e di qualsiasi informazione dell'oggetto User. La prossima volta che l'applicazione chiama NetValidatePasswordPolicy nella stessa istanza dell'oggetto User, l'applicazione deve fornire i campi obbligatori dalle informazioni persistenti.

Quando si chiama NetValidatePasswordPolicy e si specifica NET_VALIDATE_PASSWORD_CHANGE_INPUT_ARG o NET_VALIDATE_PASSWORD_RESET_INPUT_ARG nel parametro InputArg , la chiamata convalida anche la password passandola tramite la DLL del filtro password configurata dal computer. Per altre informazioni sui filtri password, vedere Uso di filtri password.

Se il valore restituito dalla funzione NetValidatePasswordPolicy è diverso da zero, il parametro OutputArg è impostato su NULL e i criteri password non possono essere esaminati.

La funzione NetValidatePasswordPolicyFree deve essere chiamata dopo aver chiamato NetValidatePasswordPolicy per liberare la memoria allocata per il parametro OutputArg restituito dalla chiamata alla funzione NetValidatePasswordPolicy .

Requisiti

Requisito	Valore
Client minimo supportato	Nessuno supportato
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	lmaccess.h (include Lm.h)
Libreria	Netapi32.lib
DLL	Netapi32.dll