.\" generated by cd2nroff 0.1 from CURLOPT_SOCKS5_AUTH.md
.TH CURLOPT_SOCKS5_AUTH 3 "2026-10-14" libcurl
.SH NAME
CURLOPT_SOCKS5_AUTH \- methods for SOCKS5 proxy authentication
.SH SYNOPSIS
.nf
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKS5_AUTH, long bitmask);
.fi
.SH DESCRIPTION
Pass a long as parameter, which is set to a bitmask, to tell libcurl which
authentication method(s) are allowed for SOCKS5 proxy authentication. The only
supported flags are \fICURLAUTH_BASIC\fP, which allows username/password
authentication, and \fICURLAUTH_GSSAPI\fP, which allows GSS\-API authentication.
Set the actual username and password with the \fICURLOPT_PROXYUSERPWD(3)\fP option.

libcurl offers the SOCKS5 "no authentication" method in addition to the ones
in the bitmask, and accepts it if the proxy selects it. \fICURLAUTH_NONE\fP is zero
and therefore cannot be combined with the other flags; setting the bitmask to
\fICURLAUTH_NONE\fP makes libcurl offer only the no authentication method.

Add \fICURLAUTH_ONLY\fP to the bitmask to require authentication. libcurl then does
not offer the no authentication method, and rejects it with \fICURLE_PROXY\fP if
the proxy selects it anyway. A connection that was set up without SOCKS5
authentication is also not reused for such a transfer. Setting \fICURLAUTH_ONLY\fP
without \fICURLAUTH_BASIC\fP or \fICURLAUTH_GSSAPI\fP makes \fIcurl_easy_setopt(3)\fP return
\fICURLE_BAD_FUNCTION_ARGUMENT\fP.

The specific socks authentication method is an \fIaccess property\fP, it does not
change the security context. This means that this option changes how the
connection and access to the proxy happens when a connection is setup, but it
does not affect which proxy connections libcurl can reuse. libcurl may reuse a
connection that was set up with a different socks authentication method. Proxy
connection reuse still depends on other properties matching, such as the
protocol, proxy hostname, port number, credentials and other settings that
affect the connection.
.SH DEFAULT
CURLAUTH_BASIC | CURLAUTH_GSSAPI
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode result;
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");

    /* request to use a SOCKS5 proxy */
    curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://user:pass@myproxy.com");

    /* enable username/password authentication only */
    curl_easy_setopt(curl, CURLOPT_SOCKS5_AUTH, CURLAUTH_BASIC);

    /* Perform the request */
    result = curl_easy_perform(curl);
    curl_easy_cleanup(curl);
  }
}
.fi
.SH HISTORY
\fBCURLAUTH_\fP* macros became \fIlong\fP types in 7.26.0, prior to this version
a \fIlong\fP cast was necessary when passed to \fIcurl_easy_setopt(3)\fP.

\fICURLAUTH_ONLY\fP is supported since 8.23.0.
.SH AVAILABILITY
Added in curl 7.55.0
.SH RETURN VALUE
\fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error.

CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP.
.SH SEE ALSO
.BR CURLOPT_PROXY (3),
.BR CURLOPT_PROXYTYPE (3)