diff options
Diffstat (limited to 'lib/crypto/doc')
| -rw-r--r-- | lib/crypto/doc/src/Makefile | 1 | ||||
| -rw-r--r-- | lib/crypto/doc/src/crypto.xml | 296 | ||||
| -rw-r--r-- | lib/crypto/doc/src/engine_load.xml | 31 | ||||
| -rw-r--r-- | lib/crypto/doc/src/notes.xml | 63 |
4 files changed, 350 insertions, 41 deletions
diff --git a/lib/crypto/doc/src/Makefile b/lib/crypto/doc/src/Makefile index aa987d2b39..2148062e78 100644 --- a/lib/crypto/doc/src/Makefile +++ b/lib/crypto/doc/src/Makefile @@ -89,6 +89,7 @@ debug opt valgrind: clean clean_docs clean_tex: rm -rf $(HTMLDIR)/* + rm -rf $(XMLDIR) rm -f $(MAN3DIR)/* rm -f $(MAN6DIR)/* rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml index 42e411a0e3..4289bd4a64 100644 --- a/lib/crypto/doc/src/crypto.xml +++ b/lib/crypto/doc/src/crypto.xml @@ -110,6 +110,9 @@ <code>ecdh_params() = ec_named_curve() | ec_explicit_curve()</code> + <code>ed_named_curves_ecdh() -> x448 | x25519</code> + <p>Note that the curves are only supported if the underlying OpenSSL has support for them.</p> + <code>ec_explicit_curve() = {ec_field(), Prime :: key_value(), Point :: key_value(), Order :: integer(), CoFactor :: none | integer()} </code> @@ -143,7 +146,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> @@ -155,12 +158,13 @@ <p>The key's password </p> - <code>stream_cipher() = rc4 | aes_ctr </code> + <code>stream_cipher() = rc4 | aes_ctr | chacha20 </code> <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> + <p>Note that the actual supported algorithms depends on the underlying crypto library.</p> <code>stream_key() = aes_key() | rc4_key() </code> @@ -189,13 +193,16 @@ <code>rsa_sign_padding() = rsa_pkcs1_padding | rsa_pkcs1_pss_padding</code> - <code> hash_algorithms() = md5 | ripemd160 | sha | sha224 | sha256 | sha384 | sha512 </code> <p>md4 is also supported for hash_init/1 and hash/2. + <code> hash_algorithms() = md5 | ripemd160 | sha | sha224 | sha256 | sha384 | sha512 | + sha3_224 | sha3_256 | sha3_384 | sha3_512 </code> + <p>md4 is also supported for hash_init/1 and hash/2. Note that both md4 and md5 are recommended only for compatibility with existing applications. + Note that the actual supported hash_algorithms depends on the underlying crypto library. </p> <code> cipher_algorithms() = aes_cbc | aes_cfb8 | aes_cfb128 | aes_ctr | aes_gcm | - aes_ige256 | blowfish_cbc | blowfish_cfb64 | chacha20_poly1305 | des_cbc | + aes_ige256 | blowfish_cbc | blowfish_cfb64 | chacha20 | chacha20_poly1305 | des_cbc | des_cfb | des3_cbc | des3_cfb | des_ede3 | rc2_cbc | rc4 </code> - <code> mac_algorithms() = hmac | cmac</code> + <code> mac_algorithms() = hmac | cmac | poly1305</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. @@ -306,7 +313,7 @@ <v> Type = dh | ecdh | srp </v> <v>OthersPublicKey = dh_public() | ecdh_public() | srp_public() </v> <v>MyKey = dh_private() | ecdh_private() | {srp_public(),srp_private()}</v> - <v>Params = dh_params() | ecdh_params() | SrpUserParams | SrpHostParams</v> + <v>Params = dh_params() | ecdh_params() | ed_named_curves_ecdh() | SrpUserParams | SrpHostParams</v> <v>SrpUserParams = {user, [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom() | [Scrambler:binary()]]} </v> <v>SrpHostParams = {host, [Verifier::binary(), Prime::binary(), Version::atom() | [Scrambler::binary]]} </v> <v>SharedSecret = binary()</v> @@ -336,7 +343,7 @@ <fsummary>Generates a public key of type <c>Type</c></fsummary> <type> <v> Type = dh | ecdh | rsa | srp </v> - <v>Params = dh_params() | ecdh_params() | RsaParams | SrpUserParams | SrpHostParams </v> + <v>Params = dh_params() | ecdh_params() | ed_named_curves_ecdh()| RsaParams | SrpUserParams | SrpHostParams </v> <v>RsaParams = {ModulusSizeInBits::integer(), PublicExponent::key_value()}</v> <v>SrpUserParams = {user, [Generator::binary(), Prime::binary(), Version::atom()]}</v> <v>SrpHostParams = {host, [Verifier::binary(), Generator::binary(), Prime::binary(), Version::atom()]}</v> @@ -598,6 +605,20 @@ </func> <func> + <name>poly1305(Key, Data) -> Mac</name> + <fsummary></fsummary> + <type> + <v>Key = iodata()</v> + <v>Data = iodata()</v> + <v>Mac = binary()</v> + </type> + <desc> + <p>Computes a POLY1305 message authentication code (<c>Mac</c>) from <c>Data</c> using + <c>Key</c> as the authentication key.</p> + </desc> + </func> + + <func> <name>private_decrypt(Type, CipherText, PrivateKey, Padding) -> PlainText</name> <fsummary>Decrypts CipherText using the private Key.</fsummary> <type> @@ -629,7 +650,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> @@ -958,7 +979,7 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[</pre> <name>stream_init(Type, Key, IVec) -> State</name> <fsummary></fsummary> <type> - <v>Type = aes_ctr </v> + <v>Type = aes_ctr | chacha20</v> <v>State = opaque() </v> <v>Key = iodata()</v> <v>IVec = binary()</v> @@ -1075,8 +1096,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 +1113,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 +1141,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 +1150,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 +1164,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 +1185,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 +1212,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 +1220,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 +1235,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 +1244,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(<<"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 @@ <<"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(<<"MD5">>, + <<"/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(<<"MD5">>). + ok</code> + </section> + + + + <section> <title>List all engines currently loaded</title> <code> 5> crypto:engine_list(). diff --git a/lib/crypto/doc/src/notes.xml b/lib/crypto/doc/src/notes.xml index 2e48b48d67..9207d09821 100644 --- a/lib/crypto/doc/src/notes.xml +++ b/lib/crypto/doc/src/notes.xml @@ -31,6 +31,53 @@ </header> <p>This document describes the changes made to the Crypto application.</p> +<section><title>Crypto 4.3.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Update the crypto engine functions to handle multiple + loads of an engine. </p> <p><c>engine_load/3/4</c> is + updated so it doesn't add the engine ID to OpenSSLs + internal list of engines which makes it possible to run + the engine_load more than once if it doesn't contain + global data.</p> <p>Added <c>ensure_engine_loaded/2/3</c> + which guarantees that the engine just is loaded once and + the following calls just returns a reference to it. This + is done by add the ID to the internal OpenSSL list and + check if it is already registered when the function is + called.</p> <p>Added <c>ensure_engine_unloaded/1/2</c> to + unload engines loaded with ensure_engine_loaded.</p> + <p>Then some more utility functions are added.</p> + <p><c>engine_add/1</c>, adds the engine to OpenSSL + internal list</p> <p><c>engine_remove/1</c>, remove the + engine from OpenSSL internal list</p> + <p><c>engine_get_id/1</c>, fetch the engines id</p> + <p><c>engine_get_name/1</c>, fetch the engine name</p> + <p> + Own Id: OTP-15233</p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 4.3.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Fixed a node crash in <c>crypto:compute_key(ecdh, + ...)</c> when passing a wrongly typed Others + argument.</p> + <p> + Own Id: OTP-15194 Aux Id: ERL-673 </p> + </item> + </list> + </section> + +</section> + <section><title>Crypto 4.3</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -78,6 +125,22 @@ </section> +<section><title>Crypto 4.2.2.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Fixed a node crash in <c>crypto:compute_key(ecdh, + ...)</c> when passing a wrongly typed Others + argument.</p> + <p> + Own Id: OTP-15194 Aux Id: ERL-673 </p> + </item> + </list> + </section> + +</section> + <section><title>Crypto 4.2.2</title> <section><title>Fixed Bugs and Malfunctions</title> |