SO_CONDITIONAL_ACCEPT socket option

Article
01/07/2021

The SO_CONDITIONAL_ACCEPT socket option is designed to allow an application to decide whether or not to accept an incoming connection on a listening socket.

Socket option value

The constant that represents this socket option is 0x3002.

Syntax

int setsockopt(
  (SOCKET) s,      // descriptor identifying a socket 
  (int) SOL_SOCKET,   // level
  (int) SO_CONDITIONAL_ACCEPT, // optname
  (char *) optval,         // input buffer,
  (int) optlen,       // size of input buffer
);

Parameters

s [in]

A descriptor identifying the socket.

level [in]

The level at which the option is defined. Use SOL_SOCKET for this operation.

optname [in]

The socket option for which the value is to be set. Use SO_CONDITIONAL_ACCEPT for this operation.

optval [out]

A pointer to the buffer containing the value for the option to set. This parameter should point to buffer equal to or larger than the size of a DWORD value.

This value is treated as a boolean value with 0 used to indicate FALSE (disabled) and a nonzero value to indicate TRUE (enabled).

optlen [in, out]

A pointer to the size, in bytes, of the optval buffer. This size must be equal to or larger than the size of a DWORD value.

Return value

If the operation completes successfully, setsockopt returns zero.

If the operation fails, a value of SOCKET_ERROR is returned and a specific error code can be retrieved by calling WSAGetLastError.

Error code	Meaning
WSANOTINITIALISED	A successful WSAStartup call must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEFAULT	One of the optval or the optlen parameters point to memory that is not in a valid part of the user address space. This error is also returned if the value pointed to by the optlen parameter is less than the size of a DWORD value.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEINVAL	The level parameter is unknown or invalid. This error is also returned if the socket was already in a listening state.
WSAENOPROTOOPT	The option is unknown or unsupported by the indicated protocol family.
WSAENOTSOCK	The descriptor is not a socket.

Remarks

The setsockopt function called with the SO_CONDITIONAL_ACCEPT socket option allows an application to decide whether or not to accept an incoming connection on a listening socket. The conditional accept option for a socket is disabled (set to FALSE) by default.

When this socket option is enabled, the TCP stack does not automatically accept connections. It waits for the application to indicate that it accepts the connection via the conditional accept callback registered with WSAAccept function. Once a connection request is received, Winsock invokes the conditional accept callback registered by the application. Only when the conditional accept callback returns CF_ACCEPT will Winsock notify the transport to fully accept the connection.

When the SO_CONDITIONAL_ACCEPT socket option is set to enabled (set to TRUE), this has several side effects on the socket:

This disables the TCP stack's built-in SYN attack protection defenses, since the application is now taking ownership of accepting connections.
This effectively disables the listen backlog since connections aren't accepted on behalf of a listening socket. A connection is never fully accepted until the application fully accepts using the CF_ACCEPT mechanism.
This also means the application take care to always be in a state to readily handle the accept callbacks to accept the connection. If the application is busy doing other processing, then the client side may time out before the application actually accepts the connection. This leads to a poor client experience.

Generally, the main reason applications use conditional accept is to inspect the source IP address or port used by the connecting client and then decide to accept or reject the connection. However, applications are likely to perform better if the SO_CONDITIONAL_ACCEPT option is not enabled and the application allows the TCP stack and the listen backlog to work as expected. Then when the application handles the accepted connection, if it is from a improper IP source address or port, the application can just close the socket. The security drawback to this behavior is that now the client has confirmation that the application is listening on an IP address and port since it forcefully closed the previously accepted connection. However, the drawbacks to enabling SO_CONDITIONAL_ACCEPT generally outweigh this limitation.

The getsockopt function called with the SO_CONDITIONAL_ACCEPT socket option allows an application to retrieve the current state of the conditional accept option, although this is feature not normally used. If an application needs to enable conditional accept on a socket, it justs calls the setsockopt function to enable the option.

Note that the Ws2def.h header file is automatically included in Winsock2.h, and should never be used directly.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Header	Ws2def.h (include Winsock2.h)