Authentication

Active contributors: Daniel Stenberg, Jay Satiro, Viktor Szakats

Purpose

curl supports a long list of authentication schemes for HTTP, HTTPS, FTP, SMTP, IMAP, POP3, LDAP, SOCKS, and proxies. The mechanism-specific code lives under lib/vauth/; the protocol-side glue (Authorization headers, SASL exchanges) lives in the protocol handlers.

Schemes

Scheme	Where applicable	Source
Basic	HTTP, HTTPS, IMAP/SMTP/POP3, LDAP	lib/http.c, lib/vauth/cleartext.c
Digest	HTTP, HTTPS	lib/http_digest.c, lib/vauth/digest.c, lib/vauth/digest_sspi.c (Win)
NTLM (and SSO via SSPI on Windows)	HTTP, SMTP, IMAP, POP3	lib/http_ntlm.c, lib/vauth/ntlm.c, lib/vauth/ntlm_sspi.c, lib/curl_ntlm_core.c
Negotiate / SPNEGO	HTTP	lib/http_negotiate.c, lib/vauth/spnego_gssapi.c, lib/vauth/spnego_sspi.c, lib/curl_gssapi.c
AWS Signature V4	HTTP, HTTPS	lib/http_aws_sigv4.c
Bearer	HTTP, HTTPS	lib/http.c
OAuth 2.0 (SASL XOAUTH2/OAUTHBEARER)	SMTP, IMAP, POP3	lib/vauth/oauth2.c
GSSAPI / Kerberos	HTTP (via Negotiate), FTP, SMB	lib/curl_gssapi.c, lib/vauth/krb5_gssapi.c, lib/vauth/krb5_sspi.c, lib/socks_gssapi.c, lib/socks_sspi.c
CRAM-MD5	SMTP, IMAP, POP3	lib/vauth/cram.c
External / EXTERNAL	SASL	lib/vauth/cleartext.c
.netrc lookup	All schemes that use credentials	lib/netrc.c

Key abstractions

Symbol	File	Description
struct SASL	lib/curl_sasl.h	SASL state machine for SMTP/IMAP/POP3
Curl_sasl_*	lib/curl_sasl.c	SASL driver — invoked from the relevant protocol handler
struct ntlmdata	lib/curl_ntlm_core.h	Per-connection NTLM state
struct digestdata	lib/http_digest.h	Per-handle Digest state (nc/nonce/qop)
Curl_http_input_auth()	lib/http.c	Reads WWW-Authenticate/Proxy-Authenticate headers and chooses a scheme
Curl_http_output_auth()	lib/http.c	Renders the chosen scheme's Authorization header
Curl_aws_sigv4_*	lib/http_aws_sigv4.c	Per-request canonicalization + HMAC
Curl_auth_* (vauth API)	lib/vauth/vauth.h	The set of helpers each mechanism exposes (build, decode, free state)

How it works (HTTP)

sequenceDiagram
    participant App
    participant Easy as easy.c
    participant HTTP as http.c
    participant VAuth as vauth/
    App->>Easy: setopt USERPWD + HTTPAUTH=ANY
    Easy->>HTTP: do_it()
    HTTP->>HTTP: send unauthenticated request
    HTTP-->>App: 401 Unauthorized
    HTTP->>HTTP: parse WWW-Authenticate
    HTTP->>VAuth: build response (Digest/NTLM/Negotiate)
    VAuth-->>HTTP: encoded credentials
    HTTP->>HTTP: retry with Authorization header
    HTTP-->>App: 200 OK

When the user sets CURLOPT_HTTPAUTH = CURLAUTH_ANY (or --anyauth), curl performs an empty probe to discover the schemes the server offers, then picks the strongest. Specific selection (CURLAUTH_BASIC, CURLAUTH_DIGEST, …) skips the probe.

How it works (SASL)

SMTP, IMAP, and POP3 use SASL. The Curl_sasl_* driver in lib/curl_sasl.c:

1. Reads server CAPABILITY/AUTH advertisements.
2. Picks the strongest mechanism allowed by CURLOPT_LOGIN_OPTIONS (AUTH=NTLM, AUTH=DIGEST-MD5, etc.).
3. Drives the chosen Curl_auth_* builder per round trip.
4. Reports success or fall-through.

The mechanism-specific files (lib/vauth/digest.c, lib/vauth/ntlm.c, etc.) build and parse the SASL payloads.

NTLM and Kerberos

These schemes have two implementations because Windows users want SSO via SSPI:

• POSIX / OpenSSL builds use the in-tree implementations (lib/vauth/ntlm.c, lib/vauth/krb5_gssapi.c).
• Windows builds compiled with SSPI (USE_WINDOWS_SSPI) use SSPI directly (lib/vauth/ntlm_sspi.c, lib/vauth/krb5_sspi.c, lib/vauth/digest_sspi.c, lib/vauth/spnego_sspi.c).

The selection is compile-time via lib/curl_setup.h macros.

AWS Signature V4

Implemented in lib/http_aws_sigv4.c. Triggered by CURLOPT_AWS_SIGV4 (--aws-sigv4) which takes a colon-separated provider/region/service spec. Signs every request with HMAC-SHA256 over a canonicalized string. Used for AWS APIs and any service that accepts AWS-style signatures.

.netrc

Credentials may come from a ~/.netrc file via CURLOPT_NETRC (--netrc). The parser is in lib/netrc.c. The format is the standard machine/login/password blocks; matched entries override only when no explicit credential is provided.

Integration points

• Protocol handlers: each handler that supports auth calls into Curl_sasl_* or Curl_http_*_auth from its do_it/connecting callbacks.
• Connection cache: NTLM and Negotiate are connection-bound — once an auth context is established, the connection is locked to that user. The cache key reflects this.
• Cookies: orthogonal — cookies are managed separately (see Cookies and state).

Entry points for modification

• New auth mechanism → write lib/vauth/<name>.c exposing Curl_auth_* helpers; register it in lib/curl_sasl.c's mech table; document under docs/libcurl/opts/.
• Tweak NTLM hashing → lib/curl_ntlm_core.c. Note SSPI builds bypass this entirely.
• AWS SigV4 dialect → lib/http_aws_sigv4.c. Most providers have minor canonicalization differences; the file already handles a few.

Related pages

• Protocol handlers
• Connection management
• Cookies and state