crypto: Engine stored keys doc

4 files changed, 132 insertions, 2 deletions

diff --git a/lib/crypto/doc/src/Makefile b/lib/crypto/doc/src/Makefile
index a902779383..aa987d2b39 100644
--- a/lib/crypto/doc/src/Makefile
+++ b/lib/crypto/doc/src/Makefile
@@ -39,7 +39,7 @@ XML_REF3_FILES = crypto.xml
 XML_REF6_FILES = crypto_app.xml
 
 XML_PART_FILES = usersguide.xml
-XML_CHAPTER_FILES = notes.xml licenses.xml fips.xml engine_load.xml
+XML_CHAPTER_FILES = notes.xml licenses.xml fips.xml engine_load.xml engine_keys.xml
 
 BOOK_FILES = book.xml
 
diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml
index 8e2d33c928..dbc42812a8 100644
--- a/lib/crypto/doc/src/crypto.xml
+++ b/lib/crypto/doc/src/crypto.xml
@@ -136,11 +136,12 @@
     See also <seealso marker="#supports-0">crypto:supports/0</seealso>
     </p>
 
+    <marker id="engine_key_ref_type"/>
     <code>engine_key_ref() = #{engine   := engine_ref(),
                                key_id   := key_id(),
                                password => password()}</code>
 
-    <code>engine_key_ref() = term()</code>
+    <code>engine_ref() = term()</code>
     <p>The result of a call to <seealso marker="#engine_load-3">engine_load/3</seealso>.
     </p>
 
diff --git a/lib/crypto/doc/src/engine_keys.xml b/lib/crypto/doc/src/engine_keys.xml
new file mode 100644
index 0000000000..64d1e6c2a3
--- /dev/null
+++ b/lib/crypto/doc/src/engine_keys.xml
@@ -0,0 +1,128 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2017</year><year>2017</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    </legalnotice>
+    <title>Engine Stored Keys</title>
+    <prepared>Hans Nilsson</prepared>
+    <date>2017-11-10</date>
+    <file>engine_keys.xml</file>
+  </header>
+  <p>
+    <marker id="engine_key"></marker>
+    This chapter describes the support in the crypto application for using public and private keys stored in encryption engines.
+  </p>
+
+  <section>
+    <title>Background</title>
+    <p>
+      <url href="https://www.openssl.org/">OpenSSL</url> exposes an Engine API, which makes 
+      it possible to plug in alternative implementations for some of the cryptographic
+      operations implemented by OpenSSL.
+      See the chapter <seealso marker="crypto:engine_load#engine_load">Engine Load</seealso>
+      for details and how to load an Engine.
+    </p>
+    <p>
+      In addition to provide alternative cryptographic implementations, an engine could provide a storage for
+      private or public keys. Such a storage could be made safer than the normal file system. Such techniques are not 
+      described in this User's Guide.  Here we concentrate on how to use private or public keys stored in
+      such an engine.
+    </p>
+    <p>
+      The storage engine must call <c>ENGINE_set_load_privkey_function</c> and <c>ENGINE_set_load_pubkey_function</c>.
+      See the OpenSSL cryptolib's <url href="https://www.openssl.org/docs/manpages.html">manpages</url>.
+    </p>
+    <p>
+      OTP/Crypto requires that the user provides two or three items of information about the key. The application used
+      by the user is usually on a higher level, for example <seealso marker="ssl:ssl_app#application">SSL</seealso>. If using
+      the crypto application directly, it is required that:
+    </p>
+    <list>
+      <item>an Engine is loaded, see the chapter on <seealso marker="crypto:engine_load#engine_load">Engine Load</seealso>
+      or the <seealso marker="crypto:crypto#engine_load-3">Reference Manual</seealso>
+      </item>
+      <item>a reference to a key in the Engine is available. This should be an Erlang string or binary and depends
+      on the Engine loaded
+      </item>
+      <item>an Erlang map is constructed with the Engine reference, the key reference and possibly a key passphrase if
+      needed by the Engine. See the <seealso marker="crypto:crypto#engine_key_ref_type">Reference Manual</seealso> for
+      details of the map.
+      </item>
+    </list>
+  </section>
+
+  <section>
+    <title>Use Cases</title>
+    <section>
+      <title>Sign with an engine stored private key</title>
+      <p>
+	This example shows how to construct a key reference that is used in a sign operation.
+	The actual key is stored in the engine that is loaded at prompt 1.
+      </p>
+      <code>
+1> {ok, EngineRef} = crypto:engine_load(....).
+...
+{ok,#Ref&lt;0.2399045421.3028942852.173962>}
+2> PrivKey = #{engine => EngineRef,
+               key_id => "id of the private key in Engine"}.
+...
+3> Signature = crypto:sign(rsa, sha, &lt;&lt;"The message">>, PrivKey).
+&lt;&lt;65,6,125,254,54,233,84,77,83,63,168,28,169,214,121,76,
+  207,177,124,183,156,185,160,243,36,79,125,230,231,...>>
+      </code>
+    </section>
+
+    <section>
+      <title>Verify with an engine stored public key</title>
+      <p>
+	Here the signature and message in the last example is verifyed using the public key.
+	The public key is stored in an engine, only to exemplify that it is possible. The public
+	key could of course be handled openly as usual.
+      </p>
+      <code>
+4> PublicKey = #{engine => EngineRef,
+                 key_id => "id of the public key in Engine"}.
+...
+5> crypto:verify(rsa, sha, &lt;&lt;"The message">>, Signature, PublicKey).
+true
+6> 
+      </code>
+    </section>
+
+    <section>
+      <title>Using a password protected private key</title>
+      <p>
+	The same example as the first sign example, except that a password protects the key down in the Engine.
+      </p>
+      <code>
+6> PrivKeyPwd = #{engine => EngineRef,
+                  key_id => "id of the pwd protected private key in Engine",
+		  password => "password"}.
+...
+7> crypto:sign(rsa, sha, &lt;&lt;"The message">>, PrivKeyPwd).
+&lt;&lt;140,80,168,101,234,211,146,183,231,190,160,82,85,163,
+  175,106,77,241,141,120,72,149,181,181,194,154,175,76,
+  223,...>>
+8> 
+      </code>
+
+    </section>
+
+  </section>
+</chapter>
diff --git a/lib/crypto/doc/src/usersguide.xml b/lib/crypto/doc/src/usersguide.xml
index f637a1db79..e2ba1fe160 100644
--- a/lib/crypto/doc/src/usersguide.xml
+++ b/lib/crypto/doc/src/usersguide.xml
@@ -49,4 +49,5 @@
   <xi:include href="licenses.xml"/>
   <xi:include href="fips.xml"/>
   <xi:include href="engine_load.xml"/>
+  <xi:include href="engine_keys.xml"/>
 </part>