Função NetValidatePasswordPolicy (lmaccess.h)

Artigo
08/24/2023

A função NetValidatePasswordPolicy permite que um aplicativo marcar a conformidade de senha em um banco de dados de conta fornecido pelo aplicativo e verifique se as senhas atendem aos requisitos de complexidade, envelhecimento, comprimento mínimo e reutilização de histórico de uma política de senha.

Sintaxe

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

Um ponteiro para uma cadeia de caracteres Unicode constante especificando o nome do servidor remoto no qual a função deve ser executada. Essa cadeia de caracteres deve começar com \ seguida pelo nome do servidor remoto. Se esse parâmetro for NULL, o computador local será usado.

[in] Qualifier

Reservado para uso futuro. Esse parâmetro deve ser NULL.

[in] ValidationType

O tipo de validação de senha a ser executada. Esse parâmetro deve ser um dos seguintes valores constantes enumerados.

typedef enum _NET_VALIDATE_PASSWORD_TYPE {

    NetValidateAuthentication = 1,
    NetValidatePasswordChange,
    NetValidatePasswordReset,

} NET_VALIDATE_PASSWORD_TYPE, *PNET_VALIDATE_PASSWORD_TYPE;

Esses valores têm os seguintes significados.

Valor	Significado
NetValidateAuthentication	O aplicativo está solicitando validação de senha durante a autenticação. O parâmetro InputArg aponta para uma estrutura de NET_VALIDATE_AUTHENTICATION_INPUT_ARG . Esse tipo de validação impõe a expiração de senha e a política de bloqueio de conta.
NetValidatePasswordChange	O aplicativo está solicitando validação de senha durante uma operação de alteração de senha. O parâmetro InputArg aponta para uma estrutura de NET_VALIDATE_PASSWORD_CHANGE_INPUT_ARG .
NetValidatePasswordReset	O aplicativo está solicitando validação de senha durante uma operação de redefinição de senha. O parâmetro InputArg aponta para uma estrutura de NET_VALIDATE_PASSWORD_RESET_INPUT_ARG . Você também pode redefinir o "estado de bloqueio" de uma conta de usuário especificando essa estrutura.

[in] InputArg

Um ponteiro para uma estrutura que depende do tipo de validação de senha a ser executada. O tipo de estrutura depende do valor do parâmetro ValidationType . Para obter mais informações, consulte a descrição do parâmetro ValidationType .

[out] OutputArg

Se a função NetValidatePasswordPolicy for bem-sucedida (o valor retornado é Nerr_Success), a função alocará um buffer que contém os resultados da operação. O parâmetro OutputArg contém um ponteiro para uma estrutura NET_VALIDATE_OUTPUT_ARG . O aplicativo deve examinar o membro ValidationStatus na estrutura NET_VALIDATE_OUTPUT_ARG apontada pelo parâmetro OutputArg para determinar os resultados do marcar de validação da política de senha. A estrutura NET_VALIDATE_OUTPUT_ARG contém uma estrutura NET_VALIDATE_PERSISTED_FIELDS com alterações nas informações persistentes relacionadas à senha e os resultados da validação de senha. O aplicativo deve planejar manter todos os campos persistidos na estrutura NET_VALIDATE_PERSISTED_FIELDS além do membro ValidationStatus como informações junto com as informações do objeto do usuário e fornecer os campos necessários das informações persistentes ao chamar essa função no futuro no mesmo objeto de usuário.

Se a função NetValidatePasswordPolicy falhar (o valor retornado não é zero), o parâmetro OutputArg será definido como um ponteiro NULL e a política de senha não poderá ser examinada.

Para obter mais informações, consulte as seções Valores retornados e Comentários.

Retornar valor

Se a função for bem-sucedida e a senha for autenticada, alterada ou redefinida, o valor retornado será NERR_Success e a função alocará um parâmetro OutputArg .

Se a função falhar, o parâmetro OutputArg será NULL e o valor retornado será um código de erro do sistema que pode ser um dos seguintes códigos de erro. Para obter uma lista de todos os códigos de erro possíveis, consulte Códigos de erro do sistema.

Código de retorno	Descrição
ERROR_INVALID_PARAMETER	Um parâmetro está incorreto. Esse erro será retornado se os parâmetros InputArg ou OutputArg forem NULL. Esse erro também será retornado se o parâmetro Qualifier não for NULL ou se o parâmetro ValidationType não for um dos valores permitidos.
ERROR_NOT_ENOUGH_MEMORY	Não há memória disponível suficiente para concluir a operação.

