curl-library
[PATCH v2] docs: Update SPNEGO and GSS-API related doc sections
From: Michael Osipov <1983-01-06_at_gmx.net>
Date: Mon, 4 Aug 2014 09:52:33 +0200
Date: Mon, 4 Aug 2014 09:52:33 +0200
Reflect recent changes in SPNEGO and GSS-API code in the docs.
Update them with appropriate namings and remove visible spots for
GSS-Negotiate.
--- docs/FAQ | 4 ++-- docs/FEATURES | 10 ++++++---- docs/KNOWN_BUGS | 6 +++--- docs/MANUAL | 8 ++++---- docs/curl.1 | 35 ++++++++++++++--------------------- docs/libcurl/curl_version_info.3 | 13 +++++++++---- docs/libcurl/libcurl-tutorial.3 | 4 ++-- docs/libcurl/opts/CURLOPT_HTTPAUTH.3 | 14 ++++++-------- docs/libcurl/symbols-in-versions | 2 +- 9 files changed, 47 insertions(+), 49 deletions(-) diff --git a/docs/FAQ b/docs/FAQ index 0850bd4..55af84e 100644 --- a/docs/FAQ +++ b/docs/FAQ @@ -136,11 +136,11 @@ FAQ POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, TELNET and TFTP. libcurl supports HTTPS certificates, HTTP POST, HTTP PUT, FTP uploading, - kerberos, HTTP form based upload, proxies, cookies, user+password + Kerberos, SPNEGO, HTTP form based upload, proxies, cookies, user+password authentication, file transfer resume, http proxy tunneling and more! libcurl is highly portable, it builds and works identically on numerous - platforms, including Solaris, NetBSD, FreeBSD, OpenBSD, Darwin, HPUX, + platforms, including Solaris, NetBSD, FreeBSD, OpenBSD, Darwin, HP-UX, IRIX, AIX, Tru64, Linux, UnixWare, HURD, Windows, Amiga, OS/2, BeOS, Mac OS X, Ultrix, QNX, OpenVMS, RISC OS, Novell NetWare, DOS, Symbian, OSF, Android, Minix, IBM TPF and more... diff --git a/docs/FEATURES b/docs/FEATURES index 53cd54f..414fd0b 100644 --- a/docs/FEATURES +++ b/docs/FEATURES @@ -45,8 +45,8 @@ HTTP - POST - Pipelining - multipart formpost (RFC1867-style) - - authentication: Basic, Digest, NTLM (*9), Negotiate (*3) and to server and - proxy + - authentication: Basic, Digest, NTLM (*9) and Negotiate (SPNEGO) (*3) + to server and proxy - resume (both GET and PUT) - follow redirects - maximum amount of redirects to follow @@ -78,7 +78,7 @@ FTP - download - authentication - kerberos4 (*5) - - kerberos5 (*3) + - Kerberos 5 (*14) - active/passive using PORT, EPRT, PASV or EPSV - single file size information (compare to HTTP HEAD) - 'type=' URL support @@ -180,7 +180,8 @@ FOOTNOTES *1 = requires OpenSSL, GnuTLS, NSS, yassl, axTLS, PolarSSL, WinSSL (native Windows), Secure Transport (native iOS/OS X) or qssl (native IBM i) *2 = requires OpenLDAP - *3 = requires a GSSAPI-compliant library, such as Heimdal or similar + *3 = requires a GSS-API implementation (e.g., Heimdal or MIT Kerberos) or + SSPI (native Windows) *4 = requires nghttp2 and possibly a recent TLS library *5 = requires a krb4 library, such as the MIT one or similar *6 = requires c-ares @@ -195,3 +196,4 @@ FOOTNOTES *12 = requires libz *13 = requires libmetalink, and either an Apple or Microsoft operating system, or OpenSSL, or GnuTLS, or NSS + *14 = requires a GSS-API implementation (e.g., Heimdal or MIT Kerberos) diff --git a/docs/KNOWN_BUGS b/docs/KNOWN_BUGS index 70e8566..409a177 100644 --- a/docs/KNOWN_BUGS +++ b/docs/KNOWN_BUGS @@ -216,9 +216,9 @@ may have been fixed since this was written! acknowledged after the actual TCP connect (during the SOCKS "negotiate" phase). -10. To get HTTP Negotiate authentication to work fine, you need to provide a - (fake) user name (this concerns both curl and the lib) because the code - wrongly only considers authentication if there's a user name provided. +10. To get HTTP Negotiate (SPNEGO) authentication to work fine, you need to + provide a (fake) user name (this concerns both curl and the lib) because the + code wrongly only considers authentication if there's a user name provided. http://curl.haxx.se/bug/view.cgi?id=440 How? http://curl.haxx.se/mail/lib-2004-08/0182.html diff --git a/docs/MANUAL b/docs/MANUAL index 11960e1..06b3abe 100644 --- a/docs/MANUAL +++ b/docs/MANUAL @@ -108,10 +108,10 @@ USING PASSWORDS curl -u name:passwd http://machine.domain/full/path/to/file HTTP offers many different methods of authentication and curl supports - several: Basic, Digest, NTLM and Negotiate. Without telling which method to - use, curl defaults to Basic. You can also ask curl to pick the most secure - ones out of the ones that the server accepts for the given URL, by using - --anyauth. + several: Basic, Digest, NTLM and Negotiate (SPNEGO). Without telling which + method to use, curl defaults to Basic. You can also ask curl to pick the + most secure ones out of the ones that the server accepts for the given URL, + by using --anyauth. NOTE! According to the URL specification, HTTP URLs can not contain a user and password, so that style will not work when using curl via a proxy, even diff --git a/docs/curl.1 b/docs/curl.1 index b47bc4b..962d750 100644 --- a/docs/curl.1 +++ b/docs/curl.1 @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH curl 1 "27 July 2012" "Curl 7.27.0" "Curl Manual" +.TH curl 1 "2 Aug 2014" "Curl 7.38.0" "Curl Manual" .SH NAME curl \- transfer a URL .SH SYNOPSIS @@ -827,9 +827,8 @@ If this option is used several times, the last one will be used. should be one of 'clear', 'safe', 'confidential', or 'private'. Should you use a level that is not one of these, 'private' will instead be used. -This option requires a library built with kerberos4 or GSSAPI -(GSS-Negotiate) support. This is not very common. Use \fI-V, --version\fP to -see if your curl supports it. +This option requires a library built with kerberos4 support. This is not +very common. Use \fI-V, --version\fP to see if your curl supports it. If this option is used several times, the last one will be used. .IP "-l, --list-only" @@ -1024,18 +1023,13 @@ Very similar to \fI--netrc\fP, but this option makes the .netrc usage \fBoptional\fP and not mandatory as the \fI--netrc\fP option does. .IP "--negotiate" -(HTTP) Enables GSS-Negotiate authentication. The GSS-Negotiate method was -designed by Microsoft and is used in their web applications. It is primarily -meant as a support for Kerberos5 authentication but may be also used along -with another authentication method. For more information see IETF draft -draft-brezak-spnego-http-04.txt. +(HTTP) Enables Negotiate (SPNEGO) authentication. -If you want to enable Negotiate for your proxy authentication, then use +If you want to enable Negotiate (SPNEGO) for proxy authentication, then use \fI--proxy-negotiate\fP. -This option requires a library built with GSSAPI support. This is -not very common. Use \fI-V, --version\fP to see if your version supports -GSS-Negotiate. +This option requires a library built with GSS-API or SSPI support. Use \fI-V, +--version\fP to see if your curl supports GSS-API/SSPI and SPNEGO. When using this option, you must also provide a fake \fI-u, --user\fP option to activate the authentication code properly. Sending a '-u :' is enough as the @@ -1254,8 +1248,8 @@ the default authentication method curl uses with proxies. Tells curl to use HTTP Digest authentication when communicating with the given proxy. Use \fI--digest\fP for enabling HTTP Digest with a remote host. .IP "--proxy-negotiate" -Tells curl to use HTTP Negotiate authentication when communicating -with the given proxy. Use \fI--negotiate\fP for enabling HTTP Negotiate +Tells curl to use HTTP Negotiate (SPNEGO) authentication when communicating +with the given proxy. Use \fI--negotiate\fP for enabling HTTP Negotiate (SPNEGO) with a remote host. (Added in 7.17.1) .IP "--proxy-ntlm" Tells curl to use HTTP NTLM authentication when communicating with the given @@ -1518,7 +1512,7 @@ sockd/proxy-name --socks5 proxy-name \fI--socks5-gssapi-service\fP sockd/real-name would use sockd/real-name for cases where the proxy-name does not match the principal name. (Added in 7.19.4). .IP "--socks5-gssapi-nec" -As part of the gssapi negotiation a protection mode is negotiated. RFC 1961 +As part of the GSS-API negotiation a protection mode is negotiated. RFC 1961 says in section 4.3/4.4 it should be protected, but the NEC reference implementation does not. The option \fI--socks5-gssapi-nec\fP allows the unprotected exchange of the protection mode negotiation. (Added in 7.19.4). @@ -1917,22 +1911,21 @@ HTTPS and FTPS are supported. Automatic decompression of compressed files over HTTP is supported. .IP "NTLM" NTLM authentication is supported. -.IP "GSS-Negotiate" -Negotiate authentication and krb5 for FTP is supported. .IP "Debug" This curl uses a libcurl built with Debug. This enables more error-tracking and memory debugging etc. For curl-developers only! .IP "AsynchDNS" This curl uses asynchronous name resolves. .IP "SPNEGO" -SPNEGO Negotiate authentication is supported. +SPNEGO authentication is supported. .IP "Largefile" This curl supports transfers of large files, files larger than 2GB. .IP "IDN" This curl supports IDN - international domain names. +.IP "GSS-API" +GSS-API is supported. .IP "SSPI" -SSPI is supported. If you use NTLM and set a blank user name, curl will -authenticate with your current user and password. +SSPI is supported. .IP "TLS-SRP" SRP (Secure Remote Password) authentication is supported for TLS. .IP "Metalink" diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 index e043769..26a8acf 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.3 @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH curl_version_info 3 "18 Feb 2014" "libcurl 7.33.0" "libcurl Manual" +.TH curl_version_info 3 "2 Aug 2014" "libcurl 7.38.0" "libcurl Manual" .SH NAME curl_version_info - returns run-time libcurl version info .SH SYNOPSIS @@ -124,9 +124,14 @@ libcurl was built with support for IDNA, domain names with international letters. (Added in 7.12.0) .IP CURL_VERSION_SSPI libcurl was built with support for SSPI. This is only available on Windows and -makes libcurl use Windows-provided functions for NTLM authentication. It also -allows libcurl to use the current user and the current user's password without -the app having to pass them on. (Added in 7.13.2) +makes libcurl use Windows-provided functions for NTLM and SPNEGO authentication. +It also allows libcurl to use the current user credentials without the app having +to pass them on. (Added in 7.13.2) +.IP CURL_VERSION_GSSAPI +libcurl was built with support for GSS-API. This makes libcurl use provided +functions for Kerberos and SPNEGO authentication. It also allows libcurl +to use the current user credentials without the app having to pass them on. +(Added in 7.38.0) .IP CURL_VERSION_CONV libcurl was built with support for character conversions, as provided by the CURLOPT_CONV_* callbacks. (Added in 7.15.4) diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 018001d..17f4c3f 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH libcurl-tutorial 3 "4 Mar 2009" "libcurl" "libcurl programming" +.TH libcurl-tutorial 3 "2 Aug 2014" "libcurl" "libcurl programming" .SH NAME libcurl-tutorial \- libcurl programming tutorial .SH "Objective" @@ -442,7 +442,7 @@ authentication method is called 'Basic', which is sending the name and password in clear-text in the HTTP request, base64-encoded. This is insecure. At the time of this writing, libcurl can be built to use: Basic, Digest, NTLM, -Negotiate, GSS-Negotiate and SPNEGO. You can tell libcurl which one to use +Negotiate (SPNEGO). You can tell libcurl which one to use with \fICURLOPT_HTTPAUTH(3)\fP as in: curl_easy_setopt(easyhandle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST); diff --git a/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 b/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 index 3f0ab12..35d75aa 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 +++ b/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_HTTPAUTH 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.TH CURLOPT_HTTPAUTH 3 "2 Aug 2014" "libcurl 7.38.0" "curl_easy_setopt options" .SH NAME CURLOPT_HTTPAUTH \- set HTTP server authentication methods to try .SH SYNOPSIS @@ -56,14 +56,12 @@ defined in RFC2617 and is a more secure way to do authentication over public networks than the regular old-fashioned Basic method. The IE flavor is simply that libcurl will use a special "quirk" that IE is known to have used before version 7 and that some servers require the client to use. -.IP CURLAUTH_GSSNEGOTIATE -HTTP GSS-Negotiate authentication. The GSS-Negotiate (also known as plain -\&"Negotiate") method was designed by Microsoft and is used in their web -applications. It is primarily meant as a support for Kerberos5 authentication -but may also be used along with other authentication methods. For more -information see IETF draft draft-brezak-spnego-http-04.txt. +.IP CURLAUTH_NEGOTIATE +HTTP Negotiate (SPNEGO) authentication. Negotiate authentication is defined +in RFC 4559 and is the most secure way to perform authentication over HTTP. -You need to build libcurl with a suitable GSS-API library for this to work. +You need to build libcurl with a suitable GSS-API library or SSPI on Windows +for this to work. .IP CURLAUTH_NTLM HTTP NTLM authentication. A proprietary protocol invented and used by Microsoft. It uses a challenge-response and hash concept similar to Digest, to diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 5cbeff0..d4ba61a 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -17,7 +17,7 @@ CURLAUTH_ANYSAFE 7.10.6 CURLAUTH_BASIC 7.10.6 CURLAUTH_DIGEST 7.10.6 CURLAUTH_DIGEST_IE 7.19.3 -CURLAUTH_GSSNEGOTIATE 7.10.6 +CURLAUTH_GSSNEGOTIATE 7.10.6 7.38.0 CURLAUTH_NEGOTIATE 7.38.0 CURLAUTH_NONE 7.10.6 CURLAUTH_NTLM 7.10.6 -- 2.0.2 ------------------------------------------------------------------- List admin: http://cool.haxx.se/list/listinfo/curl-library Etiquette: http://curl.haxx.se/mail/etiquette.htmlReceived on 2014-08-04