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