[crypto] Add support for loading an alternative Engine

Add support to plug in alternative implementations for
some or all of the cryptographic operations supported by
the OpenSSL Engine API.
When configured appropriately, OpenSSL calls the engine's
implementation of these operations instead of its own.

4 files changed, 264 insertions, 35 deletions

diff --git a/lib/crypto/doc/src/Makefile b/lib/crypto/doc/src/Makefile
index 9c503b8fe0..937bb1419f 100644
--- a/lib/crypto/doc/src/Makefile
+++ b/lib/crypto/doc/src/Makefile
@@ -9,11 +9,11 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-# 
+#
 # The Initial Developer of the Original Code is Ericsson Utvecklings AB.
 # Portions created by Ericsson are Copyright 1999, Ericsson Utvecklings
 # AB. All Rights Reserved.''
-# 
+#
 #     $Id$
 #
 include $(ERL_TOP)/make/target.mk
@@ -39,12 +39,12 @@ XML_REF3_FILES = crypto.xml
 XML_REF6_FILES = crypto_app.xml
 
 XML_PART_FILES = release_notes.xml usersguide.xml
-XML_CHAPTER_FILES = notes.xml licenses.xml fips.xml
+XML_CHAPTER_FILES = notes.xml licenses.xml fips.xml engine_load.xml
 
 BOOK_FILES = book.xml
 
 XML_FILES = $(BOOK_FILES) $(XML_APPLICATION_FILES) $(XML_REF3_FILES)  $(XML_REF6_FILES) \
-            $(XML_PART_FILES) $(XML_CHAPTER_FILES) 
+            $(XML_PART_FILES) $(XML_CHAPTER_FILES)
 
 GIF_FILES =
 
@@ -63,9 +63,9 @@ HTML_REF_MAN_FILE = $(HTMLDIR)/index.html
 TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf
 
 # ----------------------------------------------------
-# FLAGS 
+# FLAGS
 # ----------------------------------------------------
-XML_FLAGS += 
+XML_FLAGS +=
 
 # ----------------------------------------------------
 # Targets
@@ -73,7 +73,6 @@ XML_FLAGS +=
 $(HTMLDIR)/%.gif: %.gif
 	$(INSTALL_DATA) $< $@
 
-
 docs: pdf html man
 
 $(TOP_PDF_FILE): $(XML_FILES)
@@ -86,7 +85,7 @@ man: $(MAN3_FILES) $(MAN6_FILES)
 
 gifs: $(GIF_FILES:%=$(HTMLDIR)/%)
 
