Fungsi NetValidatePasswordPolicy (lmaccess.h)

Artikel
03/09/2023

Fungsi NetValidatePasswordPolicy memungkinkan aplikasi memeriksa kepatuhan kata sandi terhadap database akun yang disediakan aplikasi dan memverifikasi bahwa kata sandi memenuhi persyaratan kompleksitas, penuaan, panjang minimum, dan riwayat penggunaan kembali kebijakan kata sandi.

Sintaks

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

Parameter

[in] ServerName

Penunjuk ke string Unicode konstanta yang menentukan nama server jarak jauh tempat fungsi dijalankan. String ini harus dimulai dengan \ diikuti dengan nama server jarak jauh. Jika parameter ini NULL, komputer lokal akan digunakan.

[in] Qualifier

Disiapkan untuk penggunaan masa mendatang. Parameter ini harus NULL.

[in] ValidationType

Jenis validasi kata sandi yang akan dilakukan. Parameter ini harus menjadi salah satu nilai konstanta enumerasi berikut.

typedef enum _NET_VALIDATE_PASSWORD_TYPE {

    NetValidateAuthentication = 1,
    NetValidatePasswordChange,
    NetValidatePasswordReset,

} NET_VALIDATE_PASSWORD_TYPE, *PNET_VALIDATE_PASSWORD_TYPE;

Nilai-nilai ini memiliki arti berikut.

Nilai	Makna
NetValidateAuthentication	Aplikasi meminta validasi kata sandi selama autentikasi. Parameter InputArg menunjuk ke struktur NET_VALIDATE_AUTHENTICATION_INPUT_ARG . Jenis validasi ini memberlakukan kebijakan kedaluwarsa kata sandi dan penguncian akun.
NetValidatePasswordChange	Aplikasi meminta validasi kata sandi selama operasi perubahan kata sandi. Parameter InputArg menunjuk ke struktur NET_VALIDATE_PASSWORD_CHANGE_INPUT_ARG .
NetValidatePasswordReset	Aplikasi meminta validasi kata sandi selama operasi reset kata sandi. Parameter InputArg menunjuk ke struktur NET_VALIDATE_PASSWORD_RESET_INPUT_ARG . Anda juga dapat mengatur ulang "status penguncian" akun pengguna dengan menentukan struktur ini.

[in] InputArg

Penunjuk ke struktur yang bergantung pada jenis validasi kata sandi yang akan dilakukan. Jenis struktur tergantung pada nilai parameter ValidationType . Untuk informasi selengkapnya, lihat deskripsi parameter ValidationType .

[out] OutputArg

Jika fungsi NetValidatePasswordPolicy berhasil (nilai yang dikembalikan Nerr_Success), maka fungsi mengalokasikan buffer yang berisi hasil operasi. Parameter OutputArg berisi penunjuk ke struktur NET_VALIDATE_OUTPUT_ARG . Aplikasi harus memeriksa anggota ValidationStatus dalam struktur NET_VALIDATE_OUTPUT_ARG yang diarahkan oleh parameter OutputArg untuk menentukan hasil pemeriksaan validasi kebijakan kata sandi. Struktur NET_VALIDATE_OUTPUT_ARG berisi struktur NET_VALIDATE_PERSISTED_FIELDS dengan perubahan pada informasi terkait kata sandi yang persisten, dan hasil validasi kata sandi. Aplikasi harus berencana untuk mempertahankan semua bidang yang dipertahankan dalam struktur NET_VALIDATE_PERSISTED_FIELDS selain anggota ValidationStatus sebagai informasi bersama dengan informasi objek pengguna dan memberikan bidang yang diperlukan dari informasi yang dipertahankan saat memanggil fungsi ini di masa mendatang pada objek pengguna yang sama.

Jika fungsi NetValidatePasswordPolicy gagal (nilai yang dikembalikan bukan nol), parameter OutputArg diatur ke penunjuk NULL dan kebijakan kata sandi tidak dapat diperiksa.

Untuk informasi selengkapnya, lihat bagian Mengembalikan Nilai dan Keterangan.

Mengembalikan nilai

Jika fungsi berhasil, dan kata sandi diautentikasi, diubah, atau direset, nilai yang dikembalikan NERR_Success dan fungsi mengalokasikan parameter OutputArg .

Jika fungsi gagal, parameter OutputArg adalah NULL dan nilai yang dikembalikan adalah kode kesalahan sistem yang dapat menjadi salah satu kode kesalahan berikut. Untuk daftar semua kemungkinan kode kesalahan, lihat Kode Kesalahan Sistem.

Menampilkan kode	Deskripsi
ERROR_INVALID_PARAMETER	Parameter salah. Kesalahan ini dikembalikan jika parameter InputArg atau OutputArgADALAH NULL. Kesalahan ini juga dikembalikan jika parameter Kualifikasi bukan NULL atau jika parameter ValidationType bukan salah satu nilai yang diizinkan.
ERROR_NOT_ENOUGH_MEMORY	Tidak cukup memori yang tersedia untuk menyelesaikan operasi.

