Merge branch 'maint'

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 8c30d3d50c..8503f6eabb 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>
@@ -1026,6 +1030,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 -->
@@ -1100,4 +1222,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>
-