aboutsummaryrefslogtreecommitdiffstats
path: root/lib/crypto/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/crypto/doc')
-rw-r--r--lib/crypto/doc/src/Makefile20
-rw-r--r--lib/crypto/doc/src/crypto.xml209
-rw-r--r--lib/crypto/doc/src/engine_load.xml110
-rw-r--r--lib/crypto/doc/src/usersguide.xml6
4 files changed, 303 insertions, 42 deletions
diff --git a/lib/crypto/doc/src/Makefile b/lib/crypto/doc/src/Makefile
index 9c503b8fe0..a902779383 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
@@ -38,13 +38,13 @@ XML_APPLICATION_FILES = ref_man.xml
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_PART_FILES = usersguide.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 5b2c46a004..8e2d33c928 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>
@@ -136,16 +136,33 @@
See also <seealso marker="#supports-0">crypto:supports/0</seealso>
</p>
+ <code>engine_key_ref() = #{engine := engine_ref(),
+ key_id := key_id(),
+ password => password()}</code>
+
+ <code>engine_key_ref() = term()</code>
+ <p>The result of a call to <seealso marker="#engine_load-3">engine_load/3</seealso>.
+ </p>
+
+ <code>key_id() = string() | binary()</code>
+ <p>Identifies the key to be used. The format depends on the loaded engine. It is passed to
+ the <c>ENGINE_load_(private|public)_key</c> functions in libcrypto.
+ </p>
+
+ <code>password() = string() | binary()</code>
+ <p>The key's password
+ </p>
+
<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 +191,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 +282,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 +460,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
@@ -580,7 +601,7 @@
<type>
<v>Type = rsa</v>
<v>CipherText = binary()</v>
- <v>PrivateKey = rsa_private()</v>
+ <v>PrivateKey = rsa_private() | engine_key_ref()</v>
<v>Padding = rsa_pkcs1_padding | rsa_pkcs1_oaep_padding | rsa_no_padding</v>
<v>PlainText = binary()</v>
</type>
@@ -594,7 +615,22 @@
</p>
</desc>
</func>
-
+
+ <func>
+ <name>privkey_to_pubkey(Type, EnginePrivateKeyRef) -> PublicKey</name>
+ <fsummary>Fetches a public key from an Engine stored private key.</fsummary>
+ <type>
+ <v>Type = rsa | dss</v>
+ <v>EnginePrivateKeyRef = engine_key_ref()</v>
+ <v>PublicKey = rsa_public() | dss_public()</v>
+ </type>
+ <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>
+ </desc>
+ </func>
+
<func>
<name>private_encrypt(Type, PlainText, PrivateKey, Padding) -> CipherText</name>
<fsummary>Encrypts PlainText using the private Key.</fsummary>
@@ -605,7 +641,7 @@
than <c>byte_size(N)-11</c> if <c>rsa_pkcs1_padding</c> is
used, and <c>byte_size(N)</c> if <c>rsa_no_padding</c> is
used, where N is public modulus of the RSA key.</d>
- <v>PrivateKey = rsa_private()</v>
+ <v>PrivateKey = rsa_private() | engine_key_ref()</v>
<v>Padding = rsa_pkcs1_padding | rsa_no_padding</v>
<v>CipherText = binary()</v>
</type>
@@ -624,7 +660,7 @@
<type>
<v>Type = rsa</v>
<v>CipherText = binary()</v>
- <v>PublicKey = rsa_public() </v>
+ <v>PublicKey = rsa_public() | engine_key_ref()</v>
<v>Padding = rsa_pkcs1_padding | rsa_no_padding</v>
<v>PlainText = binary()</v>
</type>
@@ -649,7 +685,7 @@
than <c>byte_size(N)-11</c> if <c>rsa_pkcs1_padding</c> is
used, and <c>byte_size(N)</c> if <c>rsa_no_padding</c> is
used, where N is public modulus of the RSA key.</d>
- <v>PublicKey = rsa_public()</v>
+ <v>PublicKey = rsa_public() | engine_key_ref()</v>
<v>Padding = rsa_pkcs1_padding | rsa_pkcs1_oaep_padding | rsa_no_padding</v>
<v>CipherText = binary()</v>
</type>
@@ -702,7 +738,7 @@
signed or it is the hashed value of "cleartext" i.e. the
digest (plaintext).</d>
<v>DigestType = rsa_digest_type() | dss_digest_type() | ecdsa_digest_type()</v>
- <v>Key = rsa_private() | dss_private() | [ecdh_private(),ecdh_params()]</v>
+ <v>Key = rsa_private() | dss_private() | [ecdh_private(),ecdh_params()] | engine_key_ref()</v>
<v>Options = sign_options()</v>
</type>
<desc>
@@ -893,7 +929,7 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[</pre>
or it is the hashed value of "cleartext" i.e. the digest (plaintext).</d>
<v>DigestType = rsa_digest_type() | dss_digest_type() | ecdsa_digest_type()</v>
<v>Signature = binary()</v>
- <v>Key = rsa_public() | dss_public() | [ecdh_public(),ecdh_params()]</v>
+ <v>Key = rsa_public() | dss_public() | [ecdh_public(),ecdh_params()] | engine_key_ref()</v>
<v>Options = sign_options()</v>
</type>
<desc>
@@ -905,6 +941,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 -->
@@ -979,4 +1133,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>
-