updated ssl/https docs

docs/api_conventions.asciidoc

@@ -21,6 +21,7 @@ NOTE: the https://github.com/fullscale/elastic.js[elastic.js] library can be use
   * `requestTimeout` -- <<config-request-timeout, more info>>
   * `maxRetries` -- <<config-max-retries, more info>>
 
+[[api-conventions-cb]]
 === Callbacks or Promises
 When a callback is passed to any of the API methods, it will be called with `(err, response, status)`. If you prefer to use promises, don't pass a callback and a promise will be returned. The promise will either be resolved with the response body, or rejected with the error that occured (including any 300+ response for non "exists" methods).
 

docs/host.asciidoc

@@ -44,42 +44,45 @@ Options :::
 `...`::
 `Any` -- When the host receives a configuration object, it assigns all of the object's keys to itself. This allows you to pass in arbitrary keys and values that can be used within selectors, or other custom functionality.
 
-`pfx`::
+`ssl`::
+`Object` -- configuration options pertaining to HTTPS/SSL. For more information visit the <<auth-reference>> Section.
+
+`ssl.pfx`::
 `String,Array[String]` -- Certificate, Private key and CA certificates to use for SSL.
 
 Default ::: `null`
 
-`key`::
+`ssl.key`::
 `String` -- Private key to use for SSL.
 
 Default ::: `null`
 
-`passphrase`::
+`ssl.passphrase`::
 `String` -- A string of passphrase for the private key or pfx.
 
 Default ::: `null`
 
-`cert`::
+`ssl.cert`::
 `String` -- Public x509 certificate to use.
 
 Default ::: `null`
 
-`ca`::
+`ssl.ca`::
 `String,Array[String]` -- An authority certificate or array of authority certificates to check the remote host against.
 
 Default ::: `null`
 
-`ciphers`::
+`ssl.ciphers`::
 `String` -- A string describing the ciphers to use or exclude. Consult http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for details on the format.
 
 Default ::: `null`
 
-`rejectUnauthorized`::
+`ssl.rejectUnauthorized`::
 `Boolean` -- If true, the server certificate is verified against the list of supplied CAs. An 'error' event is emitted if verification fails. Verification happens at the connection level, before the HTTP request is sent.
 
-Default ::: `true`
+Default ::: `false`
 
-`secureProtocol`::
+`ssl.secureProtocol`::
 `String` -- The SSL method to use, e.g. TLSv1_method to force TLS version 1. The possible values depend on your installation of OpenSSL and are defined in the constant SSL_METHODS.
 
 Default ::: `null`

docs/index.asciidoc

@@ -10,6 +10,8 @@ include::api_conventions.asciidoc[]
 
 include::configuration.asciidoc[]
 
+include::ssl_authentication.asciidoc[]
+
 include::extending_core_components.asciidoc[]
 
 include::logging.asciidoc[]

docs/ssl_authentication.asciidoc

@@ -0,0 +1,49 @@
+[[auth-reference]]
+== SSL and Authentication
+
+You can configure the client to use SSL for connecting to your elasticsearch cluster, including certificate verification and http auth.
+
+=== Basic Auth
+
+Basic authentication credentials can be configured on a per-host basis using URL notiation, or at the `auth:` property of a host config object.
+
+.Credentials directly in the host url:
+[source,js]
+-----
+var client = new elasticsearch.Client({
+  host: 'https://user:password@my-site.com:9200'
+})
+-----
+
+.Credentials as a property of the host config:
+[source,js]
+-----
+var client = new elasticsearch.Client({
+  host: [
+    {
+      host: 'es1.internal.org',
+      auth: 'user:password'
+    }
+  ]
+});
+-----
+
+=== HTTPS/SSL
+
+Without any additional configuration you can specify `https://` host urls, but the certificates used to sign these requests will not verified (`rejectUnauthorized: false`). To turn on certificate verification you must specify an `ssl:` object either in the top level config or in each host config object and set `rejectUnauthorized: true`. The ssl config object can contain many of the same configuration options that http://nodejs.org/docs/latest/api/tls.html#tls_tls_connect_port_host_options_callback[`tls.connect()`] accepts. For convenience these options are also listed in the <<host-reference>> reference.
+
+.Specify a certificate authority that should be used to verify server certifcates on all nodes:
+[source,js]
+-----
+var client = new elasticsearch.Client({
+  hosts: [
+    'https://box1.internal.org',
+    'https://box2.internal.org',
+    'https://box3.internal.org'
+  ],
+  ssl: {
+    ca: fs.readFileSync('./cacert.pem'),
+    rejectUnauthorized: true
+  }
+});
+-----