WSASetSocketSecurity-Funktion (ws2tcpip.h)

Artikel
08/28/2023

Die WSASetSocketSecurity-Funktion aktiviert und wendet Die Sicherheit für einen Socket an.

Syntax

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

Ein Deskriptor, der einen Socket identifiziert, auf den Sicherheitseinstellungen angewendet werden.

[in, optional] SecuritySettings

Ein Zeiger auf eine SOCKET_SECURITY_SETTINGS-Struktur , die die Sicherheitseinstellungen angibt, die auf den Datenverkehr des Sockets angewendet werden sollen. Wenn dieser Parameter NULL ist, werden die Standardeinstellungen auf den Socket angewendet.

[in] SecuritySettingsLen

Die Größe des SecuritySettings-Parameters in Bytes.

[in, optional] Overlapped

Ein Zeiger auf eine WSAOVERLAPPED-Struktur . Dieser Parameter wird für nicht überlappende Sockets ignoriert.

[in, optional] CompletionRoutine

Ein Zeiger auf die Vervollständigungsroutine, die aufgerufen wird, wenn der Vorgang abgeschlossen wurde. Dieser Parameter wird für nicht überlappende Sockets ignoriert.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert „0“. Andernfalls wird der Wert SOCKET_ERROR zurückgegeben, und ein bestimmter Fehlercode kann durch Aufrufen von WSAGetLastError abgerufen werden.

Einige mögliche Fehlercodes sind unten aufgeführt.

Fehlercode	Bedeutung
WSAEAFNOSUPPORT	Die angegebene Adressfamilie wird nicht unterstützt.
WSAEINVAL	Es wurde ein ungültiger Parameter übergeben. Dieser Fehler wird zurückgegeben, wenn der im Socket-Parameter übergebene Socket nicht mit einer Adressfamilie des AF_INET oder AF_INET6 und einem Sockettyp von SOCK_DGRAM oder SOCK_STREAM erstellt wurde. Dieser Fehler wird auch zurückgegeben, wenn die SOCKET_SECURITY_SETTINGS-Struktur , auf die der SecuritySettings-Parameter verweist, einen falschen Wert aufweist.
WSAEISCONN	Der Socket ist verbunden. Diese Funktion ist bei einem verbundenen Socket nicht zulässig, unabhängig davon, ob der Socket verbindungsorientiert oder verbindungslos ist.
WSAEMSGSIZE	Ein übergebener Puffer war zu klein.
WSAENOTSOCK	Der im Socket-Parameter übergebene Deskriptor ist kein gültiger Socket.

Hinweise

Der Hauptzweck der WSASetSocketSecurity-Funktion besteht darin, die Sicherheit für einen Socket zu aktivieren, wenn er nicht bereits durch eine Verwaltungsrichtlinie aktiviert ist. Für IPsec bedeutet dies, dass geeignete IPsec-Filter und -Richtlinien instanziiert werden, die zum Sichern dieses Sockets verwendet werden. Die WSASetSocketSecurity-Funktion kann auch verwendet werden, um bestimmte Sicherheitsanforderungen für den Socket festzulegen.

Diese Funktion vereinfacht das Aufrufen der WSAIoctl-Funktion mit einem dwIoControlCode-Parameter , der auf SIO_SET_SECURITY festgelegt ist.

Die WSASetSocketSecurity-Funktion kann für einen Socketparameter aufgerufen werden, der mit einer Adressfamilie von AF_INET oder AF_INET6 erstellt wurde.

Für eine Clientanwendung, die verbindungsorientierte Sockets (Protokoll von IPPROTO_TCP) verwendet, sollte die WSASetSocketSecurity-Funktion aufgerufen werden, bevor die Connect-, ConnectEx- oder WSAConnect-Funktion aufgerufen wird. Wenn die WSASetSocketSecurity-Funktion nach der Connect-, ConnectEx- oder WSAConnect-Funktion aufgerufen wird, sollte WSASetSocketSecurity fehlschlagen.

