From 5b51f9d9875750f27f2fa8a75f22e0fcb9a6bec0 Mon Sep 17 00:00:00 2001 From: Lars Thorsen 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/crypto.xml | 263 +++++++++++++++++++++++++++++++++---- lib/crypto/doc/src/engine_load.xml | 31 ++++- 2 files changed, 259 insertions(+), 35 deletions(-) (limited to 'lib/crypto/doc/src') diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml index 464799b320..8eb414b9bf 100644 --- a/lib/crypto/doc/src/crypto.xml +++ b/lib/crypto/doc/src/crypto.xml @@ -4,7 +4,7 @@
- 19992017 + 19992018 Ericsson AB. All Rights Reserved. @@ -142,7 +142,7 @@ password => password()} engine_ref() = term() -

The result of a call to engine_load/3. +

The result of a call to for example engine_load/3.

key_id() = string() | binary() @@ -628,7 +628,7 @@

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. -

+

@@ -953,8 +953,8 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[

Returns a list of all possible engine methods.

-

- May throw exception notsup in case there is +

+ May throw exception notsup in case there is no engine support in the underlying OpenSSL implementation.

@@ -970,18 +970,18 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ EngineId = unicode:chardata() PreCmds, PostCmds = [{unicode:chardata(), unicode:chardata()}] - Result = {ok, Engine::term()} | {error, Reason::term()} + Result = {ok, Engine::engine_ref()} | {error, Reason::term()}

Loads the OpenSSL engine given by EngineId if it is available and then returns ok and - an engine handle. This function is the same as calling engine_load/4 with - EngineMethods set to a list of all the possible methods. An error tuple is + an engine handle. This function is the same as calling engine_load/4 with + EngineMethods set to a list of all the possible methods. An error tuple is returned if the engine can't be loaded.

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.

@@ -998,7 +998,7 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ EngineId = unicode:chardata() PreCmds, PostCmds = [{unicode:chardata(), unicode:chardata()}] EngineMethods = [engine_method_type()] - Result = {ok, Engine::term()} | {error, Reason::term()} + Result = {ok, Engine::engine_ref()} | {error, Reason::term()}

@@ -1007,7 +1007,7 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[

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.

@@ -1021,17 +1021,17 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ engine_unload(Engine) -> Result Dynamical load an encryption engine - Engine = term() + Engine = engine_ref() Result = ok | {error, Reason::term()}

- Unloads the OpenSSL engine given by EngineId. + Unloads the OpenSSL engine given by Engine. An error tuple is returned if the engine can't be unloaded.

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.

@@ -1042,19 +1042,24 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ - engine_list() -> Result - List the known engine ids + engine_by_id(EngineId) -> Result + Get a reference to an already loaded engine - Result = [EngineId::unicode:chardata()] + EngineID = unicode:chardata()engine_ref() + Result = {ok, Engine::engine_ref()} | {error, Reason::term()} -

List the id's of all engines in OpenSSL's internal list.

- It may also throw the exception notsup in case there is + Get a reference to an already loaded engine with EngineId. + An error tuple is returned if the engine can't be unloaded. +

+

+ 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.

- See also the chapter Engine Load + See also the chapter Engine Load in the User's Guide.

@@ -1064,7 +1069,7 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ engine_ctrl_cmd_string(Engine, CmdName, CmdArg) -> Result Sends ctrl commands to an OpenSSL engine - Engine = term() + Engine = engine_ref() CmdName = unicode:chardata() CmdArg = unicode:chardata() Result = ok | {error, Reason::term()} @@ -1072,12 +1077,12 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[

Sends ctrl commands to the OpenSSL engine given by Engine. - This function is the same as calling engine_ctrl_cmd_string/4 with + This function is the same as calling engine_ctrl_cmd_string/4 with Optional set to false.

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.

@@ -1087,7 +1092,7 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ engine_ctrl_cmd_string(Engine, CmdName, CmdArg, Optional) -> Result Sends ctrl commands to an OpenSSL engine - Engine = term() + Engine = engine_ref() CmdName = unicode:chardata() CmdArg = unicode:chardata() Optional = boolean() @@ -1096,18 +1101,218 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[

Sends ctrl commands to the OpenSSL engine given by Engine. - Optional is a boolean argument that can relax the semantics of the function. - If set to true 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 + Optional is a boolean argument that can relax the semantics of the function. + If set to true 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 false.

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. +

+ + + + + engine_add(Engine) -> Result + Add engine to OpenSSL internal list + + Engine = engine_ref() + Result = ok | {error, Reason::term()} + + +

Add the engine to OpenSSL's internal list.

+

+ 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. +

+ + + + + engine_remove(Engine) -> Result + Remove engine to OpenSSL internal list + + Engine = engine_ref() + Result = ok | {error, Reason::term()} + + +

Remove the engine from OpenSSL's internal list.

+

+ 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. +

+ + + + + engine_get_id(Engine) -> EngineId + Fetch engine ID + + Engine = engine_ref() + EngineId = unicode:chardata() + + +

Return the ID for the engine, or an empty binary if there is no id set.

+

+ 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. +

+ + + + + engine_get_name(Engine) -> EngineName + Fetch engine name + + Engine = engine_ref() + EngineName = unicode:chardata() + + +

Return the name (eg a description) for the engine, or an empty binary if there is no name set.

+

+ 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. +

+ + + + + engine_list() -> Result + List the known engine ids + + Result = [EngineId::unicode:chardata()] + + +

List the id's of all engines in OpenSSL's internal list.

+

+ It may also throw the exception notsup in case there is + no engine support in the underlying OpenSSL implementation. +

+

+ See also the chapter Engine Load + in the User's Guide. +

+

+ May throw exception notsup in case engine functionality is not supported by the underlying + OpenSSL implementation. +

+ + + + + ensure_engine_loaded(EngineId, LibPath) -> Result + Ensure encryption engine just loaded once + + EngineId = unicode:chardata() + LibPath = unicode:chardata() + Result = {ok, Engine::engine_ref()} | {error, Reason::term()} + + +

+ Loads the OpenSSL engine given by EngineId and the path to the dynamic library + implementing the engine. This function is the same as calling ensure_engine_loaded/3 with + EngineMethods set to a list of all the possible methods. An error tuple is + returned if the engine can't be loaded. +

+

+ 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.

+

+ See also the chapter Engine Load + in the User's Guide. +

+ + + + + ensure_engine_loaded(EngineId, LibPath, EngineMethods) -> Result + Ensure encryption engine just loaded once + + EngineId = unicode:chardata() + LibPath = unicode:chardata() + EngineMethods = [engine_method_type()] + Result = {ok, Engine::engine_ref()} | {error, Reason::term()} + + +

+ Loads the OpenSSL engine given by EngineId 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. +

+

+ 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. +

+

+ See also the chapter Engine Load + in the User's Guide. +

+ + + + + ensure_engine_unloaded(Engine) -> Result + Unload an engine loaded with the ensure function + + Engine = engine_ref() + Result = ok | {error, Reason::term()} + + +

+ Unloads an engine loaded with the ensure_engine_loaded function. + It both removes the label from the OpenSSL internal engine list and unloads the engine. + This function is the same as calling ensure_engine_unloaded/2 with + EngineMethods set to a list of all the possible methods. An error tuple is + returned if the engine can't be unloaded. +

+

+ 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. +

+

+ See also the chapter Engine Load + in the User's Guide. +

+ + + + + ensure_engine_unloaded(Engine, EngineMethods) -> Result + Unload an engine loaded with the ensure function + + Engine = engine_ref() + EngineMethods = [engine_method_type()] + Result = ok | {error, Reason::term()} + + +

+ Unloads an engine loaded with the ensure_engine_loaded 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. +

+

+ 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. +

+

+ See also the chapter Engine Load + in the User's Guide. +

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.

+ +

The file name requirement on the engine dynamic library can differ between SSL versions.

+
@@ -54,9 +57,6 @@ 1> {ok, Engine} = crypto:engine_load(<<"otp_test_engine">>, [], []). {ok, #Ref} - -

The file name requirement on the engine dynamic library can differ between SSL versions.

-
@@ -72,9 +72,6 @@ <<"LOAD">>], []). {ok, #Ref} - -

The dynamic engine is not supported in LibreSSL from version 2.2.1

-
@@ -99,6 +96,28 @@ engine_method_pkey_meths, engine_method_pkey_asn1_meths]. {ok, #Ref}
+
+ Load with the ensure loaded function +

+ 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. +

+ + 5> {ok, Engine} = crypto:ensure_engine_loaded(<<"MD5">>, + <<"/some/path/otp_test_engine.so">>). + {ok, #Ref} +

+ To unload it use crypto:ensure_engine_unloaded/1 which removes the ID from the internal list + before unloading the engine. +

+ + 6> crypto:ensure_engine_unloaded(<<"MD5">>). + ok +
+ + +
List all engines currently loaded -- cgit v1.2.3