Función NetValidatePasswordPolicy (lmaccess.h)

Artículo
03/09/2023

La función NetValidatePasswordPolicy permite a una aplicación comprobar el cumplimiento de contraseñas en una base de datos de cuenta proporcionada por la aplicación y comprobar que las contraseñas cumplen los requisitos de complejidad, antigüedad, longitud mínima y reutilización del historial de una directiva de contraseñas.

Sintaxis

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
);

Parámetros

[in] ServerName

Puntero a una cadena Unicode constante que especifica el nombre del servidor remoto en el que se va a ejecutar la función. Esta cadena debe comenzar por \ seguido del nombre del servidor remoto. Si este parámetro es NULL, se usa el equipo local.

[in] Qualifier

Reservado para uso futuro. Este parámetro debe ser NULL.

[in] ValidationType

Tipo de validación de contraseña que se va a realizar. Este parámetro debe ser uno de los siguientes valores constantes enumerados.

typedef enum _NET_VALIDATE_PASSWORD_TYPE {

    NetValidateAuthentication = 1,
    NetValidatePasswordChange,
    NetValidatePasswordReset,

} NET_VALIDATE_PASSWORD_TYPE, *PNET_VALIDATE_PASSWORD_TYPE;

Estos valores tienen los significados siguientes.

Valor	Significado
NetValidateAuthentication	La aplicación solicita la validación de contraseñas durante la autenticación. El parámetro InputArg apunta a una estructura de NET_VALIDATE_AUTHENTICATION_INPUT_ARG . Este tipo de validación aplica la expiración de contraseñas y la directiva de bloqueo de cuenta.
NetValidatePasswordChange	La aplicación solicita la validación de contraseñas durante una operación de cambio de contraseña. El parámetro InputArg apunta a una estructura NET_VALIDATE_PASSWORD_CHANGE_INPUT_ARG .
NetValidatePasswordReset	La aplicación solicita la validación de contraseñas durante una operación de restablecimiento de contraseña. El parámetro InputArg apunta a una estructura de NET_VALIDATE_PASSWORD_RESET_INPUT_ARG . También puede restablecer el "estado de bloqueo" de una cuenta de usuario especificando esta estructura.

[in] InputArg

Puntero a una estructura que depende del tipo de validación de contraseña que se va a realizar. El tipo de estructura depende del valor del parámetro ValidationType . Para obtener más información, vea la descripción del parámetro ValidationType .

[out] OutputArg

Si la función NetValidatePasswordPolicy se realiza correctamente (el valor devuelto es Nerr_Success), la función asigna un búfer que contiene los resultados de la operación. El parámetro OutputArg contiene un puntero a una estructura NET_VALIDATE_OUTPUT_ARG . La aplicación debe examinar el miembro ValidationStatus en la estructura de NET_VALIDATE_OUTPUT_ARG a la que apunta el parámetro OutputArg para determinar los resultados de la comprobación de validación de directivas de contraseñas. La estructura NET_VALIDATE_OUTPUT_ARG contiene una estructura de NET_VALIDATE_PERSISTED_FIELDS con cambios en la información relacionada con contraseña persistente y los resultados de la validación de contraseñas. La aplicación debe planear conservar todos los campos guardados en la estructura NET_VALIDATE_PERSISTED_FIELDS aparte del miembro ValidationStatus como información junto con la información del objeto de usuario y proporcionar los campos obligatorios de la información persistente al llamar a esta función en el futuro en el mismo objeto de usuario.

Si se produce un error en la función NetValidatePasswordPolicy (el valor devuelto es distinto de cero), el parámetro OutputArg se establece en un puntero NULL y no se pudo examinar la directiva de contraseña.

Para obtener más información, vea las secciones Valores devueltos y comentarios.

Valor devuelto

Si la función se realiza correctamente y la contraseña se autentica, cambia o restablece, el valor devuelto se NERR_Success y la función asigna un parámetro OutputArg .

Si se produce un error en la función, el parámetro OutputArg es NULL y el valor devuelto es un código de error del sistema que puede ser uno de los siguientes códigos de error. Para obtener una lista de todos los códigos de error posibles, consulte Códigos de error del sistema.

Código devuelto	Descripción
ERROR_INVALID_PARAMETER	Un parámetro es incorrecto. Este error se devuelve si los parámetros InputArg o OutputArg son NULL. Este error también se devuelve si el parámetro Qualifier no es NULL o si el parámetro ValidationType no es uno de los valores permitidos.
ERROR_NOT_ENOUGH_MEMORY	Memoria insuficiente para completar la operación.

