From 223b6a3f4d53f7d5b5d0b9756c1eec4a5b8c862b Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Fri, 10 Nov 2017 16:19:36 +0100 Subject: crypto: Engine stored keys doc --- lib/crypto/doc/src/Makefile | 2 +- lib/crypto/doc/src/crypto.xml | 3 +- lib/crypto/doc/src/engine_keys.xml | 128 +++++++++++++++++++++++++++++++++++++ lib/crypto/doc/src/usersguide.xml | 1 + 4 files changed, 132 insertions(+), 2 deletions(-) create mode 100644 lib/crypto/doc/src/engine_keys.xml (limited to 'lib/crypto/doc') diff --git a/lib/crypto/doc/src/Makefile b/lib/crypto/doc/src/Makefile index a902779383..aa987d2b39 100644 --- a/lib/crypto/doc/src/Makefile +++ b/lib/crypto/doc/src/Makefile @@ -39,7 +39,7 @@ XML_REF3_FILES = crypto.xml XML_REF6_FILES = crypto_app.xml XML_PART_FILES = usersguide.xml -XML_CHAPTER_FILES = notes.xml licenses.xml fips.xml engine_load.xml +XML_CHAPTER_FILES = notes.xml licenses.xml fips.xml engine_load.xml engine_keys.xml BOOK_FILES = book.xml diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml index 8e2d33c928..dbc42812a8 100644 --- a/lib/crypto/doc/src/crypto.xml +++ b/lib/crypto/doc/src/crypto.xml @@ -136,11 +136,12 @@ See also crypto:supports/0

+ engine_key_ref() = #{engine := engine_ref(), key_id := key_id(), password => password()} - engine_key_ref() = term() + engine_ref() = term()

The result of a call to engine_load/3.

diff --git a/lib/crypto/doc/src/engine_keys.xml b/lib/crypto/doc/src/engine_keys.xml new file mode 100644 index 0000000000..64d1e6c2a3 --- /dev/null +++ b/lib/crypto/doc/src/engine_keys.xml @@ -0,0 +1,128 @@ + + + + +
+ + 20172017 + Ericsson AB. All Rights Reserved. + + + 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. + + Engine Stored Keys + Hans Nilsson + 2017-11-10 + engine_keys.xml +
+

+ + This chapter describes the support in the crypto application for using public and private keys stored in encryption engines. +

+ +
+ Background +

+ OpenSSL exposes an Engine API, which makes + it possible to plug in alternative implementations for some of the cryptographic + operations implemented by OpenSSL. + See the chapter Engine Load + for details and how to load an Engine. +

+

+ In addition to provide alternative cryptographic implementations, an engine could provide a storage for + private or public keys. Such a storage could be made safer than the normal file system. Such techniques are not + described in this User's Guide. Here we concentrate on how to use private or public keys stored in + such an engine. +

+

+ The storage engine must call ENGINE_set_load_privkey_function and ENGINE_set_load_pubkey_function. + See the OpenSSL cryptolib's manpages. +

+

+ OTP/Crypto requires that the user provides two or three items of information about the key. The application used + by the user is usually on a higher level, for example SSL. If using + the crypto application directly, it is required that: +

+ + an Engine is loaded, see the chapter on Engine Load + or the Reference Manual + + a reference to a key in the Engine is available. This should be an Erlang string or binary and depends + on the Engine loaded + + an Erlang map is constructed with the Engine reference, the key reference and possibly a key passphrase if + needed by the Engine. See the Reference Manual for + details of the map. + + +
+ +
+ Use Cases +
+ Sign with an engine stored private key +

+ This example shows how to construct a key reference that is used in a sign operation. + The actual key is stored in the engine that is loaded at prompt 1. +

+ +1> {ok, EngineRef} = crypto:engine_load(....). +... +{ok,#Ref<0.2399045421.3028942852.173962>} +2> PrivKey = #{engine => EngineRef, + key_id => "id of the private key in Engine"}. +... +3> Signature = crypto:sign(rsa, sha, <<"The message">>, PrivKey). +<<65,6,125,254,54,233,84,77,83,63,168,28,169,214,121,76, + 207,177,124,183,156,185,160,243,36,79,125,230,231,...>> + +
+ +
+ Verify with an engine stored public key +

+ Here the signature and message in the last example is verifyed using the public key. + The public key is stored in an engine, only to exemplify that it is possible. The public + key could of course be handled openly as usual. +

+ +4> PublicKey = #{engine => EngineRef, + key_id => "id of the public key in Engine"}. +... +5> crypto:verify(rsa, sha, <<"The message">>, Signature, PublicKey). +true +6> + +
+ +
+ Using a password protected private key +

+ The same example as the first sign example, except that a password protects the key down in the Engine. +

+ +6> PrivKeyPwd = #{engine => EngineRef, + key_id => "id of the pwd protected private key in Engine", + password => "password"}. +... +7> crypto:sign(rsa, sha, <<"The message">>, PrivKeyPwd). +<<140,80,168,101,234,211,146,183,231,190,160,82,85,163, + 175,106,77,241,141,120,72,149,181,181,194,154,175,76, + 223,...>> +8> + + +
+ +
+ diff --git a/lib/crypto/doc/src/usersguide.xml b/lib/crypto/doc/src/usersguide.xml index f637a1db79..e2ba1fe160 100644 --- a/lib/crypto/doc/src/usersguide.xml +++ b/lib/crypto/doc/src/usersguide.xml @@ -49,4 +49,5 @@ + -- cgit v1.2.3 From e0f51124fb37cc6287bc710a537b92d3a179cc72 Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Tue, 21 Nov 2017 14:33:54 +0100 Subject: crypto: Changes after review --- lib/crypto/doc/src/engine_keys.xml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'lib/crypto/doc') diff --git a/lib/crypto/doc/src/engine_keys.xml b/lib/crypto/doc/src/engine_keys.xml index 64d1e6c2a3..38714fed8a 100644 --- a/lib/crypto/doc/src/engine_keys.xml +++ b/lib/crypto/doc/src/engine_keys.xml @@ -39,8 +39,8 @@ for details and how to load an Engine.

- In addition to provide alternative cryptographic implementations, an engine could provide a storage for - private or public keys. Such a storage could be made safer than the normal file system. Such techniques are not + An engine could among other tasks provide a storage for + private or public keys. Such a storage could be made safer than the normal file system. Thoose techniques are not described in this User's Guide. Here we concentrate on how to use private or public keys stored in such an engine.

@@ -50,7 +50,8 @@

OTP/Crypto requires that the user provides two or three items of information about the key. The application used - by the user is usually on a higher level, for example SSL. If using + by the user is usually on a higher level, for example in + SSL. If using the crypto application directly, it is required that:

-- cgit v1.2.3