Fungsi WSASetSocketSecurity (ws2tcpip.h)

Artikel
08/28/2023

Fungsi WSASetSocketSecurity memungkinkan dan menerapkan keamanan untuk soket.

Sintaks

INT WSAAPI WSASetSocketSecurity(
  [in]           SOCKET                             Socket,
  [in, optional] const SOCKET_SECURITY_SETTINGS     *SecuritySettings,
  [in]           ULONG                              SecuritySettingsLen,
  [in, optional] LPWSAOVERLAPPED                    Overlapped,
  [in, optional] LPWSAOVERLAPPED_COMPLETION_ROUTINE CompletionRoutine
);

Parameter

[in] Socket

Deskriptor yang mengidentifikasi soket tempat pengaturan keamanan diterapkan.

[in, optional] SecuritySettings

Penunjuk ke struktur SOCKET_SECURITY_SETTINGS yang menentukan pengaturan keamanan yang akan diterapkan ke lalu lintas soket. Jika parameter ini NULL, pengaturan default akan diterapkan ke soket.

[in] SecuritySettingsLen

Ukuran, dalam byte, dari parameter SecuritySettings .

[in, optional] Overlapped

Penunjuk ke struktur WSAOVERLAPPED . Parameter ini diabaikan untuk soket yang tidak tumpang tindih.

[in, optional] CompletionRoutine

Penunjuk ke rutinitas penyelesaian yang dipanggil ketika operasi telah selesai. Parameter ini diabaikan untuk soket yang tidak tumpang tindih.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah nol. Jika tidak, nilai SOCKET_ERROR dikembalikan, dan kode kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError.

Beberapa kemungkinan kode kesalahan tercantum di bawah ini.

Kode kesalahan	Makna
WSAEAFNOSUPPORT	Keluarga alamat yang ditentukan tidak didukung.
WSAEINVAL	Parameter yang tidak valid diteruskan. Kesalahan ini dikembalikan jika soket yang diteruskan dalam parameter Soket tidak dibuat dengan keluarga alamat AF_INET atau AF_INET6 dan jenis soket SOCK_DGRAM atau SOCK_STREAM. Kesalahan ini juga dikembalikan jika struktur SOCKET_SECURITY_SETTINGS yang diacu oleh parameter SecuritySettings memiliki nilai yang salah.
WSAEISCONN	Soket tersambung. Fungsi ini tidak diizinkan dengan soket yang terhubung, baik soket berorientasi pada koneksi atau tanpa koneksi.
WSAEMSGSIZE	Buffer yang dilewati terlalu kecil.
WSAENOTSOCK	Deskriptor yang diteruskan dalam parameter Soket bukan soket yang valid.

Keterangan

Tujuan utama fungsi WSASetSocketSecurity adalah untuk mengaktifkan keamanan untuk soket jika belum diaktifkan oleh kebijakan administratif. Untuk IPsec, ini berarti bahwa filter dan kebijakan IPsec yang sesuai akan dibuat yang akan digunakan untuk mengamankan soket ini. fungsi WSASetSocketSecurity juga dapat digunakan untuk mengatur persyaratan keamanan tertentu untuk soket.

Fungsi ini menyederhanakan harus memanggil fungsi WSAIoctl dengan parameter dwIoControlCode yang diatur ke SIO_SET_SECURITY.

Fungsi WSASetSocketSecurity dapat dipanggil pada parameter Soket yang dibuat dengan keluarga alamat AF_INET atau AF_INET6.

Untuk aplikasi klien yang menggunakan soket berorientasi koneksi (protokol IPPROTO_TCP), fungsi WSASetSocketSecurity harus dipanggil sebelum fungsi connect, ConnectEx, atau WSAConnect dipanggil. Jika fungsi WSASetSocketSecurity dipanggil setelah fungsi connect, ConnectEx, atau WSAConnect , WSASetSocketSecurity harus gagal.

Untuk aplikasi server yang menggunakan soket berorientasi koneksi (protokol IPPROTO_TCP), fungsi WSASetSocketSecurity harus dipanggil sebelum fungsi ikat dipanggil. Jika fungsi WSASetSocketSecurity dipanggil setelah fungsi ikat , WSASetSocketSecurity harus gagal.

Untuk soket tanpa koneksi (protokol IPPROTO_UDP), aplikasi harus memanggil fungsi WSASetSocketSecurity segera setelah soket atau panggilan WSASocket kembali.

Aplikasi server harus memanggil fungsi setsockopt untuk memperoleh akses eksklusif ke port yang digunakan oleh soket. Ini mencegah aplikasi lain menggunakan port yang sama. Fungsi setsockopt akan dipanggil dengan parameter tingkat yang diatur ke SOL_SOCKET, parameter optname diatur ke SO_EXCLUSIVEADDRUSE, dan parameter nilai diatur ke bukan nol. Fungsi WSASetSocketSecurity secara internal memanggil setsockopt dengan SO_EXCLUSIVEADDRUSE untuk mendapatkan akses eksklusif ke port. Hal ini untuk memastikan bahwa soket tidak rentan terhadap serangan oleh aplikasi lain yang berjalan di komputer lokal.

