Fungsi NetUserChangePassword (lmaccess.h)

Artikel
03/09/2023

Fungsi NetUserChangePassword mengubah kata sandi pengguna untuk server jaringan atau domain tertentu.

Sintaks

NET_API_STATUS NET_API_FUNCTION NetUserChangePassword(
  [in] LPCWSTR domainname,
  [in] LPCWSTR username,
  [in] LPCWSTR oldpassword,
  [in] LPCWSTR newpassword
);

Parameter

[in] domainname

Penunjuk ke string konstanta yang menentukan nama DNS atau NetBIOS dari server atau domain jarak jauh tempat fungsi dijalankan. Jika parameter ini ADALAH NULL, domain masuk pemanggil akan digunakan.

[in] username

Penunjuk ke string konstanta yang menentukan nama pengguna. Fungsi NetUserChangePassword mengubah kata sandi untuk pengguna yang ditentukan.

Jika parameter ini NULL, nama masuk pemanggil akan digunakan. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

[in] oldpassword

Penunjuk ke string konstanta yang menentukan kata sandi lama pengguna.

[in] newpassword

Penunjuk ke string konstanta yang menentukan kata sandi baru pengguna.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah NERR_Success.

Jika fungsi gagal, nilai yang dikembalikan dapat menjadi salah satu kode kesalahan berikut.

Menampilkan kode	Deskripsi
ERROR_ACCESS_DENIED	Pengguna tidak memiliki akses ke informasi yang diminta.
ERROR_INVALID_PASSWORD	Pengguna telah memasukkan kata sandi yang tidak valid.
NERR_InvalidComputer	Nama komputer tidak valid.
NERR_NotPrimary	Operasi ini hanya diperbolehkan pada pengendali domain utama domain.
NERR_UserNotFound	Nama pengguna tidak dapat ditemukan.
NERR_PasswordTooShort	Kata sandi lebih pendek dari yang diperlukan. (Kata sandi juga bisa terlalu panjang, terlalu baru dalam riwayat perubahannya, tidak memiliki karakter unik yang cukup, atau tidak memenuhi persyaratan kebijakan kata sandi lain.)

Keterangan

Jika Anda memprogram Direktori Aktif, Anda mungkin dapat memanggil metode Antarmuka Layanan Direktori Aktif (ADSI) tertentu untuk mencapai hasil yang sama yang dapat Anda capai dengan memanggil fungsi pengguna manajemen jaringan. Untuk informasi selengkapnya, lihat IADsUser dan IADsComputer.

Jika aplikasi memanggil fungsi NetUserChangePassword pada pengendali domain yang menjalankan Direktori Aktif, akses diizinkan atau ditolak berdasarkan daftar kontrol akses (ACL) untuk objek yang dapat diamankan. ACL default hanya mengizinkan Admin Domain dan Operator Akun untuk memanggil fungsi ini. Di server anggota atau stasiun kerja, hanya Administrator dan Pengguna Daya yang dapat memanggil fungsi ini. Pengguna dapat mengubah kata sandinya sendiri. Untuk informasi selengkapnya, lihat Persyaratan Keamanan untuk Fungsi Manajemen Jaringan. Untuk informasi selengkapnya tentang ACL, ACE, dan token akses, lihat Model Access Control.

Pendeskripsi keamanan objek Pengguna digunakan untuk melakukan pemeriksaan akses untuk fungsi ini. Selain itu, pemanggil harus memiliki akses kontrol "Ubah kata sandi" tepat pada objek Pengguna. Hak ini diberikan kepada Masuk Anonim dan Semua Orang secara default.

Perhatikan bahwa agar fungsi berhasil, parameter oldpassword harus cocok dengan kata sandi seperti yang ada saat ini.

Dalam beberapa kasus, proses yang memanggil fungsi NetUserChangePassword juga harus mengaktifkan hak istimewa SE_CHANGE_NOTIFY_NAME; jika tidak, NetUserChangePassword gagal dan GetLastError mengembalikan ERROR_ACCESS_DENIED. Hak istimewa ini tidak diperlukan untuk akun LocalSystem atau untuk akun yang merupakan anggota grup administrator. Secara default, SE_CHANGE_NOTIFY_NAME diaktifkan untuk semua pengguna, tetapi beberapa administrator dapat menonaktifkan hak istimewa untuk semua orang. Untuk informasi selengkapnya tentang hak istimewa akun, lihat Hak Istimewa dan Konstanta Otorisasi.

Lihat Memaksa Pengguna untuk Mengubah Kata Sandi Masuk untuk sampel kode yang menunjukkan cara memaksa pengguna mengubah kata sandi masuk pada masuk berikutnya menggunakan fungsi NetUserGetInfo dan NetUserSetInfo .

Nama akun pengguna dibatasi hingga 20 karakter dan nama grup dibatasi hingga 256 karakter. Selain itu, nama akun tidak dapat dihentikan dengan titik dan tidak dapat menyertakan koma atau salah satu karakter yang dapat dicetak berikut: ", /, , [, ], :, |, <, >, +, =, ;, ?, *. Nama juga tidak dapat menyertakan karakter dalam rentang 1-31, yang tidak dapat dicetak.

Fungsi NetUserChangePassword tidak mengontrol bagaimana parameter oldpassword dan newpassword diamankan saat dikirim melalui jaringan ke server jarak jauh. Enkripsi apa pun dari parameter ini ditangani oleh mekanisme Panggilan Prosedur Jarak Jauh (RPC) yang didukung oleh pengalih jaringan yang menyediakan transportasi jaringan. Enkripsi juga dikendalikan oleh mekanisme keamanan yang didukung oleh komputer lokal dan mekanisme keamanan yang didukung oleh server jaringan jarak jauh atau domain yang ditentukan dalam parameter nama domain . Untuk detail selengkapnya tentang keamanan ketika pengalih jaringan Microsoft digunakan dan server jaringan jarak jauh menjalankan Microsoft Windows, lihat dokumentasi protokol untuk MS-RPCE, MS-SAMR, MS-SPNG, dan MS-NLMP.

Contoh

Sampel kode berikut menunjukkan cara mengubah kata sandi pengguna dengan panggilan ke fungsi NetUserChangePassword . Semua parameter ke fungsi diperlukan.

#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")

#include <stdio.h>
#include <windows.h> 
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   DWORD dwError = 0;
   NET_API_STATUS nStatus;
   //
   // All parameters are required.
   //
   if (argc != 5)
   {
      fwprintf(stderr, L"Usage: %s \\\\ServerName UserName OldPassword NewPassword\n", argv[0]);
      exit(1);
   }
   //
   // Call the NetUserChangePassword function.
   //
   nStatus = NetUserChangePassword(argv[1], argv[2], argv[3], argv[4]);
   //
   // If the call succeeds, inform the user.
   //
   if (nStatus == NERR_Success)
      fwprintf(stderr, L"User password has been changed successfully\n");
   //
   // Otherwise, print the system error.
   //
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   return 0;
}

Persyaratan

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