Return to CURLOPT_HTTPAUTH.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl / opts

Annotation of embedaddon/curl/docs/libcurl/opts/CURLOPT_HTTPAUTH.3, revision 1.1

1.1     ! misho       1: .\" **************************************************************************
        !             2: .\" *                                  _   _ ____  _
        !             3: .\" *  Project                     ___| | | |  _ \| |
        !             4: .\" *                             / __| | | | |_) | |
        !             5: .\" *                            | (__| |_| |  _ <| |___
        !             6: .\" *                             \___|\___/|_| \_\_____|
        !             7: .\" *
        !             8: .\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al.
        !             9: .\" *
        !            10: .\" * This software is licensed as described in the file COPYING, which
        !            11: .\" * you should have received as part of this distribution. The terms
        !            12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
        !            13: .\" *
        !            14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
        !            15: .\" * copies of the Software, and permit persons to whom the Software is
        !            16: .\" * furnished to do so, under the terms of the COPYING file.
        !            17: .\" *
        !            18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
        !            19: .\" * KIND, either express or implied.
        !            20: .\" *
        !            21: .\" **************************************************************************
        !            22: .\"
        !            23: .TH CURLOPT_HTTPAUTH 3 "June 15, 2018" "libcurl 7.70.0" "curl_easy_setopt options"
        !            24: 
        !            25: .SH NAME
        !            26: CURLOPT_HTTPAUTH \- set HTTP server authentication methods to try
        !            27: .SH SYNOPSIS
        !            28: .nf
        !            29: #include <curl/curl.h>
        !            30: 
        !            31: CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPAUTH, long bitmask);
        !            32: .SH DESCRIPTION
        !            33: Pass a long as parameter, which is set to a bitmask, to tell libcurl which
        !            34: authentication method(s) you want it to use speaking to the remote server.
        !            35: 
        !            36: The available bits are listed below. If more than one bit is set, libcurl will
        !            37: first query the site to see which authentication methods it supports and then
        !            38: pick the best one you allow it to use. For some methods, this will induce an
        !            39: extra network round-trip. Set the actual name and password with the
        !            40: \fICURLOPT_USERPWD(3)\fP option or with the \fICURLOPT_USERNAME(3)\fP and the
        !            41: \fICURLOPT_PASSWORD(3)\fP options.
        !            42: 
        !            43: For authentication with a proxy, see \fICURLOPT_PROXYAUTH(3)\fP.
        !            44: 
        !            45: .IP CURLAUTH_BASIC
        !            46: HTTP Basic authentication. This is the default choice, and the only method
        !            47: that is in wide-spread use and supported virtually everywhere. This sends
        !            48: the user name and password over the network in plain text, easily captured by
        !            49: others.
        !            50: .IP CURLAUTH_DIGEST
        !            51: HTTP Digest authentication.  Digest authentication is defined in RFC2617 and
        !            52: is a more secure way to do authentication over public networks than the
        !            53: regular old-fashioned Basic method.
        !            54: .IP CURLAUTH_DIGEST_IE
        !            55: HTTP Digest authentication with an IE flavor.  Digest authentication is
        !            56: defined in RFC2617 and is a more secure way to do authentication over public
        !            57: networks than the regular old-fashioned Basic method. The IE flavor is simply
        !            58: that libcurl will use a special "quirk" that IE is known to have used before
        !            59: version 7 and that some servers require the client to use.
        !            60: .IP CURLAUTH_BEARER
        !            61: HTTP Bearer token authentication, used primarily in OAuth 2.0 protocol.
        !            62: 
        !            63: You can set the Bearer token to use with \fICURLOPT_XOAUTH2_BEARER(3)\fP.
        !            64: .IP CURLAUTH_NEGOTIATE
        !            65: HTTP Negotiate (SPNEGO) authentication. Negotiate authentication is defined
        !            66: in RFC 4559 and is the most secure way to perform authentication over HTTP.
        !            67: 
        !            68: You need to build libcurl with a suitable GSS-API library or SSPI on Windows
        !            69: for this to work.
        !            70: .IP CURLAUTH_NTLM
        !            71: HTTP NTLM authentication. A proprietary protocol invented and used by
        !            72: Microsoft. It uses a challenge-response and hash concept similar to Digest, to
        !            73: prevent the password from being eavesdropped.
        !            74: 
        !            75: You need to build libcurl with either OpenSSL, GnuTLS or NSS support for this
        !            76: option to work, or build libcurl on Windows with SSPI support.
        !            77: .IP CURLAUTH_NTLM_WB
        !            78: NTLM delegating to winbind helper. Authentication is performed by a separate
        !            79: binary application that is executed when needed. The name of the application
        !            80: is specified at compile time but is typically /usr/bin/ntlm_auth
        !            81: 
        !            82: Note that libcurl will fork when necessary to run the winbind application and
        !            83: kill it when complete, calling waitpid() to await its exit when done. On POSIX
        !            84: operating systems, killing the process will cause a SIGCHLD signal to be
        !            85: raised (regardless of whether \fICURLOPT_NOSIGNAL(3)\fP is set), which must be
        !            86: handled intelligently by the application. In particular, the application must
        !            87: not unconditionally call wait() in its SIGCHLD signal handler to avoid being
        !            88: subject to a race condition.  This behavior is subject to change in future
        !            89: versions of libcurl.
        !            90: .IP CURLAUTH_ANY
        !            91: This is a convenience macro that sets all bits and thus makes libcurl pick any
        !            92: it finds suitable. libcurl will automatically select the one it finds most
        !            93: secure.
        !            94: .IP CURLAUTH_ANYSAFE
        !            95: This is a convenience macro that sets all bits except Basic and thus makes
        !            96: libcurl pick any it finds suitable. libcurl will automatically select the one
        !            97: it finds most secure.
        !            98: .IP CURLAUTH_ONLY
        !            99: This is a meta symbol. OR this value together with a single specific auth
        !           100: value to force libcurl to probe for un-restricted auth and if not, only that
        !           101: single auth algorithm is acceptable.
        !           102: .SH DEFAULT
        !           103: CURLAUTH_BASIC
        !           104: .SH PROTOCOLS
        !           105: HTTP
        !           106: .SH EXAMPLE
        !           107: .nf
        !           108: CURL *curl = curl_easy_init();
        !           109: if(curl) {
        !           110:   CURLcode ret;
        !           111:   curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
        !           112:   /* allow whatever auth the server speaks */
        !           113:   curl_easy_setopt(curl, CURLOPT_HTTPAUTH, CURLAUTH_ANY);
        !           114:   curl_easy_setopt(curl, CURLOPT_USERPWD, "james:bond");
        !           115:   ret = curl_easy_perform(curl);
        !           116: }
        !           117: .fi
        !           118: .SH AVAILABILITY
        !           119: Option Added in 7.10.6.
        !           120: 
        !           121: CURLAUTH_DIGEST_IE was added in 7.19.3
        !           122: 
        !           123: CURLAUTH_ONLY was added in 7.21.3
        !           124: 
        !           125: CURLAUTH_NTLM_WB was added in 7.22.0
        !           126: 
        !           127: CURLAUTH_BEARER was added in 7.61.0
        !           128: .SH RETURN VALUE
        !           129: Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
        !           130: CURLE_NOT_BUILT_IN if the bitmask specified no supported authentication
        !           131: methods.
        !           132: .SH "SEE ALSO"
        !           133: .BR CURLOPT_PROXYAUTH "(3), " CURLOPT_USERPWD "(3), "