From b5d4cb91f80c833795a2d87050c3674bb7aecdc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Tue, 3 Oct 2017 13:39:41 +0200 Subject: Update Hugo, docs --- docs/en/ranch/1.2/guide/ssl_auth/index.html | 309 ++++++++++++++-------------- 1 file changed, 156 insertions(+), 153 deletions(-) (limited to 'docs/en/ranch/1.2/guide/ssl_auth') diff --git a/docs/en/ranch/1.2/guide/ssl_auth/index.html b/docs/en/ranch/1.2/guide/ssl_auth/index.html index 18e94d36..3261ddc4 100644 --- a/docs/en/ranch/1.2/guide/ssl_auth/index.html +++ b/docs/en/ranch/1.2/guide/ssl_auth/index.html @@ -7,7 +7,7 @@ - + Nine Nines: SSL client authentication @@ -67,164 +67,167 @@

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 [CAcert.org](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
-
-
{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
-
-
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
-
-
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.

-
-
+
+

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 [CAcert.org](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
+
+
{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
+
+
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
+
+
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.

+
+
+ + +