From b3ea4eab7272182e3b9fe6fbbd77ce779991eb9f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A1s=20Boroska?= <andras.boroska@gmail.com>
Date: Thu, 25 Jul 2019 05:54:41 +0200
Subject: [PATCH] document self-signed certificate usage (#578)

Also document how to use client certificates, and CRLs.
---
 README.md         | 45 +++++++++++++++++++++++++++++++++++++++++++++
 doc/README.md     | 45 +++++++++++++++++++++++++++++++++++++++++++++
 doc/overview.edoc | 43 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 133 insertions(+)

diff --git a/README.md b/README.md
index 4e37544f..ed465f87 100644
--- a/README.md
+++ b/README.md
@@ -423,6 +423,51 @@ Options = [{follow_redirect, true}, {max_redirect, 5}],
 {ok, Body1} = hackney:body(Ref).
 ```
 
+### Use SSL/TLS with self signed certificates
+
+Hackney uses CA bundles adapted from Mozilla by
+[certifi](https://hex.pm/packages/certifi).
+Recognising an organisation specific (self signed) certificates is possible
+by providing the necessary `ssl_options`. Note that `ssl_options` overrides all
+options passed to the ssl module.
+
+ex (>= Erlang 21):
+
+```erlang
+
+CACertFile = <path_to_self_signed_ca_bundle>,
+CrlCheckTimeout = 5000,
+SSLOptions = [
+{verify, verify_peer},
+{versions, ['tlsv1.2']},
+{cacertfile, CACertFile},
+{crl_check, peer},
+{crl_cache, {ssl_crl_cache, {internal, [{http, CrlCheckTimeout}]}}},
+{customize_hostname_check,
+  [{match_fun, public_key:pkix_verify_hostname_match_fun(https)}]}],
+
+Method = get,
+URL = "http://my-organisation/",
+ReqHeaders = [],
+ReqBody = <<>>,
+Options = [{ssl_options, SSLoptions}],
+{ok, S, H, Ref} = hackney:request(Method, URL, ReqHeaders,
+                                  ReqBody, Options),
+
+%% To provide client certificate:
+
+CertFile = <path_to_client_certificate>,
+KeyFile = <path_to_client_private_key>,
+SSLOptions1 = SSLoptions ++ [
+{certfile, CertFile},
+{keyfile, KeyFile}
+],
+Options1 = [{ssl_options, SSLoptions1}],
+{ok, S1, H1, Ref1} = hackney:request(Method, URL, ReqHeaders,
+                                     ReqBody, Options1).
+
+```
+
 ### Proxy a connection
 
 #### HTTP Proxy
diff --git a/doc/README.md b/doc/README.md
index 0f7fa9ee..fecd42e6 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -423,6 +423,51 @@ Options = [{follow_redirect, true}, {max_redirect, 5}],
 {ok, Body1} = hackney:body(Ref).
 ```
 
+### Use SSL/TLS with self signed certificates
+
+Hackney uses CA bundles adapted from Mozilla by
+[certifi](https://hex.pm/packages/certifi).
+Recognising an organisation specific (self signed) certificates is possible
+by providing the necessary `ssl_options`. Note that `ssl_options` overrides all
+options passed to the ssl module.
+
+ex (>= Erlang 21):
+
+```erlang
+
+CACertFile = <path_to_self_signed_ca_bundle>,
+CrlCheckTimeout = 5000,
+SSLOptions = [
+{verify, verify_peer},
+{versions, ['tlsv1.2']},
+{cacertfile, CACertFile},
+{crl_check, peer},
+{crl_cache, {ssl_crl_cache, {internal, [{http, CrlCheckTimeout}]}}},
+{customize_hostname_check,
+  [{match_fun, public_key:pkix_verify_hostname_match_fun(https)}]}],
+
+Method = get,
+URL = "http://my-organisation/",
+ReqHeaders = [],
+ReqBody = <<>>,
+Options = [{ssl_options, SSLoptions}],
+{ok, S, H, Ref} = hackney:request(Method, URL, ReqHeaders,
+                                  ReqBody, Options),
+
+%% To provide client certificate:
+
+CertFile = <path_to_client_certificate>,
+KeyFile = <path_to_client_private_key>,
+SSLOptions1 = SSLoptions ++ [
+{certfile, CertFile},
+{keyfile, KeyFile}
+],
+Options1 = [{ssl_options, SSLoptions1}],
+{ok, S1, H1, Ref1} = hackney:request(Method, URL, ReqHeaders,
+                                     ReqBody, Options1).
+
+```
+
 ### Proxy a connection
 
 #### HTTP Proxy
diff --git a/doc/overview.edoc b/doc/overview.edoc
index 9b92718c..36e28f80 100644
--- a/doc/overview.edoc
+++ b/doc/overview.edoc
@@ -419,6 +419,49 @@ Options = [{follow_redirect, true}, {max_redirect, 5}],
                                      ReqBody, Options),
 {ok, Body1} = hackney:body(Ref).</pre>
 
+### Use SSL/TLS with self signed certificates
+
+Hackney uses CA bundles adapted from Mozilla by
+[certifi](https://hex.pm/packages/certifi).
+Recognising an organisation specific (self signed) certificates is possible
+by providing the necessary `ssl_options'. Note that `ssl_options' overrides all
+options passed to the ssl module.
+
+ex (>= Erlang 21):
+
+<pre lang="erlang">
+CACertFile = &lt;path_to_self_signed_ca_bundle>,
+CrlCheckTimeout = 5000,
+SSLOptions = [
+{verify, verify_peer},
+{versions, ['tlsv1.2']},
+{cacertfile, CACertFile},
+{crl_check, peer},
+{crl_cache, {ssl_crl_cache, {internal, [{http, CrlCheckTimeout}]}}},
+{customize_hostname_check,
+  [{match_fun, public_key:pkix_verify_hostname_match_fun(https)}]}],
+
+Method = get,
+URL = "http://my-organisation/",
+ReqHeaders = [],
+ReqBody = &lt;&lt;>>,
+Options = [{ssl_options, SSLoptions}],
+{ok, S, H, Ref} = hackney:request(Method, URL, ReqHeaders,
+                                  ReqBody, Options),
+
+%% To provide client certificate:
+
+CertFile = &lt;path_to_client_certificate>,
+KeyFile = &lt;path_to_client_private_key>,
+SSLOptions1 = SSLoptions ++ [
+{certfile, CertFile},
+{keyfile, KeyFile}
+],
+Options1 = [{ssl_options, SSLoptions1}],
+{ok, S1, H1, Ref1} = hackney:request(Method, URL, ReqHeaders,
+                                     ReqBody, Options1).
+</pre>
+
 ### Proxy a connection
 
 #### HTTP Proxy