Keterangan

Fungsi NetValidatePasswordPolicy dirancang untuk memungkinkan aplikasi memvalidasi kata sandi untuk pengguna yang berada dalam database akun yang disediakan oleh aplikasi. Fungsi ini juga dapat digunakan untuk memverifikasi bahwa kata sandi memenuhi persyaratan kompleksitas, penuaan, panjang minimum, dan riwayat penggunaan kembali kebijakan kata sandi. Fungsi ini juga menyediakan sarana bagi aplikasi untuk menerapkan mekanisme penguncian akun.

Fungsi NetValidatePasswordPolicy tidak memvalidasi kata sandi di akun Direktori Aktif dan tidak dapat digunakan untuk tujuan ini. Satu-satunya kebijakan yang digunakan fungsi ini untuk memeriksa kata sandi di akun Direktori Aktif adalah kompleksitas kata sandi (kekuatan kata sandi).

Skenario umum untuk penggunaan fungsi NetValidatePasswordPolicy akan memberlakukan pilihan kata sandi yang kuat oleh pengguna untuk aplikasi web dan aplikasi yang memungkinkan dokumen yang dilindungi kata sandi. Penggunaan lain dari fungsi ini dapat memeriksa kompleksitas kata sandi dalam situasi di mana kata sandi dilampirkan ke operasi fungsi, bukan ke akun pengguna; misalnya, kata sandi yang digunakan dengan kunci publik berbasis sertifikat Secure Multipurpose Internet Mail Extensions (S/MIME).

Jika fungsi NetValidatePasswordPolicy dipanggil pada pengendali domain yang menjalankan Direktori Aktif, akses diizinkan atau ditolak berdasarkan ACL untuk objek yang dapat diamankan. ACL default mengizinkan semua pengguna terautentikasi dan anggota grup "Akses pra-windows 2000 kompatibel" untuk melihat informasi. Jika Anda memanggil fungsi ini di server anggota atau stasiun kerja, semua pengguna yang diautentikasi dapat melihat informasi. Untuk informasi tentang akses anonim dan membatasi akses anonim pada platform ini, lihat Persyaratan Keamanan untuk Fungsi Manajemen Jaringan. Untuk informasi selengkapnya tentang ACL, ACL, dan token akses, lihat Model Access Control.

Deskriptor keamanan objek Domain digunakan untuk melakukan pemeriksaan akses untuk fungsi NetValidatePasswordPolicy .

Untuk memanggil NetValidatePasswordPolicy dalam konteks keamanan yang bukan default, pertama-tama panggil fungsi LogonUser , tentukan LOGON32_LOGON_NEW_CREDENTIALS dalam parameter dwLogonType , lalu panggil NetValidatePasswordPolicy di bawah peniruan. Untuk informasi selengkapnya tentang peniruan, lihat Peniruan Klien.

Jika kode pengembalian fungsi NetValidatePasswordPolicyNerr_Success maka fungsi mengalokasikan buffer yang diarahkan oleh parameter OutputArg yang berisi struktur NET_VALIDATE_OUTPUT_ARG dengan hasil operasi. Aplikasi harus memeriksa anggota ValidationStatus dalam struktur NET_VALIDATE_OUTPUT_ARG untuk menentukan hasil pemeriksaan validasi kebijakan kata sandi. Untuk informasi selengkapnya, lihat NET_VALIDATE_OUTPUT_ARG.

Perhatikan bahwa aplikasi bertanggung jawab untuk menyimpan semua data di anggota ChangedPersistedFields dari struktur NET_VALIDATE_OUTPUT_ARG serta informasi objek Pengguna apa pun. Saat aplikasi memanggil NetValidatePasswordPolicy pada instans objek Pengguna yang sama, aplikasi harus menyediakan bidang yang diperlukan dari informasi persisten.

Saat Anda memanggil NetValidatePasswordPolicy dan menentukan NET_VALIDATE_PASSWORD_CHANGE_INPUT_ARG atau NET_VALIDATE_PASSWORD_RESET_INPUT_ARG dalam parameter InputArg , panggilan juga memvalidasi kata sandi dengan meneruskannya melalui DLL filter kata sandi yang dikonfigurasi komputer untuk digunakan. Untuk informasi selengkapnya tentang filter kata sandi, lihat Menggunakan Filter Kata Sandi.

Jika nilai yang dikembalikan dari fungsi NetValidatePasswordPolicy bukan nol, parameter OutputArg diatur ke NULL dan kebijakan kata sandi tidak dapat diperiksa.

Fungsi NetValidatePasswordPolicyFree harus dipanggil setelah memanggil NetValidatePasswordPolicy untuk membebaskan memori yang dialokasikan untuk parameter OutputArg yang dikembalikan oleh panggilan ke fungsi NetValidatePasswordPolicy .

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tidak ada yang didukung
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	lmaccess.h (termasuk Lm.h)
Pustaka	Netapi32.lib
DLL	Netapi32.dll