Pengaturan keamanan yang tidak diatur menggunakan WSASetSocketSecurity berasal dari kebijakan default sistem atau kebijakan yang dikonfigurasi secara administratif. Disarankan agar sebagian besar aplikasi menentukan nilai SOCKET_SECURITY_PROTOCOL_DEFAULT untuk enumerasi SOCKET_SECURITY_PROTOCOL di anggota SecurityProtocol dari SOCKET_SECURITY_PROTOCOL yang ditunjukkan oleh parameter SecuritySettings . Ini membuat aplikasi netral terhadap protokol keamanan dan memungkinkan penyebaran yang lebih mudah di antara sistem yang berbeda.

Saat parameter SecuritySettings menunjuk ke struktur SOCKET_SECURITY_SETTINGS_IPSEC , anggota SecurityProtocol struktur harus diatur ke SOCKET_SECURITY_PROTOCOL_IPSEC, bukan SOCKET_SECURITY_PROTOCOL_DEFAULT.

Kesalahan akan dikembalikan jika kondisi berikut tidak terpenuhi.

Keluarga alamat parameter Soket harus AF_INET atau AF_INET6.
Jenis soket harus SOCK_STREAM atau SOCK_DGRAM.
Aplikasi harus mengatur pengaturan keamanannya sebelum memanggil fungsi bind, connect, ConnectEx, atau WSAConnect .
Fungsi WSASetSocketSecurity hanya dapat dipanggil sekali per soket.

Kebijakan IPsec Soket Aman Default

Jika parameter SecuritySettings diatur ke NULL, dan tidak ada kebijakan IPsec lain yang ditentukan secara administratif di komputer, kebijakan keamanan default berdasarkan IPsec akan digunakan untuk mengamankan lalu lintas aplikasi. Beberapa jenis kredensial autentikasi (sertifikat pengguna atau keanggotaan domain, misalnya) harus ada agar IPsec berhasil dengan kebijakan default.

Kebijakan IPsec default telah dirancang sehingga keamanan IPsec dapat dinegosiasikan dalam skenario sebanyak mungkin.

Authip MM policy = 
{
 Auth methods = {IKE_ANONYMOUS}
 No impersonation
 Proposals = 
 {
   {
     Crypto algos = 
     IKE_CIPHER_AES_128,
     IKE_INTEGRITY_SHA1, 
     IKE_DH_ECP_256
     MM lifetime = 2 hrs
     QM = 0 (infinite)
   }
   {
     Crypto algos = 
     IKE_CIPHER_3DES, 
     IKE_INTEGRITY_SHA1, 
     IKE_DH_GROUP_2
     MM lifetime = 2 hrs
     QM = 0 (infinite)
   }
 }
}

Authip QM policy =
{
 QM proposals = 
 {
   QM lifetime = 1 hr, 55GB,
   Crypto algos = 
   IPSEC_TRANSFORM_ESP_AUTH, 
   IPSEC_AUTH_TRANSFORM_ID_HMAC_SHA_1_96
   No PFS
 }
 {
   QM lifetime = 1 hr, 55GB,
   Crypto algos = 
   IPSEC_TRANSFORM_ESP_AUTH_AND_CIPHER,
   IPSEC_AUTH_TRANSFORM_ID_HMAC_SHA_1_96,
   IPSEC_CIPHER_TRANSFORM_ID_AES_128
   No PFS
 }
 {
   QM lifetime = 1 hr, 55GB,
   Crypto algos = 
   IPSEC_TRANSFORM_ESP_AUTH_AND_CIPHER,
   IPSEC_AUTH_TRANSFORM_ID_HMAC_SHA_1_96,
   IPSEC_CIPHER_TRANSFORM_ID_CBC_3DES
   No PFS
 }
 {
   QM lifetime = 1 hr, 55GB,
   Crypto algos = 
   IPSEC_TRANSFORM_AH,
   IPSEC_AUTH_TRANSFORM_ID_HMAC_SHA_1_96
   No PFS
 }
 IPSEC_POLICY_FLAG_ND_BOUNDARY
 ndAllowClearTimeoutSeconds = 10
 saIdleTimeout = {5mins, 1min}
 UM policy = 
 {
   {IKE_SSL, Null-Root-Config}
   {IKE_KERBEROS}
   {IKE_SSL, Null-Root-Config}
   No impersonation
 } 
}

Persyaratan


Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	ws2tcpip.h
Pustaka	Fwpuclnt.lib
DLL	Fwpuclnt.dll