From 992831c7a516b5183c2af06260829d41aa45267c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Thu, 9 Sep 2021 12:15:32 +0200
Subject: Ranch 2.1.0

---
 docs/en/ranch/1.5/guide/ssl_auth.asciidoc | 120 ------------------------------
 1 file changed, 120 deletions(-)
 delete mode 100644 docs/en/ranch/1.5/guide/ssl_auth.asciidoc

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

diff --git a/docs/en/ranch/1.5/guide/ssl_auth.asciidoc b/docs/en/ranch/1.5/guide/ssl_auth.asciidoc
deleted file mode 100644
index de16107a..00000000
--- a/docs/en/ranch/1.5/guide/ssl_auth.asciidoc
+++ /dev/null
@@ -1,120 +0,0 @@
-== 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,
-	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

