From 5b51f9d9875750f27f2fa8a75f22e0fcb9a6bec0 Mon Sep 17 00:00:00 2001
From: Lars Thorsen <lars@erlang.org>
Date: Wed, 15 Aug 2018 12:26:44 +0200
Subject: Updated the engine load functionality

- engine_load/3/4 can be called multiple times for same engine
  if it allows it (eg doesn't contain global data)
- ensure_engine_loaded/2/3 is new functions that guarantees that the engine
  is just loaded once by adding it to OpenSSL internal engine list and check that
  before loading.
- ensure_engine_unloaded/1/2 is new functions that is used to unload engines loaded with
  ensure_engine_loaded (remove it from OpenSSL internal engine list and then unload).
- new utility functions engine_by_id/1, engine_add/1, engine_remove/1,
  engine_get_id/1 and engine_get_name/1
---
 lib/crypto/doc/src/engine_load.xml | 31 +++++++++++++++++++++++++------
 1 file changed, 25 insertions(+), 6 deletions(-)

(limited to 'lib/crypto/doc/src/engine_load.xml')

diff --git a/lib/crypto/doc/src/engine_load.xml b/lib/crypto/doc/src/engine_load.xml
index e5c3f5d561..3d0aa0c32a 100644
--- a/lib/crypto/doc/src/engine_load.xml
+++ b/lib/crypto/doc/src/engine_load.xml
@@ -42,6 +42,9 @@
       operations. The hardware implementation usually offers improved performance over its
       software-based counterpart, which is known as cryptographic acceleration.
     </p>
+    <note>
+      <p>The file name requirement on the engine dynamic library can differ between SSL versions.</p>
+    </note>
   </section>
 
   <section>
@@ -54,9 +57,6 @@
       <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>
@@ -72,9 +72,6 @@
                                        &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>
@@ -99,6 +96,28 @@ engine_method_pkey_meths, engine_method_pkey_asn1_meths].
  {ok, #Ref}</code>
     </section>
 
+    <section>
+      <title>Load with the ensure loaded function</title>
+      <p>
+	This function makes sure the engine is loaded just once and the ID is added to the internal
+	engine list of OpenSSL. The following calls to the function will check if the ID is loaded
+	and then just get a new reference to the engine.
+      </p>
+      <code>
+ 5> {ok, Engine} = crypto:ensure_engine_loaded(&lt;&lt;"MD5">>,
+                                               &lt;&lt;"/some/path/otp_test_engine.so">>).
+ {ok, #Ref}</code>
+      <p>
+	To unload it use crypto:ensure_engine_unloaded/1 which removes the ID from the internal list
+	before unloading the engine.
+      </p>
+      <code>
+ 6> crypto:ensure_engine_unloaded(&lt;&lt;"MD5">>).
+ ok</code>
+    </section>
+
+
+
     <section>
       <title>List all engines currently loaded</title>
       <code>
-- 
cgit v1.2.3