NetValidatePasswordPolicy 函式 (lmaccess.h)

發行項
03/05/2024

NetValidatePasswordPolicy 函式可讓應用程式針對應用程式提供的帳戶資料庫檢查密碼合規性，並確認密碼符合密碼原則的複雜度、過時、最小長度和歷程記錄重複使用需求。

語法

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

參數

[in] ServerName

常數 Unicode 字串的指標，指定要執行函式之遠端伺服器的名稱。此字串開頭必須是 \ ，後面接著遠端伺服器名稱。如果此參數為 NULL，則會使用本機電腦。

[in] Qualifier

保留供未來使用。此參數必須是 NULL。

[in] ValidationType

要執行的密碼驗證類型。此參數必須是下列其中一個列舉常數值。

typedef enum _NET_VALIDATE_PASSWORD_TYPE {

    NetValidateAuthentication = 1,
    NetValidatePasswordChange,
    NetValidatePasswordReset,

} NET_VALIDATE_PASSWORD_TYPE, *PNET_VALIDATE_PASSWORD_TYPE;

這些值具有下列意義。

值	意義
NetValidateAuthentication	應用程式正在驗證期間要求密碼驗證。 InputArg 參數指向NET_VALIDATE_AUTHENTICATION_INPUT_ARG結構。這種類型的驗證會強制執行密碼到期和帳戶鎖定原則。
NetValidatePasswordChange	應用程式在密碼變更作業期間要求密碼驗證。 InputArg 參數指向NET_VALIDATE_PASSWORD_CHANGE_INPUT_ARG結構。
NetValidatePasswordReset	應用程式在密碼重設作業期間要求密碼驗證。 InputArg 參數指向NET_VALIDATE_PASSWORD_RESET_INPUT_ARG結構。您也可以藉由指定這個結構來重設使用者帳戶的「鎖定狀態」。

[in] InputArg

結構的指標，取決於要執行的密碼驗證類型。結構的型別取決於 ValidationType 參數的值。如需詳細資訊，請參閱 ValidationType 參數的描述。

[out] OutputArg

如果 NetValidatePasswordPolicy 函式成功 (傳回值 Nerr_Success) ，則函式會配置包含作業結果的緩衝區。 OutputArg 參數包含NET_VALIDATE_OUTPUT_ARG結構的指標。應用程式必須檢查 OutputArg 參數所指向之NET_VALIDATE_OUTPUT_ARG結構中的 ValidationStatus 成員，以判斷密碼原則驗證檢查的結果。 NET_VALIDATE_OUTPUT_ARG 結構包含NET_VALIDATE_PERSISTED_FIELDS結構，其中包含持續密碼相關信息的變更，以及密碼驗證的結果。應用程式必須計劃保存 NET_VALIDATE_PERSISTED_FIELDS結構中的所有 持續性欄位，除了 ValidationStatus 成員做為資訊，以及使用者物件資訊，並在未來在同一個使用者物件上呼叫此函式時，提供保存資訊所需的字段。

如果 NetValidatePasswordPolicy 函式失敗 (傳回值為非零) ，則 OutputArg 參數會設定為 NULL 指標，而且無法檢查密碼原則。

如需詳細資訊，請參閱傳回值和備註小節。

傳回值

如果函式成功，且密碼已驗證、變更或重設，則傳回值會NERR_Success，且函式會配置 OutputArg 參數。

如果函式失敗， OutputArg 參數為 NULL ，而傳回值為系統錯誤碼，可以是下列其中一個錯誤碼。如需所有可能錯誤碼的清單，請參閱系統錯誤碼。

傳回碼	Description
ERROR_INVALID_PARAMETER	參數不正確。如果 InputArg 或 OutputArg 參數為 NULL，就會傳回此錯誤。如果限定符參數不是 NULL ，或者 ValidationType 參數不是其中一個允許的值，也會傳回此錯誤。
ERROR_NOT_ENOUGH_MEMORY	可用的記憶體不足，無法完成作業。

