From 01c644bbfbc3ac88d45ce5f77a35de9e82067009 Mon Sep 17 00:00:00 2001
From: Ingela Anderton Andin <ingela@erlang.org>
Date: Fri, 15 Dec 2017 14:59:03 +0100
Subject: ssl: Add engine use case to Users Guide

---
 lib/ssl/doc/src/using_ssl.xml | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

(limited to 'lib')

diff --git a/lib/ssl/doc/src/using_ssl.xml b/lib/ssl/doc/src/using_ssl.xml
index f84cd6e391..61918a346d 100644
--- a/lib/ssl/doc/src/using_ssl.xml
+++ b/lib/ssl/doc/src/using_ssl.xml
@@ -152,4 +152,41 @@ Shell got {ssl,{sslsocket,[...]},"foo"}
 ok</code>
     </section>
   </section>
+
+   <section>
+    <title>Using an Engine Stored Key</title>
+    
+    <p>Erlang ssl application is able to use private keys provided
+    by OpenSSL engines using the following mechanism:</p>
+    
+    <code type="erl">1> ssl:start().
+ok</code>
+
+    <p>Load a crypto engine, should be done once per engine used. For example
+    dynamically load the engine called <c>MyEngine</c>:
+    </p>
+    <code type="erl">2> {ok, EngineRef} =
+crypto:engine_load(&lt;&lt;"dynamic">>,
+                   [{&lt;&lt;"SO_PATH">>, "/tmp/user/engines/MyEngine"},&lt;&lt;"LOAD">>],[]).
+{ok,#Ref&lt;0.2399045421.3028942852.173962>}
+    </code>
+    
+    <p>Create a map with the engine information and the algorithm used by the engine:</p>
+    <code type="erl">3> PrivKey =
+ #{algorithm => rsa,
+   engine => EngineRef,
+   key_id => "id of the private key in Engine"}.
+    </code>
+    <p>Use the map in the ssl key option:</p>
+    <code type="erl">4> {ok, SSLSocket} =
+ssl:connect("localhost", 9999,
+            [{cacertfile, "cacerts.pem"},
+             {certfile, "cert.pem"},
+             {key, PrivKey}], infinity).
+    </code>
+
+    <p>See also <seealso marker="crypto:engine_load#engine_load"> crypto documentation</seealso> </p>
+    
+     </section>      
+  
  </chapter>
-- 
cgit v1.2.3