WSAQuerySocketSecurity 関数 (ws2tcpip.h)

  • [アーティクル]

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

こちらもご覧ください

SOCKET_SECURITY_QUERY_INFO

SOCKET_SECURITY_QUERY_TEMPLATE

Secure Socket Extensions の使用

WSADeleteSocketPeerTargetName

WSAImpersonateSocketPeer

WSARevertImpersonation

WSASetSocketPeerTargetName

WSASetSocketSecurity

Windows フィルタリング プラットフォーム

Windows フィルタリング プラットフォーム API 関数

Winsock Secure Socket Extensions