1[[security]]
2== Security
3
4The Elasticsearch-PHP client supports two security features: HTTP Authentication and SSL encryption.
5
6=== HTTP Authentication
7
8If your Elasticsearch server is protected by HTTP Authentication, you need to provide the credentials to ES-PHP so
9that requests can be authenticated server-side.  Authentication credentials are provided as part of the host array
10when instantiating the client:
11
12[source,php]
13----
14$hosts = [
15    'http://user:pass@localhost:9200',       // HTTP Basic Authentication
16    'http://user2:pass2@other-host.com:9200' // Different credentials on different host
17];
18
19$client = ClientBuilder::create()
20                    ->setHosts($hosts)
21                    ->build();
22----
23
24Credentials are provided per-host, which allows each host to have their own set of credentials.  All requests sent to the
25cluster will use the appropriate credentials depending on the node being talked to.
26
27=== SSL Encryption
28
29Configuring SSL is a little more complex.  You need to identify if your certificate has been signed by a public
30Certificate Authority (CA), or if it is a self-signed certificate.
31
32[NOTE]
33.A note on libcurl version
34=================
35If you believe the client is configured to correctly use SSL, but it simply is not working, check your libcurl
36version.  On certain platforms, various features may or may not be available depending on version number of libcurl.
37For example, the `--cacert` option was not added to the OSX version of libcurl until version 7.37.1.  The `--cacert`
38option is equivalent to PHP's `CURLOPT_CAINFO` constant, meaning that custom certificate paths will not work on lower
39versions.
40
41If you are encountering problems, update your libcurl version and/or check the http://curl.haxx.se/changes.html[curl changelog].
42=================
43
44==== Public CA Certificates
45
46If your certificate has been signed by a public Certificate Authority and your server has up-to-date root certificates,
47you only need to use `https` in the host path.  The client will automatically verify SSL certificates:
48
49[source,php]
50----
51$hosts = [
52    'https://localhost:9200' <1>
53];
54
55$client = ClientBuilder::create()
56                    ->setHosts($hosts)
57                    ->build();
58----
59<1> Note that `https` is used, not `http`
60
61
62If your server has out-dated root certificates, you may need to use a certificate bundle.  For PHP clients, the best
63way is to use https://github.com/composer/ca-bundle[composer/ca-bundle].  Once installed, you need to tell the client to
64use your certificates instead of the system-wide bundle.  To do this, specify the path to verify:
65
66
67[source,php]
68----
69$hosts = ['https://localhost:9200'];
70$caBundle = \Composer\CaBundle\CaBundle::getBundledCaBundlePath();
71
72$client = ClientBuilder::create()
73                    ->setHosts($hosts)
74                    ->setSSLVerification($caBundle)
75                    ->build();
76----
77
78==== Self-signed Certificates
79
80Self-signed certificates are certs that have not been signed by a public CA.  They are signed by your own organization.
81Self-signed certificates are often used for internal purposes, when you can securely spread the root certificate
82yourself.  It should not be used when being exposed to public consumers, since this leaves the client vulnerable to
83man-in-the-middle attacks.
84
85If you are using a self-signed certificate, you need to provide the certificate to the client.  This is the same syntax
86as specifying a new root bundle, but instead you point to your certificate:
87
88[source,php]
89----
90$hosts = ['https://localhost:9200'];
91$myCert = 'path/to/cacert.pem';
92
93$client = ClientBuilder::create()
94                    ->setHosts($hosts)
95                    ->setSSLVerification($myCert)
96                    ->build();
97----
98
99
100=== Using Authentication with SSL
101
102It is possible to use HTTP authentication with SSL.  Simply specify `https` in the URI, configure SSL settings as
103required and provide authentication credentials.  For example, this snippet will authenticate using Basic HTTP auth
104and a self-signed certificate:
105
106[source,php]
107----
108$hosts = ['https://user:pass@localhost:9200'];
109$myCert = 'path/to/cacert.pem';
110
111$client = ClientBuilder::create()
112                    ->setHosts($hosts)
113                    ->setSSLVerification($myCert)
114                    ->build();
115----