Comentários

A função NetValidatePasswordPolicy foi projetada para permitir que os aplicativos validem senhas para usuários que estão em um banco de dados de conta fornecido pelo aplicativo. Essa função também pode ser usada para verificar se as senhas atendem aos requisitos de complexidade, envelhecimento, comprimento mínimo e reutilização de histórico de uma política de senha. Essa função também fornece os meios para um aplicativo implementar um mecanismo de bloqueio de conta.

A função NetValidatePasswordPolicy não valida senhas em contas do Active Directory e não pode ser usada para essa finalidade. A única política em que essa função verifica uma senha em contas do Active Directory é a complexidade da senha (a força da senha).

Um cenário típico para o uso da função NetValidatePasswordPolicy seria impor a escolha de senhas fortes por usuários para aplicativos Web e aplicativos que permitem documentos protegidos por senha. Outro uso dessa função pode ser verificar a complexidade da senha em uma situação em que uma senha é anexada a uma operação funcional em vez de a uma conta de usuário; por exemplo, senhas usadas com chaves públicas baseadas em certificado S/MIME (Secure Multipurpose Internet Mail Extensions).

Se a função NetValidatePasswordPolicy for chamada em um controlador de domínio que esteja executando o Active Directory, o acesso será permitido ou negado com base na ACL do objeto protegível. A ACL padrão permite que todos os usuários autenticados e membros do grupo "Acesso compatível com o Pré-Windows 2000" exibam as informações. Se você chamar essa função em um servidor membro ou estação de trabalho, todos os usuários autenticados poderão exibir as informações. Para obter informações sobre acesso anônimo e restrição de acesso anônimo nessas plataformas, consulte Requisitos de segurança para as funções de gerenciamento de rede. Para obter mais informações sobre ACLs, ACEs e tokens de acesso, consulte Controle de Acesso Model.

O descritor de segurança do objeto Domain é usado para executar o marcar de acesso para a função NetValidatePasswordPolicy.

Para chamar NetValidatePasswordPolicy em um contexto de segurança que não é o padrão, primeiro chame a função LogonUser , especificando LOGON32_LOGON_NEW_CREDENTIALS no parâmetro dwLogonType e, em seguida, chame NetValidatePasswordPolicy em representação. Para obter mais informações sobre representação, consulte Representação de cliente.

Se o código de retorno da função NetValidatePasswordPolicy for Nerr_Success , a função alocará um buffer apontado pelo parâmetro OutputArg que contém uma estrutura NET_VALIDATE_OUTPUT_ARG com os resultados da operação. O aplicativo deve examinar o membro ValidationStatus na estrutura NET_VALIDATE_OUTPUT_ARG para determinar os resultados do marcar de validação da política de senha. Para obter mais informações, consulte NET_VALIDATE_OUTPUT_ARG.

Observe que é responsabilidade do aplicativo salvar todos os dados no membro ChangedPersistedFields da estrutura NET_VALIDATE_OUTPUT_ARG , bem como qualquer informação de objeto user. Na próxima vez que o aplicativo chamar NetValidatePasswordPolicy na mesma instância do objeto User, o aplicativo deverá fornecer os campos necessários das informações persistentes.

Quando você chama NetValidatePasswordPolicy e especifica NET_VALIDATE_PASSWORD_CHANGE_INPUT_ARG ou NET_VALIDATE_PASSWORD_RESET_INPUT_ARG no parâmetro InputArg , a chamada também valida a senha passando-a pela DLL de filtro de senha que o computador está configurado para usar. Para obter mais informações sobre filtros de senha, consulte Usando filtros de senha.

Se o valor retornado da função NetValidatePasswordPolicy não for zero, o parâmetro OutputArg será definido como NULL e a política de senha não poderá ser examinada.

A função NetValidatePasswordPolicyFree deve ser chamada depois de chamar NetValidatePasswordPolicy para liberar a memória alocada para o parâmetro OutputArg retornado pela chamada para a função NetValidatePasswordPolicy .

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Nenhum compatível
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	lmaccess.h (inclua Lm.h)
Biblioteca	Netapi32.lib
DLL	Netapi32.dll