-debug opt valgrind: 
+debug opt valgrind:
 
 clean clean_docs clean_tex:
 	rm -rf $(HTMLDIR)/*
@@ -97,7 +96,7 @@ clean clean_docs clean_tex:
 
 # ----------------------------------------------------
 # Release Target
-# ---------------------------------------------------- 
+# ----------------------------------------------------
 include $(ERL_TOP)/make/otp_release_targets.mk
 
 release_docs_spec: docs
@@ -114,4 +113,3 @@ release_docs_spec: docs
 
 
 release_spec:
-
diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml
index 5b2c46a004..c0f85945a7 100644
--- a/lib/crypto/doc/src/crypto.xml
+++ b/lib/crypto/doc/src/crypto.xml
@@ -11,7 +11,7 @@
       Licensed under the Apache License, Version 2.0 (the "License");
       you may not use this file except in compliance with the License.
       You may obtain a copy of the License at
- 
+
           http://www.apache.org/licenses/LICENSE-2.0
 
       Unless required by applicable law or agreed to in writing, software
@@ -19,7 +19,6 @@
       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
       See the License for the specific language governing permissions and
       limitations under the License.
-
     </legalnotice>
 
     <title>crypto</title>
@@ -68,11 +67,11 @@
 
  <section>
     <title>DATA TYPES </title>
-    
-    <code>key_value()  = integer() | binary() </code>
+
+    <code>key_value() = integer() | binary() </code>
     <p>Always <c>binary()</c> when used as return value</p>
 
-    <code>rsa_public()  = [key_value()] = [E, N]  </code>
+    <code>rsa_public() = [key_value()] = [E, N]  </code>
     <p> Where E is the public exponent and N is public modulus. </p>
 
     <code>rsa_private() = [key_value()] = [E, N, D] | [E, N, D, P1, P2, E1, E2, C] </code>
@@ -85,7 +84,7 @@
     <code>dss_public() = [key_value()] = [P, Q, G, Y] </code>
     <p>Where P, Q and G are the dss parameters and Y is the public key.</p>
 
-    <code>dss_private() =  [key_value()] = [P, Q, G, X] </code>
+    <code>dss_private() = [key_value()] = [P, Q, G, X] </code>
     <p>Where P, Q and G are the dss parameters and X is the private key.</p>
 
     <code>srp_public() = key_value() </code>
@@ -109,15 +108,16 @@
 
     <code>ecdh_private() = key_value() </code>
 
-    <code>ecdh_params() =  ec_named_curve() | ec_explicit_curve()</code>
+    <code>ecdh_params() = ec_named_curve() | ec_explicit_curve()</code>
 
     <code>ec_explicit_curve() =
-    {ec_field(), Prime :: key_value(), Point :: key_value(), Order :: integer(), CoFactor :: none | integer()} </code>
+    {ec_field(), Prime :: key_value(), Point :: key_value(), Order :: integer(),
+     CoFactor :: none | integer()} </code>
 
     <code>ec_field() = {prime_field, Prime :: integer()} |
     {characteristic_two_field, M :: integer(), Basis :: ec_basis()}</code>
 
-    <code>ec_basis() =  {tpbasis, K :: non_neg_integer()} |
+    <code>ec_basis() = {tpbasis, K :: non_neg_integer()} |
     {ppbasis, K1 :: non_neg_integer(), K2 :: non_neg_integer(), K3 :: non_neg_integer()} |
     onbasis</code>
 
@@ -138,14 +138,14 @@
 
      <code>stream_cipher() = rc4 | aes_ctr </code>
 
-     <code>block_cipher() =  aes_cbc | aes_cfb8 | aes_cfb128 | aes_ige256 | blowfish_cbc |
+     <code>block_cipher() = aes_cbc | aes_cfb8 | aes_cfb128 | aes_ige256 | blowfish_cbc |
      blowfish_cfb64 | des_cbc | des_cfb | des3_cbc | des3_cfb | des_ede3 | rc2_cbc </code>
 
-     <code>aead_cipher() =  aes_gcm | chacha20_poly1305 </code>
+     <code>aead_cipher() = aes_gcm | chacha20_poly1305 </code>
 
-     <code>stream_key() =  aes_key() | rc4_key() </code>
+     <code>stream_key() = aes_key() | rc4_key() </code>
 
-     <code>block_key() =  aes_key() |  blowfish_key() | des_key()| des3_key() </code>
+     <code>block_key() = aes_key() |  blowfish_key() | des_key()| des3_key() </code>
 
      <code>aes_key() = iodata() </code> <p>Key length is 128, 192 or 256 bits</p>
 
@@ -174,13 +174,17 @@
      Note that both md4 and md5 are recommended only for compatibility with existing applications.
      </p>
      <code> cipher_algorithms() = aes_cbc | aes_cfb8 | aes_cfb128 | aes_ctr | aes_gcm |
-     aes_ige256 | blowfish_cbc | blowfish_cfb64 | chacha20_poly1305 | des_cbc | des_cfb |
-     des3_cbc | des3_cfb | des_ede3 | rc2_cbc | rc4 </code>
-     <code> mac_algorithms() =   hmac | cmac</code>
-     <code> public_key_algorithms() =   rsa |dss | ecdsa | dh | ecdh | ec_gf2m</code>
+     aes_ige256 | blowfish_cbc | blowfish_cfb64 | chacha20_poly1305 | des_cbc |
+     des_cfb | des3_cbc | des3_cfb | des_ede3 | rc2_cbc | rc4 </code>
+     <code> mac_algorithms() = hmac | cmac</code>
+     <code> public_key_algorithms() = rsa |dss | ecdsa | dh | ecdh | ec_gf2m</code>
      <p>Note that ec_gf2m is not strictly a public key algorithm, but a restriction on what curves are supported
      with ecdsa and ecdh.
      </p>
+     <code>engine_method_type() = engine_method_rsa | engine_method_dsa | engine_method_dh |
+     engine_method_rand | engine_method_ecdh | engine_method_ecdsa |
+     engine_method_ciphers | engine_method_digests | engine_method_store |
+     engine_method_pkey_meths | engine_method_pkey_asn1_meths</code>
 
  </section>
 
@@ -261,13 +265,13 @@
 	is not supported by the underlying OpenSSL implementation.</p>
       </desc>
     </func>
-    
+
      <func>
       <name>bytes_to_integer(Bin) -> Integer </name>
       <fsummary>Convert binary representation, of an integer, to an Erlang integer.</fsummary>
       <type>
 	<v>Bin = binary() - as returned by crypto functions</v>
-	
+
         <v>Integer = integer() </v>
       </type>
       <desc>
@@ -439,7 +443,7 @@
       </type>
       <desc>
         <p>Updates the HMAC represented by <c>Context</c> using the given <c>Data</c>. <c>Context</c>
-        must have been generated using an HMAC init function (such as 
+        must have been generated using an HMAC init function (such as
         <seealso marker="#hmac_init-2">hmac_init</seealso>). <c>Data</c> can be any length. <c>NewContext</c>
         must be passed into the next call to <c>hmac_update</c>
 	or to one of the functions <seealso marker="#hmac_final-1">hmac_final</seealso> and
@@ -594,7 +598,7 @@
 	</p>
       </desc>
     </func>
-    
+
     <func>
       <name>private_encrypt(Type, PlainText, PrivateKey, Padding) -> CipherText</name>
       <fsummary>Encrypts PlainText using the private Key.</fsummary>
@@ -905,6 +909,124 @@ _FloatValue = rand:uniform().     % [0.0; 1.0[</pre>
       </desc>
     </func>
 
+    <!-- Engine functions -->
+    <func>
+      <name>engine_get_all_methods() -> Result</name>
+      <fsummary>Return list of all possible engine methods</fsummary>
+      <type>
+	<v>Result = [EngineMethod::atom()]</v>
+      </type>
+      <desc>
+	<p>
+	  Returns a list of all possible engine methods.
+	</p>
+	<p>	  
+	  May throw exception notsup in case there is 
+	  no engine support in the underlying OpenSSL implementation.
+	</p>
+	<p>
+	  See also the chapter <seealso marker="crypto:engine_load#engine_load">Engine Load</seealso>
+	  in the User's Guide.
+	</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>engine_load(EngineId, PreCmds, PostCmds) -> Result</name>
+      <fsummary>Dynamical load an encryption engine</fsummary>
+      <type>
+	<v>EngineId = unicode:chardata()</v>
+	<v>PreCmds, PostCmds = [{unicode:chardata(), unicode:chardata()}]</v>
+	<v>Result = {ok, Engine::term()} | {error, Reason::term()}</v>
+      </type>
+      <desc>
+	<p>
+	  Loads the OpenSSL engine given by <c>EngineId</c> if it is available and then returns ok and
+	  an engine handle. This function is the same as calling <c>engine_load/4</c> with 
+	  <c>EngineMethods</c> set to a list of all the possible methods.  An error tuple is 
+	  returned if the engine can't be loaded.
+	</p>
+	<p>
+	  The function throws a badarg if the parameters are in wrong format.
+	  It may also throw the exception notsup in case there is 
+	  no engine support in the underlying OpenSSL implementation.
+	</p>
+	<p>
+	  See also the chapter <seealso marker="crypto:engine_load#engine_load">Engine Load</seealso>
+	  in the User's Guide.
+	</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>engine_load(EngineId, PreCmds, PostCmds, EngineMethods) -> Result</name>
+      <fsummary>Dynamical load an encryption engine</fsummary>
+      <type>
+	<v>EngineId = unicode:chardata()</v>
+	<v>PreCmds, PostCmds = [{unicode:chardata(), unicode:chardata()}]</v>
+	<v>EngineMethods = [engine_method_type()]</v>
+	<v>Result = {ok, Engine::term()} | {error, Reason::term()}</v>
+      </type>
+      <desc>
+	<p>
+	  Loads the OpenSSL engine given by <c>EngineId</c> if it is available and then returns ok and
+	  an engine handle. An error tuple is returned if the engine can't be loaded.
+	</p>
+	<p>
+	  The function throws a badarg if the parameters are in wrong format.
+	  It may also throw the exception notsup in case there is 
+	  no engine support in the underlying OpenSSL implementation.
+	</p>
+	<p>
+	  See also the chapter <seealso marker="crypto:engine_load#engine_load">Engine Load</seealso>
+	  in the User's Guide.
+	</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>engine_unload(Engine) -> Result</name>
+      <fsummary>Dynamical load an encryption engine</fsummary>
+      <type>
+	<v>Engine = term()</v>
+	<v>Result = ok | {error, Reason::term()}</v>
+      </type>
+      <desc>
+	<p>
+	  Unloads the OpenSSL engine given by <c>EngineId</c>.
+	  An error tuple is returned if the engine can't be unloaded.
+	</p>
+	<p>
+	  The function throws a badarg if the parameter is in wrong format.
+	  It may also throw the exception notsup in case there is 
+	  no engine support in the underlying OpenSSL implementation.
+	</p>
+	<p>
+	  See also the chapter <seealso marker="crypto:engine_load#engine_load">Engine Load</seealso>
+	  in the User's Guide.
+	</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>engine_list() -> Result</name>
+      <fsummary>List the known engine ids</fsummary>
+      <type>
+	<v>Result = [EngineId::unicode:chardata()]</v>
+      </type>
+      <desc>
+	<p>List the id's of all engines in OpenSSL's internal list.</p>
+	<p>
+	  It may also throw the exception notsup in case there is 
+	  no engine support in the underlying OpenSSL implementation.
+	</p>
+	<p>
+	  See also the chapter <seealso marker="crypto:engine_load#engine_load">Engine Load</seealso> 
+	  in the User's Guide.
+	</p>
+      </desc>
+    </func>
+
  </funcs>
 
   <!-- Maybe put this in the users guide -->
@@ -979,4 +1101,3 @@ _FloatValue = rand:uniform().     % [0.0; 1.0[</pre>
   <!--   </p> -->
   <!-- </section> -->
 </erlref>
-
diff --git a/lib/crypto/doc/src/engine_load.xml b/lib/crypto/doc/src/engine_load.xml
new file mode 100644
index 0000000000..e5c3f5d561
--- /dev/null
+++ b/lib/crypto/doc/src/engine_load.xml
@@ -0,0 +1,110 @@
+<?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 Load</title>
+    <prepared>Lars Thorsén</prepared>
+    <date>2017-08-22</date>
+    <file>engine_load.xml</file>
+  </header>
+  <p>
+    <marker id="engine_load"></marker>
+    This chapter describes the support for loading encryption engines in the crypto application.
+  </p>
+
+  <section>
+    <title>Background</title>
+    <p>
+      OpenSSL exposes an Engine API, which makes it possible to plug in alternative
+      implementations for some or all of the cryptographic operations implemented by OpenSSL.
+      When configured appropriately, OpenSSL calls the engine's implementation of these
+      operations instead of its own.
+    </p>
+    <p>
+      Typically, OpenSSL engines provide a hardware implementation of specific cryptographic
+      operations. The hardware implementation usually offers improved performance over its
+      software-based counterpart, which is known as cryptographic acceleration.
+    </p>
+  </section>
+
+  <section>
+    <title>Use Cases</title>
+    <section>
+      <title>Dynamically load an engine from default directory</title>
+      <p>
+	If the engine is located in the OpenSSL/LibreSSL installation <c>engines</c> directory.
+      </p>
+      <code>
+1> {ok, Engine} = crypto:engine_load(&lt;&lt;"otp_test_engine">>, [], []).
+ {ok, #Ref}</code>
+       <note>
+	<p>The file name requirement on the engine dynamic library can differ between SSL versions.</p>
+      </note>
+    </section>
+
+    <section>
+      <title>Load an engine with the dynamic engine</title>
+      <p>
+	Load an engine with the help of the dynamic engine by giving the path to the library.
+      </p>
+      <code>
+ 2> {ok, Engine} = crypto:engine_load(&lt;&lt;"dynamic">>,
+                                      [{&lt;&lt;"SO_PATH">>,
+                                        &lt;&lt;"/some/path/otp_test_engine.so">>},
+                                       {&lt;&lt;"ID">>, &lt;&lt;"MD5">>},
+                                       &lt;&lt;"LOAD">>],
+                                      []).
+ {ok, #Ref}</code>
+      <note>
+	<p>The dynamic engine is not supported in LibreSSL from version 2.2.1</p>
+      </note>
+    </section>
+
+    <section>
+      <title>Load an engine and replace some methods</title>
+      <p>
+	Load an engine with the help of the dynamic engine and just
+	replace some engine methods.
+      </p>
+      <code>
+ 3> Methods = crypto:engine_get_all_methods() -- [engine_method_dh,engine_method_rand,
+engine_method_ciphers,engine_method_digests, engine_method_store,
+engine_method_pkey_meths, engine_method_pkey_asn1_meths].
+[engine_method_rsa,engine_method_dsa,
+ engine_method_ecdh,engine_method_ecdsa]
+ 4> {ok, Engine} = crypto:engine_load(&lt;&lt;"dynamic">>,
+                                      [{&lt;&lt;"SO_PATH">>,
+                                        &lt;&lt;"/some/path/otp_test_engine.so">>},
+                                       {&lt;&lt;"ID">>, &lt;&lt;"MD5">>},
+                                       &lt;&lt;"LOAD">>],
+                                      [],
+		                      Methods).
+ {ok, #Ref}</code>
+    </section>
+
+    <section>
+      <title>List all engines currently loaded</title>
+      <code>
+ 5> crypto:engine_list().
+[&lt;&lt;"dynamic">>, &lt;&lt;"MD5">>]</code>
+    </section>
+
+  </section>
+</chapter>
diff --git a/lib/crypto/doc/src/usersguide.xml b/lib/crypto/doc/src/usersguide.xml
index 7971aefff4..f637a1db79 100644
--- a/lib/crypto/doc/src/usersguide.xml
+++ b/lib/crypto/doc/src/usersguide.xml
@@ -11,7 +11,7 @@
       Licensed under the Apache License, Version 2.0 (the "License");
       you may not use this file except in compliance with the License.
       You may obtain a copy of the License at
- 
+
           http://www.apache.org/licenses/LICENSE-2.0
 
       Unless required by applicable law or agreed to in writing, software
@@ -19,7 +19,7 @@
       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
       See the License for the specific language governing permissions and
       limitations under the License.
-    
+
     </legalnotice>
 
     <title>Crypto User's Guide</title>
@@ -48,5 +48,5 @@
   </description>
   <xi:include href="licenses.xml"/>
   <xi:include href="fips.xml"/>
+  <xi:include href="engine_load.xml"/>
 </part>
-