From 9c80a8810759c9ed19606547c5aaa47aa1699be4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Sat, 26 Nov 2016 12:58:19 +0100
Subject: Add Ranch 1.3 and various small fixes

---
 docs/en/ranch/1.3/guide/ssl_auth.asciidoc | 120 ++++++++++++++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 docs/en/ranch/1.3/guide/ssl_auth.asciidoc

(limited to 'docs/en/ranch/1.3/guide/ssl_auth.asciidoc')

diff --git a/docs/en/ranch/1.3/guide/ssl_auth.asciidoc b/docs/en/ranch/1.3/guide/ssl_auth.asciidoc
new file mode 100644
index 00000000..de0bbaf0
--- /dev/null
+++ b/docs/en/ranch/1.3/guide/ssl_auth.asciidoc
@@ -0,0 +1,120 @@
+== SSL client authentication
+
+=== Purpose
+
+SSL client authentication is a mechanism allowing applications to
+identify certificates. This allows your application to make sure that
+the client is an authorized certificate, but makes no claim about
+whether the user can be trusted. This can be combined with a password
+based authentication to attain greater security.
+
+The server only needs to retain the certificate serial number and
+the certificate issuer to authenticate the certificate. Together,
+they can be used to uniquely identify a certicate.
+
+As Ranch allows the same protocol code to be used for both SSL and
+non-SSL transports, you need to make sure you are in an SSL context
+before attempting to perform an SSL client authentication. This
+can be done by checking the return value of `Transport:name/0`.
+
+=== Obtaining client certificates
+
+You can obtain client certificates from various sources. You can
+generate them yourself, or you can use a service like CAcert.org
+which allows you to generate client and server certificates for
+free.
+
+Following are the steps you need to take to create a CAcert.org
+account, generate a certificate and install it in your favorite
+browser.
+
+* Open http://cacert.org in your favorite browser
+* Root Certificate link: install both certificates
+* Join (Register an account)
+* Verify your account (check your email inbox!)
+* Log in
+* Client Certificates: New
+* Follow instructions to create the certificate
+* Install the certificate in your browser
+
+You can optionally save the certificate for later use, for example
+to extract the `IssuerID` information as will be detailed later on.
+
+=== Transport configuration
+
+The SSL transport does not request a client certificate by default.
+You need to specify the `{verify, verify_peer}` option when starting
+the listener to enable this behavior.
+
+.Configure a listener for SSL authentication
+
+[source,erlang]
+{ok, _} = ranch:start_listener(my_ssl, 100,
+	ranch_ssl, [
+		{port, SSLPort},
+		{certfile, PathToCertfile},
+		{cacertfile, PathToCACertfile},
+		{verify, verify_peer}
+	],
+	my_protocol, []
+).
+
+In this example we set the required `port` and `certfile`, but also
+the `cacertfile` containing the CACert.org root certificate, and
+the option to request the client certificate.
+
+If you enable the `{verify, verify_peer}` option and the client does
+not have a client certificate configured for your domain, then no
+certificate will be sent. This allows you to use SSL for more than
+just authenticated clients.
+
+=== Authentication
+
+To authenticate users, you must first save the certificate information
+required. If you have your users' certificate files, you can simply
+load the certificate and retrieve the information directly.
+
+.Retrieve the issuer ID from a certificate
+
+[source,erlang]
+----
+certfile_to_issuer_id(Filename) ->
+	{ok, Data} = file:read_file(Filename),
+	[{'Certificate', Cert, not_encrypted}] = public_key:pem_decode(Data),
+	{ok, IssuerID} = public_key:pkix_issuer_id(Cert, self),
+	IssuerID.
+----
+
+The `IssuerID` variable contains both the certificate serial number
+and the certificate issuer stored in a tuple, so this value alone can
+be used to uniquely identify the user certificate. You can save this
+value in a database, a configuration file or any other place where an
+Erlang term can be stored and retrieved.
+
+To retrieve the `IssuerID` from a running connection, you need to first
+retrieve the client certificate and then extract this information from
+it. Ranch does not provide a function to retrieve the client certificate.
+Instead you can use the `ssl:peercert/1` function. Once you have the
+certificate, you can again use the `public_key:pkix_issuer_id/2` to
+extract the `IssuerID` value.
+
+The following function returns the `IssuerID` or `false` if no client
+certificate was found. This snippet is intended to be used from your
+protocol code.
+
+.Retrieve the issuer ID from the certificate for the current connection
+
+[source,erlang]
+----
+socket_to_issuer_id(Socket) ->
+	case ssl:peercert(Socket) of
+		{error, no_peercert} ->
+			false;
+		{ok, Cert} ->
+			{ok, IssuerID} = public_key:pkix_issuer_id(Cert, self),
+			IssuerID
+	end.
+----
+
+You then only need to match the `IssuerID` value to authenticate the
+user.
-- 
cgit v1.2.3