Comentarios

La función NetValidatePasswordPolicy está diseñada para permitir que las aplicaciones validen contraseñas para los usuarios que se encuentran en una base de datos de cuentas proporcionada por la aplicación. Esta función también se puede usar para comprobar que las contraseñas cumplen los requisitos de complejidad, antigüedad, longitud mínima y reutilización del historial de una directiva de contraseñas. Esta función también proporciona los medios para que una aplicación implemente un mecanismo de bloqueo de cuenta.

La función NetValidatePasswordPolicy no valida contraseñas en cuentas de Active Directory y no se puede usar para este fin. La única directiva en la que esta función comprueba una contraseña en las cuentas de Active Directory es la complejidad de la contraseña (la seguridad de la contraseña).

Un escenario típico para el uso de la función NetValidatePasswordPolicy sería aplicar la elección de contraseñas seguras por parte de los usuarios para aplicaciones web y aplicaciones que permiten documentos protegidos con contraseña. Otro uso de esta función podría estar comprobando la complejidad de la contraseña en una situación en la que una contraseña está asociada a una operación funcional en lugar de a una cuenta de usuario; por ejemplo, las contraseñas que se usan con claves públicas basadas en certificados Secure Multipurpose Internet Mail Extensions (S/MIME).

Si se llama a la función NetValidatePasswordPolicy en un controlador de dominio que ejecuta Active Directory, se permite o se deniega el acceso basado en la ACL para el objeto protegible. La ACL predeterminada permite que todos los usuarios y miembros autenticados del grupo "Acceso compatible con Pre-Windows 2000" vean la información. Si llama a esta función en un servidor miembro o estación de trabajo, todos los usuarios autenticados pueden ver la información. Para obtener información sobre el acceso anónimo y restringir el acceso anónimo en estas plataformas, consulte Requisitos de seguridad para las funciones de administración de red. Para obtener más información sobre las ACL, los ACL y los tokens de acceso, consulte Access Control Model.

El descriptor de seguridad del objeto Domain se usa para realizar la comprobación de acceso de la función NetValidatePasswordPolicy .

Para llamar a NetValidatePasswordPolicy en un contexto de seguridad que no es el valor predeterminado, primero llame a la función LogonUser , especificando LOGON32_LOGON_NEW_CREDENTIALS en el parámetro dwLogonType y, a continuación, llame a NetValidatePasswordPolicy en suplantación. Para obtener más información sobre la suplantación, consulte Suplantación de cliente.

Si el código devuelto de la función NetValidatePasswordPolicy es Nerr_Success , la función asigna un búfer al que apunta el parámetro OutputArg que contiene una estructura de NET_VALIDATE_OUTPUT_ARG con los resultados de la operación. La aplicación debe examinar el miembro ValidationStatus en la estructura NET_VALIDATE_OUTPUT_ARG para determinar los resultados de la comprobación de validación de la directiva de contraseñas. Para obtener más información, consulte NET_VALIDATE_OUTPUT_ARG.

Tenga en cuenta que es responsabilidad de la aplicación guardar todos los datos en el miembro ChangedPersistedFields de la estructura NET_VALIDATE_OUTPUT_ARG , así como cualquier información del objeto User. La próxima vez que la aplicación llame a NetValidatePasswordPolicy en la misma instancia del objeto User, la aplicación debe proporcionar los campos necesarios de la información persistente.

Al llamar a NetValidatePasswordPolicy y especificar NET_VALIDATE_PASSWORD_CHANGE_INPUT_ARG o NET_VALIDATE_PASSWORD_RESET_INPUT_ARG en el parámetro InputArg , la llamada también valida la contraseña pasandola a través del archivo DLL de filtro de contraseña que el equipo está configurado para usar. Para obtener más información sobre los filtros de contraseña, consulte Uso de filtros de contraseña.

Si el valor devuelto de la función NetValidatePasswordPolicy es distinto de cero, el parámetro OutputArg se establece en NULL y no se pudo examinar la directiva de contraseña.

Se debe llamar a la función NetValidatePasswordPolicyFree después de llamar a NetValidatePasswordPolicy para liberar la memoria asignada para el parámetro OutputArg devuelto por la llamada a la función NetValidatePasswordPolicy .

Requisitos

Requisito	Value
Cliente mínimo compatible	No se admite ninguno
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	lmaccess.h (include Lm.h)
Library	Netapi32.lib
Archivo DLL	Netapi32.dll