備註

NetValidatePasswordPolicy 函式的設計目的是允許應用程式驗證應用程式所提供帳戶資料庫中用戶的密碼。此函式也可以用來確認密碼符合密碼原則的複雜度、過時、最小長度和歷程記錄重複使用需求。此函式也提供應用程式實作帳戶鎖定機制的方法。

NetValidatePasswordPolicy 函式不會驗證 Active Directory 帳戶中的密碼，而且無法用於此用途。此函式在 Active Directory 帳戶中檢查密碼的唯一原則是密碼複雜度 (密碼強度) 。

使用 NetValidatePasswordPolicy 函式的典型案例是針對允許受密碼保護之檔的 Web 應用程式和應用程式，強制使用者選擇強密碼。此函式的另一個用法可能是在密碼附加至功能作業而非使用者帳戶的情況下檢查密碼複雜度;例如，與安全多用途因特網郵件延伸模組搭配使用的密碼， (S/MIME) 憑證式公鑰。

如果在執行 Active Directory 的域控制器上呼叫 NetValidatePasswordPolicy 函式，則會根據安全性實體物件的 ACL 來允許或拒絕存取。默認 ACL 允許所有已驗證的使用者和「Windows 2000 相容存取」群組的成員檢視資訊。如果您在成員伺服器或工作站上呼叫此函式，所有已驗證的使用者都可以檢視資訊。如需有關匿名存取和限制這些平臺上匿名存取的資訊，請參閱網路管理功能的安全性需求。如需 ACL、ACE 和存取令牌的詳細資訊，請參閱存取控制模型。

Domain 對象的安全性描述元是用來執行 NetValidatePasswordPolicy 函式的存取檢查。

若要在非預設值的安全性內容中呼叫 NetValidatePasswordPolicy ，請先呼叫 LogonUser 函式，並在 dwLogonType 參數中指定LOGON32_LOGON_NEW_CREDENTIALS，然後在模擬下呼叫 NetValidatePasswordPolicy 。如需仿真的詳細資訊，請參閱用戶端模擬。

如果 NetValidatePasswordPolicy 函式的傳回碼 是Nerr_Success ，則函式會配置 OutputArg 參數所指向的緩衝區，其中包含具有作業結果的NET_VALIDATE_OUTPUT_ARG 結構。應用程式必須檢查 NET_VALIDATE_OUTPUT_ARG 結構中的 ValidationStatus 成員，以判斷密碼原則驗證檢查的結果。如需詳細資訊，請參閱 NET_VALIDATE_OUTPUT_ARG。

請注意，應用程式必須負責儲存NET_VALIDATE_OUTPUT_ARG結構之 ChangedPersistedFields 成員中的所有數據，以及任何 User 對象資訊。下次應用程式在相同 User 對象的實例上呼叫 NetValidatePasswordPolicy 時，應用程式必須從持續性資訊提供所需的欄位。

當您呼叫 NetValidatePasswordPolicy並在InputArg 參數中指定NET_VALIDATE_PASSWORD_CHANGE_INPUT_ARG或NET_VALIDATE_PASSWORD_RESET_INPUT_ARG時，呼叫也會透過電腦設定使用的密碼篩選 DLL 傳遞它來驗證密碼。如需密碼篩選的詳細資訊，請參閱使用密碼篩選。

如果 NetValidatePasswordPolicy 函式的傳回值不是零值， 則 OutputArg 參數會設定為 NULL ，而且無法檢查密碼原則。

呼叫 NetValidatePasswordPolicyFree 函式之後，應該呼叫 NetValidatePasswordPolicy，以釋放由呼叫 NetValidatePasswordPolicy 函式所傳回的 OutputArg 參數所配置的記憶體。

規格需求

需求	值
最低支援的用戶端	都不支援
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平台	Windows
標頭	lmaccess.h (包括 Lm.h)
程式庫	Netapi32.lib
Dll	Netapi32.dll