WSAQuerySocketSecurity 関数 (ws2tcpip.h)

[アーティクル]
08/28/2023

WSAQuerySocketSecurity 関数は、ソケット上の接続に適用されるセキュリティに関する情報を照会します。

構文

INT WSAAPI WSAQuerySocketSecurity(
  [in]            SOCKET                               Socket,
  [in, optional]  const SOCKET_SECURITY_QUERY_TEMPLATE *SecurityQueryTemplate,
  [in]            ULONG                                SecurityQueryTemplateLen,
  [out, optional] SOCKET_SECURITY_QUERY_INFO           *SecurityQueryInfo,
  [in, out]       ULONG                                *SecurityQueryInfoLen,
  [in, optional]  LPWSAOVERLAPPED                      Overlapped,
  [in, optional]  LPWSAOVERLAPPED_COMPLETION_ROUTINE   CompletionRoutine
);

パラメーター

[in] Socket

セキュリティ情報のクエリを実行するソケットを識別する記述子。

[in, optional] SecurityQueryTemplate

返すクエリ情報の種類を指定する SOCKET_SECURITY_QUERY_TEMPLATE 構造体へのポインター。

このパラメーターが指すSOCKET_SECURITY_QUERY_TEMPLATE 構造体には、すべてのメンバーが既定のセキュリティ情報を要求するためのゼロが含まれている場合があります。正常に戻ると、返される SecurityQueryInfo パラメーターには、SOCKET_SECURITY_QUERY_INFOの Flags メンバーのみが設定されます。

Socket パラメーターが IPPROTO_TCP のプロトコルで作成された場合、このパラメーターは NULL ポインターである可能性があります。この場合、返される情報は、すべての値が 0 に設定された SOCKET_SECURITY_QUERY_TEMPLATE 構造体が渡された場合と同じです。既定のセキュリティ情報が必要な場合は、 プロトコルが IPPROTO_TCP のソケットに対してこのパラメーターを指定する必要があります。

peerTokenAccessMask メンバーが指定されていない (ゼロに設定されている) SOCKET_SECURITY_QUERY_TEMPLATE構造体が指定されている場合、WSAQuerySocketSecurity 関数は、SOCKET_SECURITY_QUERY_INFO構造体の PeerApplicationAccessTokenHandle および PeerMachineAccessTokenHandle メンバーを返しません。

Socket パラメーターが、IPPROTO_TCPと等しくないプロトコルで作成された場合は、SecurityQueryTemplate パラメーターを指定する必要があります。このような場合、SOCKET_SECURITY_QUERY_TEMPLATE構造体の PeerAddress メンバーは、ピア IP アドレスとポート番号と共に、AF_INETまたはAF_INET6のアドレスファミリを指定する必要があります。

[in] SecurityQueryTemplateLen

SecurityQueryTemplate パラメーターのサイズ (バイト単位)。

Socket パラメーターが IPPROTO_TCP のプロトコルで作成された場合、このパラメーターは 0 になることがあります。それ以外の場合、このパラメーターは SOCKET_SECURITY_QUERY_TEMPLATE 構造体のサイズである必要があります。

[out, optional] SecurityQueryInfo

照会された情報を含む SOCKET_SECURITY_QUERY_INFO 構造体を受け取るバッファーへのポインター。この値を NULL に設定して、出力バッファーのサイズを照会できます。

[in, out] SecurityQueryInfoLen

入力時に、 SecurityQueryInfo パラメーターのサイズ (バイト単位) へのポインター。バッファーが小さすぎてクエリされた情報を受信できない場合、呼び出しはSOCKET_ERRORを返し、クエリされた情報を返すために必要なバイト数は、このパラメーターによって示される値に設定されます。正常に呼び出されると、コピーされたバイト数が返されます。

[in, optional] Overlapped

WSAOVERLAPPED 構造体へのポインター。このパラメーターは、重複しないソケットでは無視されます。

[in, optional] CompletionRoutine

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

戻り値

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

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

エラーコード	意味
WSAEAFNOSUPPORT	指定されたアドレスファミリはサポートされていません。
WSAECONNRESET	ストリームソケットの場合、仮想回線はリモート側によってリセットされました。ソケットが使用できないため、アプリケーションはソケットを閉じる必要があります。 UDP データグラムソケットの場合、このエラーは、以前の送信操作で ICMP "ポートに到達できません" メッセージが発生したことを示します。
WSAEFAULT	パラメーターを使用しようとしたときに、システムによって無効なポインターアドレスが検出されました。 SecurityQueryInfoLen パラメーターが NULL ポインターの場合、このエラーが返されます。
WSAEINVAL	無効なパラメーターが渡されました。このエラーは、Socket パラメーターで渡されたソケットが、AF_INETまたはAF_INET6のアドレスファミリとSOCK_DGRAMまたはSOCK_STREAMのソケットの種類で作成されなかった場合に返されます。
WSAEMSGSIZE	渡されたバッファーが小さすぎます。このエラーは、SecurityQueryInfo パラメーターが NULL ポインターであるか、SecurityQueryTemplateLen パラメーターがSOCKET_SECURITY_QUERY_TEMPLATE構造体のサイズより小さい場合に、プロトコルがIPPROTO_TCPされなかった場合に Socket パラメーターに対して返されます。
WSAENOTSOCK	Socket パラメーターで渡された記述子が有効なソケットではありません。

注釈

WSAQuerySocketSecurity 関数は、ソケットの現在のセキュリティ設定に対してクエリを実行するメソッドを提供します。接続が確立されると、 WSAQuerySocketSecurity 関数を使用すると、アプリケーションは接続のセキュリティプロパティに対してクエリを実行できます。これには、ピアアクセストークンに関する情報を含めることができます。

接続指向ソケットの場合は、接続が確立された直後に WSAQuerySocketSecurity 関数を呼び出することをお勧めします。コネクションレスソケットの場合は、データが新しいピアアドレスに送信されるか、新しいピアアドレスから受信された直後に WSAQuerySocketSecurity 関数を呼び出することをお勧めします。 WSAQuerySocketSecurity 関数は、1 つのソケットで複数回呼び出すことができます。

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

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

Socket パラメーターが IPPROTO_TCP のプロトコルで作成された場合、SecurityQueryTemplate パラメーターは NULL、SecurityQueryTemplateLen パラメーターは 0 になる場合があります。それ以外の場合、 SecurityQueryTemplate パラメーターは、SOCKET_SECURITY_QUERY_TEMPLATE 構造体を指す必要があります。

接続指向ソケット (IPPROTO_TCP のプロトコルで作成されたソケット) を使用するクライアントアプリケーションの場合、接続、ConnectEx、または WSAConnect 関数が戻った後に WSAQuerySocketSecurity 関数を呼び出す必要があります。接続指向ソケット (IPPROTO_TCPのプロトコル) を使用するサーバーアプリケーションの場合、accept、AcceptEx、または WSAAccept 関数が戻った後に WSAQuerySocketSecurity 関数を呼び出す必要があります。

コネクションレスソケット (IPPROTO_UDP のプロトコルで作成されたソケット) の場合、アプリケーションは、WSASendTo または WSARecvFrom 呼び出しが新しいピアアドレスに対して返された直後に WSAQuerySocketSecurity 関数を呼び出す必要があります。

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

Socket パラメーターのアドレスファミリは、AF_INETまたはAF_INET6である必要があります。
ソケットの種類は、SOCK_STREAMまたはSOCK_DGRAMである必要があります。

要件

要件	値
サポートされている最小のクライアント	Windows Vista [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	ws2tcpip.h
Library	Fwpuclnt.lib
[DLL]	Fwpuclnt.dll