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

操作が完了したときに呼び出される完了ルーチンへのポインター。このパラメーターは、重複していないソケットでは無視されます。

戻り値

関数が成功した場合の戻り値は 0 です。それ以外の場合は、 SOCKET_ERROR の値が返され、 WSAGetLastError を呼び出すことによって特定のエラーコードを取得できます。

考えられるエラーコードを次に示します。

エラーコード	意味
WSAEAFNOSUPPORT	指定されたアドレスファミリはサポートされていません。
WSAEINVAL	無効なパラメーターが渡されました。 Socket パラメーターで渡されたソケットが、AF_INETまたはAF_INET6のアドレスファミリと、SOCK_DGRAMまたはSOCK_STREAMのソケットの種類で作成されていない場合、このエラーが返されます。 SecuritySettings パラメーターが指すSOCKET_SECURITY_SETTINGS構造体の値が正しくない場合も、このエラーが返されます。
WSAEISCONN	ソケットが接続されています。この関数は、ソケットが接続指向であるかコネクションレスであるかに関係なく、接続されたソケットでは許可されません。
WSAEMSGSIZE	渡されたバッファーが小さすぎます。
WSAENOTSOCK	Socket パラメーターで渡された記述子が有効なソケットではありません。

注釈

WSASetSocketSecurity 関数の主な目的は、ソケットのセキュリティが管理ポリシーによってまだ有効になっていない場合に有効にすることです。 IPsec の場合、このソケットをセキュリティで保護するために使用される適切な IPsec フィルターとポリシーがインスタンス化されることを意味します。 WSASetSocketSecurity 関数を使用して、ソケットの特定のセキュリティ要件を設定することもできます。

この関数を使用すると、dwIoControlCode パラメーターを SIO_SET_SECURITY に設定して WSAIoctl 関数を呼び出す必要が簡単になります。

WSASetSocketSecurity 関数は、AF_INETまたはAF_INET6のアドレスファミリを使用して作成された Socket パラメーターで呼び出すことができます。

接続指向ソケット (IPPROTO_TCP のプロトコル) を使用するクライアントアプリケーションの場合、接続、ConnectEx、または WSAConnect 関数を呼び出す前に、WSASetSocketSecurity 関数を呼び出す必要があります。接続、ConnectEx、または WSAConnect 関数の後に WSASetSocketSecurity 関数が呼び出された場合、WSASetSocketSecurity は失敗します。

接続指向ソケット (IPPROTO_TCP のプロトコル) を使用するサーバーアプリケーションの場合、バインド関数を呼び出す前に WSASetSocketSecurity 関数を呼び出す必要があります。 バインド関数の後に WSASetSocketSecurity 関数を呼び出すと、WSASetSocketSecurity は失敗します。

コネクションレスソケット (IPPROTO_UDP のプロトコル) の場合、アプリケーションはソケットまたは WSASocket 呼び出しが返された直後に WSASetSocketSecurity 関数を呼び出す必要があります。

サーバーアプリケーションは setsockopt 関数を呼び出して、ソケットで使用されるポートへの排他的アクセスを取得する必要があります。これにより、他のアプリケーションが同じポートを使用できなくなります。 setsockopt 関数は、level パラメーターが SOL_SOCKET に設定され、optname パラメーターが SO_EXCLUSIVEADDRUSE に設定され、value パラメーターが 0 以外に設定された状態で呼び出されます。 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_DEFAULTではなく、SOCKET_SECURITY_PROTOCOL_IPSECに設定する必要があります。

次の条件が満たされない場合、エラーが返されます。

Socket パラメーターのアドレスファミリは、AF_INETまたはAF_INET6である必要があります。
ソケットの種類は、SOCK_STREAMまたはSOCK_DGRAMである必要があります。
アプリケーションは、バインド、接続、 ConnectEx、または WSAConnect 関数を呼び出す前に、そのセキュリティ設定を設定する必要があります。
WSASetSocketSecurity 関数は、ソケットごとに 1 回だけ呼び出すことができます。

既定の Secure Socket 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
Library	Fwpuclnt.lib
[DLL]	Fwpuclnt.dll