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 구조체에는 모든 멤버가 기본 보안 정보를 요청하는 0이 포함될 수 있습니다. 반환이 성공적이면 반환된 SecurityQueryInfo 매개 변수에 SOCKET_SECURITY_QUERY_INFOFlags 멤버만 설정됩니다.

Socket 매개 변수가 IPPROTO_TCP 프로토콜로 만들어진 경우 이 매개 변수는 NULL 포인터일 수 있습니다. 이 경우 반환되는 정보는 모든 값이 0으로 설정된 SOCKET_SECURITY_QUERY_TEMPLATE 구조체가 전달된 경우와 동일합니다. 기본 보안 정보가 필요한 경우 프로토콜이 IPPROTO_TCP 소켓에 대해 이 매개 변수를 지정해야 합니다.

SOCKET_SECURITY_QUERY_TEMPLATE 구조체가 지정되지 않은 PeerTokenAccessMask 멤버로 지정된 경우(0으로 설정) WSAQuerySocketSecurity 함수는 SOCKET_SECURITY_QUERY_INFO 구조체의 PeerApplicationAccessTokenHandle 및 PeerMachineAccessTokenHandle 멤버를 반환하지 않습니다.

IPPROTO_TCP 같지 않은 프로토콜을 사용하여 Socket 매개 변수를 만든 경우 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 함수는 단일 소켓에서 여러 번 호출할 수 있습니다.

이 함수는 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 프로토콜로 만든 소켓)을 사용하는 클라이언트 애플리케이션의 경우 connect, 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
라이브러리	Fwpuclnt.lib
DLL	Fwpuclnt.dll