WSASetSocketSecurity 函式 (ws2tcpip.h)

發行項
08/28/2023

WSASetSocketSecurity函式會啟用並套用通訊端的安全性。

語法

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

參數

[in] Socket

描述項，識別套用安全性設定的通訊端。

[in, optional] SecuritySettings

SOCKET_SECURITY_SETTINGS結構的指標，指定要套用至通訊端流量的安全性設定。如果此參數為 Null，預設設定將會套用至通訊端。

[in] SecuritySettingsLen

SecuritySettings參數的大小，以位元組為單位。

[in, optional] Overlapped

WSAOVERLAPPED結構的指標。非重迭通訊端會忽略此參數。

[in, optional] CompletionRoutine

作業完成時呼叫之完成常式的指標。非重迭通訊端會忽略此參數。

傳回值

如果此函式成功，則傳回值為零。否則，會傳回 SOCKET_ERROR 的值，並呼叫 WSAGetLastError來擷取特定的錯誤碼。

以下列出一些可能的錯誤碼。

錯誤碼	意義
WSAEAFNOSUPPORT	不支援指定的位址系列。
WSAEINVAL	傳遞了一個無效的參數。如果未使用AF_INET或AF_INET6的位址系列建立通訊端，且通訊端類型為SOCK_DGRAM或SOCK_STREAM，則會傳回此錯誤。如果SecuritySettings參數指向的SOCKET_SECURITY_SETTINGS結構有不正確的值，也會傳回此錯誤。
WSAEISCONN	通訊端已連接。不論通訊端是面向連線還是無連線，都不允許此函式與連接通訊端搭配使用。
WSAEMSGSIZE	傳遞的緩衝區太小。
WSAENOTSOCK	在 Socket參數中傳遞的描述項不是有效的通訊端。

備註

WSASetSocketSecurity函式的主要目的是在系統管理原則尚未啟用通訊端時開啟通訊端的安全性。針對 IPsec，這表示會具現化適當的 IPsec 篩選和原則，以用來保護此通訊端。 WSASetSocketSecurity函式也可以用來設定通訊端的特定安全性需求。

此函式可簡化呼叫 WSAIoctl 函式， 並將 dwIoControlCode 參數設定為 SIO_SET_SECURITY。

WSASetSocketSecurity函式可以在使用位址系列AF_INET或AF_INET6所建立的Socket參數上呼叫。

對於使用連線導向通訊端的用戶端應用程式， (通訊協定IPPROTO_TCP) ，應該在呼叫 connect、ConnectEx或 WSAConnect 函式之前呼叫WSASetSocketSecurity函式。如果在connect、ConnectEx或WSAConnect函式之後呼叫WSASetSocketSecurity函式，WSASetSocketSecurity應該會失敗。

對於使用連接導向通訊端的伺服器應用程式 (通訊協定 IPPROTO_TCP) ， 應該先呼叫 WSASetSocketSecurity 函式，再呼叫系結函式。如果在系結函式之後呼叫WSASetSocketSecurity函式，WSASetSocketSecurity應該會失敗。

對於無連線通訊端 (通訊協定IPPROTO_UDP) ，應用程式應該在通訊端或WSASocket 呼叫傳回之後立即呼叫 WSASetSocketSecurity函式。

伺服器應用程式應該呼叫 setsockopt 函式，以取得通訊端所用埠的獨佔存取權。這可防止其他應用程式使用相同的埠。 會呼叫 setsockopt函式，並將level參數設定為 SOL_SOCKET、optname參數設定為SO_EXCLUSIVEADDRUSE，並將value參數設定為非零。 WSASetSocketSecurity函式會在內部呼叫具有 SO_EXCLUSIVEADDRUSE 的setsockopt，以取得埠的獨佔存取權。這是為了確保通訊端不會受到本機電腦上執行的其他應用程式攻擊。

未使用 WSASetSocketSecurity 設定 的安全性設定衍生自系統預設原則或系統管理設定的原則。建議大部分的應用程式在SecuritySettings參數所指向SOCKET_SECURITY_PROTOCOL的SecurityProtocol成員中，為SOCKET_SECURITY_PROTOCOL列舉指定SOCKET_SECURITY_PROTOCOL_DEFAULT值。這可讓應用程式與安全性通訊協定保持中性，並允許在不同系統之間進行更輕鬆的部署。

當 SecuritySettings 參數指向 SOCKET_SECURITY_SETTINGS_IPSEC 結構時，結構的 SecurityProtocol 成員必須設定為 SOCKET_SECURITY_PROTOCOL_IPSEC，而不是 SOCKET_SECURITY_PROTOCOL_DEFAULT。

如果不符合下列條件，將會傳回錯誤。

Socket參數的位址系列必須是 AF_INET 或 AF_INET6。
通訊端類型必須是 SOCK_STREAM 或 SOCK_DGRAM。
應用程式必須先設定其安全性設定，才能呼叫系結、 connect、 ConnectEx或 WSAConnect 函式。
WSASetSocketSecurity函式只能針對每個通訊端呼叫一次。

預設安全通訊端 IPsec 原則

如果 SecuritySettings 參數設定為 Null，且電腦上沒有其他系統管理指定的 IPsec 原則，則會使用以 IPsec 為基礎的預設安全性原則來保護應用程式的流量。某些類型的驗證認證 (使用者憑證或網域成員資格，例如) 必須存在，IPsec 才能使用預設原則成功。

預設的 IPsec 原則已設計，以便盡可能在多個案例中交涉 IPsec 安全性。

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
 } 
}

規格需求


最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平台	Windows
標頭	ws2tcpip.h
程式庫	Fwpuclnt.lib
Dll	Fwpuclnt.dll