aboutsummaryrefslogtreecommitdiffstats
path: root/lib/crypto/doc
diff options
context:
space:
mode:
authorLars Thorsen <[email protected]>2018-08-15 12:26:44 +0200
committerLars Thorsen <[email protected]>2018-08-23 07:26:32 +0200
commitb7d7cc2c3ce83c1206c3ba98a2b90958f4c50693 (patch)
treef66c2ff9fcf2d29ec469e602cec68194b2da3a6b /lib/crypto/doc
parente37eec271ad08a6689e358071eeb800674cde938 (diff)
downloadotp-b7d7cc2c3ce83c1206c3ba98a2b90958f4c50693.tar.gz
otp-b7d7cc2c3ce83c1206c3ba98a2b90958f4c50693.tar.bz2
otp-b7d7cc2c3ce83c1206c3ba98a2b90958f4c50693.zip
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 Conflicts: lib/crypto/c_src/crypto.c
Diffstat (limited to 'lib/crypto/doc')
-rw-r--r--lib/crypto/doc/src/crypto.xml261
-rw-r--r--lib/crypto/doc/src/engine_load.xml31
2 files changed, 258 insertions, 34 deletions
diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml
index 42e411a0e3..e6147ddffc 100644
--- a/lib/crypto/doc/src/crypto.xml
+++ b/lib/crypto/doc/src/crypto.xml
@@ -143,7 +143,7 @@
password => password()}</code>
<code>engine_ref() = term()</code>
- <p>The result of a call to <seealso marker="#engine_load-3">engine_load/3</seealso>.
+ <p>The result of a call to for example <seealso marker="#engine_load-3">engine_load/3</seealso>.
</p>
<code>key_id() = string() | binary()</code>
@@ -629,7 +629,7 @@
<desc>
<p>Fetches the corresponding public key from a private key stored in an Engine.
The key must be of the type indicated by the Type parameter.
- </p>
+ </p>
</desc>
</func>
@@ -1075,8 +1075,8 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[</pre>
<p>
Returns a list of all possible engine methods.
</p>
- <p>
- May throw exception notsup in case there is
+ <p>
+ May throw exception notsup in case there is
no engine support in the underlying OpenSSL implementation.
</p>
<p>
@@ -1092,18 +1092,18 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[</pre>
<type>
<v>EngineId = unicode:chardata()</v>
<v>PreCmds, PostCmds = [{unicode:chardata(), unicode:chardata()}]</v>
- <v>Result = {ok, Engine::term()} | {error, Reason::term()}</v>
+ <v>Result = {ok, Engine::engine_ref()} | {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
+ 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
+ It may also throw the exception notsup in case there is
no engine support in the underlying OpenSSL implementation.
</p>
<p>
@@ -1120,7 +1120,7 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[</pre>
<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>
+ <v>Result = {ok, Engine::engine_ref()} | {error, Reason::term()}</v>
</type>
<desc>
<p>
@@ -1129,7 +1129,7 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[</pre>
</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
+ It may also throw the exception notsup in case there is
no engine support in the underlying OpenSSL implementation.
</p>
<p>
@@ -1143,17 +1143,17 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[</pre>
<name>engine_unload(Engine) -> Result</name>
<fsummary>Dynamical load an encryption engine</fsummary>
<type>
- <v>Engine = term()</v>
+ <v>Engine = engine_ref()</v>
<v>Result = ok | {error, Reason::term()}</v>
</type>
<desc>
<p>
- Unloads the OpenSSL engine given by <c>EngineId</c>.
+ Unloads the OpenSSL engine given by <c>Engine</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
+ It may also throw the exception notsup in case there is
no engine support in the underlying OpenSSL implementation.
</p>
<p>
@@ -1164,19 +1164,24 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[</pre>
</func>
<func>
- <name>engine_list() -> Result</name>
- <fsummary>List the known engine ids</fsummary>
+ <name>engine_by_id(EngineId) -> Result</name>
+ <fsummary>Get a reference to an already loaded engine</fsummary>
<type>
- <v>Result = [EngineId::unicode:chardata()]</v>
+ <v>EngineID = unicode:chardata()engine_ref()</v>
+ <v>Result = {ok, Engine::engine_ref()} | {error, Reason::term()}</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
+ Get a reference to an already loaded engine with <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>
+ See also the chapter <seealso marker="crypto:engine_load#engine_load">Engine Load</seealso>
in the User's Guide.
</p>
</desc>
@@ -1186,7 +1191,7 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[</pre>
<name>engine_ctrl_cmd_string(Engine, CmdName, CmdArg) -> Result</name>
<fsummary>Sends ctrl commands to an OpenSSL engine</fsummary>
<type>
- <v>Engine = term()</v>
+ <v>Engine = engine_ref()</v>
<v>CmdName = unicode:chardata()</v>
<v>CmdArg = unicode:chardata()</v>
<v>Result = ok | {error, Reason::term()}</v>
@@ -1194,12 +1199,12 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[</pre>
<desc>
<p>
Sends ctrl commands to the OpenSSL engine given by <c>Engine</c>.
- This function is the same as calling <c>engine_ctrl_cmd_string/4</c> with
+ This function is the same as calling <c>engine_ctrl_cmd_string/4</c> with
<c>Optional</c> set to <c>false</c>.
</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
+ It may also throw the exception notsup in case there is
no engine support in the underlying OpenSSL implementation.
</p>
</desc>
@@ -1209,7 +1214,7 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[</pre>
<name>engine_ctrl_cmd_string(Engine, CmdName, CmdArg, Optional) -> Result</name>
<fsummary>Sends ctrl commands to an OpenSSL engine</fsummary>
<type>
- <v>Engine = term()</v>
+ <v>Engine = engine_ref()</v>
<v>CmdName = unicode:chardata()</v>
<v>CmdArg = unicode:chardata()</v>
<v>Optional = boolean()</v>
@@ -1218,18 +1223,218 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[</pre>
<desc>
<p>
Sends ctrl commands to the OpenSSL engine given by <c>Engine</c>.
- <c>Optional</c> is a boolean argument that can relax the semantics of the function.
- If set to <c>true</c> it will only return failure if the ENGINE supported the given
- command name but failed while executing it, if the ENGINE doesn't support the command
- name it will simply return success without doing anything. In this case we assume
+ <c>Optional</c> is a boolean argument that can relax the semantics of the function.
+ If set to <c>true</c> it will only return failure if the ENGINE supported the given
+ command name but failed while executing it, if the ENGINE doesn't support the command
+ name it will simply return success without doing anything. In this case we assume
the user is only supplying commands specific to the given ENGINE so we set this to
<c>false</c>.
</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
+ It may also throw the exception notsup in case there is
+ no engine support in the underlying OpenSSL implementation.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>engine_add(Engine) -> Result</name>
+ <fsummary>Add engine to OpenSSL internal list</fsummary>
+ <type>
+ <v>Engine = engine_ref()</v>
+ <v>Result = ok | {error, Reason::term()}</v>
+ </type>
+ <desc>
+ <p>Add the engine to OpenSSL's internal list.</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>
+ </desc>
+ </func>
+
+ <func>
+ <name>engine_remove(Engine) -> Result</name>
+ <fsummary>Remove engine to OpenSSL internal list</fsummary>
+ <type>
+ <v>Engine = engine_ref()</v>
+ <v>Result = ok | {error, Reason::term()}</v>
+ </type>
+ <desc>
+ <p>Remove the engine from OpenSSL's internal list.</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>
+ </desc>
+ </func>
+
+ <func>
+ <name>engine_get_id(Engine) -> EngineId</name>
+ <fsummary>Fetch engine ID</fsummary>
+ <type>
+ <v>Engine = engine_ref()</v>
+ <v>EngineId = unicode:chardata()</v>
+ </type>
+ <desc>
+ <p>Return the ID for the engine, or an empty binary if there is no id set.</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>
+ </desc>
+ </func>
+
+ <func>
+ <name>engine_get_name(Engine) -> EngineName</name>
+ <fsummary>Fetch engine name</fsummary>
+ <type>
+ <v>Engine = engine_ref()</v>
+ <v>EngineName = unicode:chardata()</v>
+ </type>
+ <desc>
+ <p>Return the name (eg a description) for the engine, or an empty binary if there is no name set.</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>
+ </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>
+ <p>
+ May throw exception notsup in case engine functionality is not supported by the underlying
+ OpenSSL implementation.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>ensure_engine_loaded(EngineId, LibPath) -> Result</name>
+ <fsummary>Ensure encryption engine just loaded once</fsummary>
+ <type>
+ <v>EngineId = unicode:chardata()</v>
+ <v>LibPath = unicode:chardata()</v>
+ <v>Result = {ok, Engine::engine_ref()} | {error, Reason::term()}</v>
+ </type>
+ <desc>
+ <p>
+ Loads the OpenSSL engine given by <c>EngineId</c> and the path to the dynamic library
+ implementing the engine. This function is the same as calling <c>ensure_engine_loaded/3</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>ensure_engine_loaded(EngineId, LibPath, EngineMethods) -> Result</name>
+ <fsummary>Ensure encryption engine just loaded once</fsummary>
+ <type>
+ <v>EngineId = unicode:chardata()</v>
+ <v>LibPath = unicode:chardata()</v>
+ <v>EngineMethods = [engine_method_type()]</v>
+ <v>Result = {ok, Engine::engine_ref()} | {error, Reason::term()}</v>
+ </type>
+ <desc>
+ <p>
+ Loads the OpenSSL engine given by <c>EngineId</c> and the path to the dynamic library
+ implementing the engine. This function differs from the normal engine_load in that sense it
+ also add the engine id to the internal list in OpenSSL. Then in the following calls to the function
+ it just fetch the reference to the engine instead of loading it again.
+ 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>ensure_engine_unloaded(Engine) -> Result</name>
+ <fsummary>Unload an engine loaded with the ensure function</fsummary>
+ <type>
+ <v>Engine = engine_ref()</v>
+ <v>Result = ok | {error, Reason::term()}</v>
+ </type>
+ <desc>
+ <p>
+ Unloads an engine loaded with the <c>ensure_engine_loaded</c> function.
+ It both removes the label from the OpenSSL internal engine list and unloads the engine.
+ This function is the same as calling <c>ensure_engine_unloaded/2</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 unloaded.
+ </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>ensure_engine_unloaded(Engine, EngineMethods) -> Result</name>
+ <fsummary>Unload an engine loaded with the ensure function</fsummary>
+ <type>
+ <v>Engine = engine_ref()</v>
+ <v>EngineMethods = [engine_method_type()]</v>
+ <v>Result = ok | {error, Reason::term()}</v>
+ </type>
+ <desc>
+ <p>
+ Unloads an engine loaded with the <c>ensure_engine_loaded</c> function.
+ It both removes the label from the OpenSSL internal engine list and unloads the engine.
+ An error tuple is returned if the engine can't be unloaded.
+ </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>
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>
@@ -100,6 +97,28 @@ engine_method_pkey_meths, engine_method_pkey_asn1_meths].
</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>
5> crypto:engine_list().