allowing all native libcurl authentication methods

README.md

@@ -14,7 +14,7 @@ Unirest is a set of lightweight HTTP libraries available in [multiple languages]
 * Utility methods to call `GET`, `HEAD`, `POST`, `PUT`, `DELETE`, `CONNECT`, `OPTIONS`, `TRACE`, `PATCH` requests
 * Supports form parameters, file uploads and custom body entities
 * Supports gzip
-* Supports Basic Authentication natively
+* Supports Basic, Digest, Negotiate, NTLM Authentication natively
 * Customizable timeout
 * Customizable default headers for every request (DRY)
 * Automatic JSON parsing into a native object for JSON responses
@@ -110,29 +110,59 @@ $body =   json_encode(array("foo" => "hellow", "bar" => "world"));
 $response = Unirest\Request::post("http://httpbin.org/post", $headers, $body);
 ```
 
-### Basic Authentication
+### Authentication
 
-Authenticating the request with basic authentication can be done by providing the `username` and `password` arguments:
+Passing a username, password *(optional)*, defaults to Basic Authentication:
+
+```php
+// basic auth
+Unirest\Request::auth('username', 'password');
+```
+
+The third parameter, which is a bitmask, will Unirest which HTTP authentication method(s) you want it to use for your proxy authentication.
+
+If more than one bit is set, Unirest *(at PHP's libcurl level)* will first query the site to see what authentication methods it supports and then pick the best one you allow it to use. *For some methods, this will induce an extra network round-trip.*
+
+**Supported Method**
+
+| Method               | Description                                                                                                                                                                                                     |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `CURLAUTH_BASIC`     | HTTP Basic authentication. This is the default choice                                                                                                                                                           | 
+| `CURLAUTH_DIGEST`    | HTTP Digest authentication. as defined in [RFC 2617](http://www.ietf.org/rfc/rfc2617.txt)                                                                                                                       | 
+| `CURLAUTH_DIGEST_IE` | HTTP Digest authentication with an IE flavor. *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.* | 
+| `CURLAUTH_NEGOTIATE` | HTTP Negotiate (SPNEGO) authentication. as defined in [RFC 4559](http://www.ietf.org/rfc/rfc4559.txt)                                                                                                           |
+| `CURLAUTH_NTLM`      | HTTP NTLM authentication. A proprietary protocol invented and used by Microsoft.                                                                                                                                |
+| `CURLAUTH_NTLM_WB`   | NTLM delegating to winbind helper. Authentication is performed by a separate binary application. *see [libcurl docs](http://curl.haxx.se/libcurl/c/CURLOPT_HTTPAUTH.html) for more info*                        | 
+| `CURLAUTH_ANY`       | This is a convenience macro that sets all bits and thus makes libcurl pick any it finds suitable. libcurl will automatically select the one it finds most secure.                                               |
+| `CURLAUTH_ANYSAFE`   | This is a convenience macro that sets all bits except Basic and thus makes libcurl pick any it finds suitable. libcurl will automatically select the one it finds most secure.                                  |
+| `CURLAUTH_ONLY`      | This is a meta symbol. OR this value together with a single specific auth value to force libcurl to probe for un-restricted auth and if not, only that single auth algorithm is acceptable.                     |
+
+```php
+// custom auth method
+Unirest\Request::proxyAuth('username', 'password', CURLAUTH_DIGEST);
+```
+
+Previous versions of **Unirest** support *Basic Authentication* by providing the `username` and `password` arguments:
 
 ```php
 $response = Unirest\Request::get("http://httpbin.org/get", null, null, "username", "password");
 ```
 
+**This has been deprecated, and will be completely removed in `v.3.0.0` please use the `Unirest\Request::auth()` method instead**
+
 ### Request Object
 
 ```php