Für eine Serveranwendung, die verbindungsorientierte Sockets (Protokoll von IPPROTO_TCP) verwendet, sollte die WSASetSocketSecurity-Funktion aufgerufen werden, bevor die Bindfunktion aufgerufen wird. Wenn die WSASetSocketSecurity-Funktion nach der bind-Funktion aufgerufen wird, sollte WSASetSocketSecurity fehlschlagen.

Für verbindungslose Sockets (Protokoll der IPPROTO_UDP) sollte die Anwendung die WSASetSocketSecurity-Funktionunmittelbar nach dem Socket- oder WSASocket-Aufruf aufrufen.

Serveranwendungen sollten die setockopt-Funktion aufrufen, um exklusiven Zugriff auf den port zu erhalten, der vom Socket verwendet wird. Dadurch wird verhindert, dass andere Anwendungen denselben Port verwenden. Die setockopt-Funktion wird aufgerufen, wobei der level-Parameter auf SOL_SOCKET, der optname-Parameter auf SO_EXCLUSIVEADDRUSE und der wertparameter auf ungleich null festgelegt ist. Die WSASetSocketSecurity-Funktion ruft intern den setockopt mit SO_EXCLUSIVEADDRUSE auf, um exklusiven Zugriff auf den Port zu erhalten. Dadurch soll sichergestellt werden, dass der Socket nicht anfällig für Angriffe durch andere Anwendungen ist, die auf dem lokalen Computer ausgeführt werden.

Sicherheitseinstellungen, die nicht mit WSASetSocketSecurity festgelegt werden, werden von der Standardrichtlinie des Systems oder der administrativ konfigurierten Richtlinie abgeleitet. Es wird empfohlen, dass die meisten Anwendungen den Wert SOCKET_SECURITY_PROTOCOL_DEFAULT für die SOCKET_SECURITY_PROTOCOL-Enumeration im SecurityProtocol-Element der SOCKET_SECURITY_PROTOCOL angeben, auf die der SecuritySettings-Parameter verweist. Dies macht die Anwendung neutral für Sicherheitsprotokolle und ermöglicht einfachere Bereitstellungen zwischen verschiedenen Systemen.

Wenn der SecuritySettings-Parameter auf eine SOCKET_SECURITY_SETTINGS_IPSEC-Struktur zeigt, muss das SecurityProtocol-Element der -Struktur auf SOCKET_SECURITY_PROTOCOL_IPSEC und nicht auf SOCKET_SECURITY_PROTOCOL_DEFAULT festgelegt werden.

Wenn die folgenden Bedingungen nicht erfüllt sind, wird ein Fehler zurückgegeben.

Die Adressfamilie des Socket-Parameters muss entweder AF_INET oder AF_INET6 sein.
Der Sockettyp muss entweder SOCK_STREAM oder SOCK_DGRAM sein.
Die Anwendung muss ihre Sicherheitseinstellungen festlegen, bevor die Funktionen bind, connect, ConnectEx oder WSAConnect aufgerufen werden.
Die WSASetSocketSecurity-Funktion kann nur einmal pro Socket aufgerufen werden.

Standardmäßige Secure Socket-IPsec-Richtlinie

Wenn der SecuritySettings-Parameter auf NULL festgelegt ist und keine andere administrativ angegebene IPsec-Richtlinie auf dem Computer vorhanden ist, wird eine Standardsicherheitsrichtlinie verwendet, die auf IPsec basiert, um den Datenverkehr der Anwendung zu schützen. Einige Arten von Authentifizierungsanmeldeinformationen (z. B. ein Benutzerzertifikat oder eine Domänenmitgliedschaft) müssen vorhanden sein, damit IPsec mit einer Standardrichtlinie erfolgreich ist.

Die IPsec-Standardrichtlinie wurde so konzipiert, dass IPsec-Sicherheit in so vielen Szenarien wie möglich ausgehandelt werden kann.

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

Anforderungen


Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	ws2tcpip.h
Bibliothek	Fwpuclnt.lib
DLL	Fwpuclnt.dll