<?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>
      An engine could among other tasks provide a storage for
      private or public keys. Such a storage could be made safer than the normal file system. Thoose 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 in
      <seealso marker="ssl:ssl#key_option_def">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>