-Unirest\Request::get($url, $headers = array(), $parameters = null, $username = null, $password = null)
+Unirest\Request::get($url, $headers = array(), $parameters = null)
-Unirest\Request::post($url, $headers = array(), $body = null, $username = null, $password = null)
+Unirest\Request::post($url, $headers = array(), $body = null)
-Unirest\Request::put($url, $headers = array(), $body = null, $username = null, $password = null)
+Unirest\Request::put($url, $headers = array(), $body = null)
-Unirest\Request::patch($url, $headers = array(), $body = null, $username = null, $password = null)
+Unirest\Request::patch($url, $headers = array(), $body = null)
-Unirest\Request::delete($url, $headers = array(), $body = null, $username = null, $password = null)
+Unirest\Request::delete($url, $headers = array(), $body = null)
 ```
   
 - `url` - Endpoint, address, or uri to be acted upon and requested information from.
 - `headers` - Request Headers as associative array or object
 - `body` - Request Body as associative array or object
-- `username` - Basic Authentication username
-- `password` - Basic Authentication password
 
 You can send a request with any [standard](http://www.iana.org/assignments/http-methods/http-methods.xhtml) or custom HTTP Method:
 
@@ -183,7 +213,6 @@ you can also set the proxy type to be one of `CURLPROXY_HTTP`, `CURLPROXY_HTTP_1
 *check the [cURL docs](http://curl.haxx.se/libcurl/c/CURLOPT_PROXYTYPE.html) for more info*.
 
 ```php
-
 // quick setup with default port: 1080
 Unirest\Request::proxy('10.10.10.1');
 
@@ -194,6 +223,26 @@ Unirest\Request::proxy('10.10.10.1', 8080, CURLPROXY_HTTP);
 Unirest\Request::proxy('10.10.10.1', 8080, CURLPROXY_HTTP, true);
 ```
 
+##### Proxy Authenticaton
+
+Passing a username, password *(optional)*, defaults to Basic Authentication:
+
+```php
+// basic auth
+Unirest\Request::proxyAuth('username', 'password');
+```
+
+The third parameter, which is a bitmask, will Unirest which HTTP authentication method(s) you want it to use for your proxy authentication. 
+
+If more than one bit is set, Unirest *(at PHP's libcurl level)* will first query the site to see what authentication methods it supports and then pick the best one you allow it to use. *For some methods, this will induce an extra network round-trip.*
+
+See [Authentication](#authentication) for more details on methods supported.
+
+```php
+// basic auth
+Unirest\Request::proxyAuth('username', 'password', CURLAUTH_DIGEST);
+```
+
 #### Default Request Headers
 
 You can set default headers that will be sent on every request:

src/Unirest/Request.php

@@ -7,15 +7,29 @@ use Unirest\Response;
 
 class Request
 {
-    private static $proxyPort = false;
-    private static $proxyType = CURLPROXY_HTTP;
-    private static $proxyTunnel = false;
-    private static $proxyAddress = false;
     private static $jsonOpts = array();
     private static $verifyPeer = true;
     private static $socketTimeout = null;
     private static $defaultHeaders = array();
 
+    private static $auth => array (
+        'user' => '',
+        'pass' => '',
+        'method' => CURLAUTH_BASIC
+    );
+
+    private static $proxy = array(
+        'port' => false,
+        'tunnel' => false,
+        'address' => false,
+        'type' => CURLPROXY_HTTP,
+        'auth' => array (
+            'user' => '',
+            'pass' => '',
+            'method' => CURLAUTH_BASIC
+        )
+    );
+
     /**
      * Set JSON decode mode
      *
@@ -81,6 +95,20 @@ class Request
         return self::$defaultHeaders = array();
     }
 
+    /**
+     * Set authentication method to use
+     *
+     * @param string $username authentication username
+     * @param string $password authentication password
+     * @param string $method authentication method
+     */
+    public static function auth($username = '', $password = '', $method = CURLAUTH_BASIC)
+    {
+        self::$auth['user'] = $username;
+        self::$auth['pass'] = $password;
+        self::$auth['method'] = $method;
+    }
+
     /**
      * Set proxy to use
      *
@@ -91,10 +119,25 @@ class Request
      */
     public static function proxy($address, $port = 1080, $type = CURLPROXY_HTTP, $tunnel = false)
     {
-        self::$proxyType = $type;
+        self::$proxy['type'] = $type;
-        self::$proxyPort = $port;
+        self::$proxy['port'] = $port;
-        self::$proxyTunnel = $tunnel;
+        self::$proxy['tunnel'] = $tunnel;
-        self::$proxyAddress = $address;
+        self::$proxy['address'] = $address;
+    }
+
+    /**
+     * Set proxy authentication method to use
+     *
+     * @param string $username authentication username
+     * @param string $password authentication password
+     * @param string $method authentication method
+     * @param string $tunnel enable/disable tunneling
+     */
+    public static function proxyAuth($username = '', $password = '', $method = CURLAUTH_BASIC)
+    {
+        self::$proxy['auth']['user'] = $username;
+        self::$proxy['auth']['pass'] = $password;
+        self::$proxy['auth']['method'] = $method;
     }
 
     /**
@@ -103,8 +146,8 @@ class Request
      * @param string $url URL to send the GET request to
      * @param array $headers additional headers to send
      * @param mixed $parameters parameters to send in the querystring
-     * @param string $username Basic Authentication username
+     * @param string $username Authentication username (deprecated)
-     * @param string $password Basic Authentication password
+     * @param string $password Authentication password (deprecated)
      * @return string|stdObj response string or stdObj if response is json-decodable
      */
     public static function get($url, $headers = array(), $parameters = null, $username = null, $password = null)
@@ -117,8 +160,8 @@ class Request
      * @param string $url URL to send the HEAD request to
      * @param array $headers additional headers to send
      * @param mixed $parameters parameters to send in the querystring
-     * @param string $username Basic Authentication username
+     * @param string $username Basic Authentication username (deprecated)
-     * @param string $password Basic Authentication password
+     * @param string $password Basic Authentication password (deprecated)
      * @return string|stdObj response string or stdObj if response is json-decodable
      */
     public static function head($url, $headers = array(), $parameters = null, $username = null, $password = null)
@@ -145,8 +188,8 @@ class Request
      * @param string $url URL to send the CONNECT request to
      * @param array $headers additional headers to send
      * @param mixed $parameters parameters to send in the querystring
-     * @param string $username Basic Authentication username
+     * @param string $username Basic Authentication username (deprecated)
-     * @param string $password Basic Authentication password
+     * @param string $password Basic Authentication password (deprecated)
      * @return string|stdObj response string or stdObj if response is json-decodable
      */
     public static function connect($url, $headers = array(), $parameters = null, $username = null, $password = null)
@@ -159,8 +202,8 @@ class Request
      * @param string $url URL to send the POST request to
      * @param array $headers additional headers to send
      * @param mixed $body POST body data
-     * @param string $username Basic Authentication username
+     * @param string $username Basic Authentication username (deprecated)
-     * @param string $password Basic Authentication password
+     * @param string $password Basic Authentication password (deprecated)
      * @return string|stdObj response string or stdObj if response is json-decodable
      */
     public static function post($url, $headers = array(), $body = null, $username = null, $password = null)
@@ -173,8 +216,8 @@ class Request
      * @param string $url URL to send the DELETE request to
      * @param array $headers additional headers to send
      * @param mixed $body DELETE body data
-     * @param string $username Basic Authentication username
+     * @param string $username Basic Authentication username (deprecated)
-     * @param string $password Basic Authentication password
+     * @param string $password Basic Authentication password (deprecated)
      * @return string|stdObj response string or stdObj if response is json-decodable
      */
     public static function delete($url, $headers = array(), $body = null, $username = null, $password = null)
@@ -187,8 +230,8 @@ class Request
      * @param string $url URL to send the PUT request to
      * @param array $headers additional headers to send
      * @param mixed $body PUT body data
-     * @param string $username Basic Authentication username
+     * @param string $username Basic Authentication username (deprecated)
-     * @param string $password Basic Authentication password
+     * @param string $password Basic Authentication password (deprecated)
      * @return string|stdObj response string or stdObj if response is json-decodable
      */
     public static function put($url, $headers = array(), $body = null, $username = null, $password = null)
@@ -201,8 +244,8 @@ class Request
      * @param string $url URL to send the PATCH request to
      * @param array $headers additional headers to send
      * @param mixed $body PATCH body data
-     * @param string $username Basic Authentication username
+     * @param string $username Basic Authentication username (deprecated)
-     * @param string $password Basic Authentication password
+     * @param string $password Basic Authentication password (deprecated)
      * @return string|stdObj response string or stdObj if response is json-decodable
      */
     public static function patch($url, $headers = array(), $body = null, $username = null, $password = null)
@@ -215,8 +258,8 @@ class Request
      * @param string $url URL to send the TRACE request to
      * @param array $headers additional headers to send
      * @param mixed $body TRACE body data
-     * @param string $username Basic Authentication username
+     * @param string $username Basic Authentication username (deprecated)
-     * @param string $password Basic Authentication password
+     * @param string $password Basic Authentication password (deprecated)
      * @return string|stdObj response string or stdObj if response is json-decodable
      */
     public static function trace($url, $headers = array(), $body = null, $username = null, $password = null)
@@ -259,8 +302,8 @@ class Request
      * @param string $url URL to send the request to
      * @param mixed $body request body
      * @param array $headers additional headers to send
-     * @param string $username  Basic Authentication username
+     * @param string $username Authentication username (deprecated)
-     * @param string $password  Basic Authentication password
+     * @param string $password Authentication password (deprecated)
      * @throws Exception if a cURL error occurs
      * @return Unirest\Response
      */
@@ -299,15 +342,21 @@ class Request
             curl_setopt($ch, CURLOPT_TIMEOUT, self::$socketTimeout);
         }
 
-        if (!empty($username)) {
+        if (!empty($self::auth['user'])) {
-            curl_setopt($ch, CURLOPT_USERPWD, $username . ':' . ((empty($password)) ? '' : $password));
+            curl_setopt($ch, CURLOPT_USERNAME, self::$auth['user']);
+            curl_setopt($ch, CURLOPT_PASSWORD, self::$auth['pass']);
+            curl_setopt($ch, CURLOPT_HTTPAUTH, self::$auth['method']);
         }
 
-        if (self::$proxyAddress) {
+        if (self::$proxy['address'] !== false) {
-            curl_setopt($ch, CURLOPT_PROXYTYPE, self::$proxyType);
+            curl_setopt($ch, CURLOPT_PROXYTYPE, self::$proxy['type']);
-            curl_setopt($ch, CURLOPT_PROXY, self::$proxyAddress);
+            curl_setopt($ch, CURLOPT_PROXY, self::$proxy['address']);
-            curl_setopt($ch, CURLOPT_PROXYPORT, self::$proxyPort);
+            curl_setopt($ch, CURLOPT_PROXYPORT, self::$proxy['port']);
-            curl_setopt($ch, CURLOPT_HTTPPROXYTUNNEL, self::$proxyTunnel);
+            curl_setopt($ch, CURLOPT_HTTPPROXYTUNNEL, self::$proxy['tunnel']);
+
+            curl_setopt($ch, CURLOPT_PROXYAUTH, self::$proxy['auth']['method']);
+            curl_setopt($ch, CURLOPT_PROXYUSERNAME, self::$proxy['auth']['user']);
+            curl_setopt($ch, CURLOPT_PROXYPASSWORD, self::$proxy['auth']['pass']);
         }
 
         $response = curl_exec($ch);