From f2bae041d5adce4aed85d5e388ac4464468c51e7 Mon Sep 17 00:00:00 2001 From: Marcin Olszewski Date: Tue, 9 May 2017 14:22:54 +0200 Subject: [PATCH] Addressed comments in review --- docs/SECURE_PLUGIN_COMMUNICATION.md | 39 +++++++++++++++++++++++------ 1 file changed, 32 insertions(+), 7 deletions(-) diff --git a/docs/SECURE_PLUGIN_COMMUNICATION.md b/docs/SECURE_PLUGIN_COMMUNICATION.md index 8982e5b47..3a700f657 100644 --- a/docs/SECURE_PLUGIN_COMMUNICATION.md +++ b/docs/SECURE_PLUGIN_COMMUNICATION.md @@ -19,7 +19,27 @@ limitations under the License. # Secure Plugin Communication -Snap communicates with plugins over gRPC protocol, which in general transfers data in plaintext. + + +- [Secure Plugin Communication](#secure-plugin-communication) + - [Overview](#overview) + - [Usage](#usage) + - [Shortest guide](#shortest-guide) + - [Detailed preparation](#detailed-preparation) + - [Enabling secure communication](#enabling-secure-communication) + - [Using system-installed CA certificates](#using-system-installed-ca-certificates) + - [More information](#more-information) + - [Exclusive security](#exclusive-security) + - [Relation to other functionalities](#relation-to-other-functionalities) + - [TLS setup requirements](#tls-setup-requirements) + - [Obtaining self-signed TLS certificates for tests](#obtaining-self-signed-tls-certificates-for-tests) + - [More information](#more-information-1) + + + +## Overview + +Snap framework communicates with plugins over gRPC protocol, which in general transfers data in plaintext. Snap allows securing communication with plugins by opening TLS channels and using certificates to authenticate plugins and framework. ## Usage @@ -28,23 +48,20 @@ This walkthrough assumes you have downloaded a Snap release as described in [Get ### Shortest guide -Assuming all the test files are available, the following steps will result in secure plugin communication: +Assuming all the test files are available (basing on [test instructions](#obtaining-self-signed-tls-certificates-for-tests)) , the following steps will result in secure plugin communication: ``` snapteld --log-level 1 --plugin-trust 0 --tls-cert /tmp/snaptest-cli.crt --tls-key /tmp/snaptest-cli.key --ca-cert-paths /tmp/snaptest-ca.crt -## (in another terminal) -## Load each plugin snaptel plugin load --plugin-cert /tmp/snaptest-srv.crt --plugin-key /tmp/snaptest-srv.key --plugin-ca-certs /tmp/snaptest-ca.crt plugins/snap-plugin-collector-rand -## Start a sample task snaptel task create -t sample-task.json ``` ### Detailed preparation Starting secure communication requires following steps: -1. Obtain TLS certificate and private key for framework. +1. Obtain X.509 certificate and private key for framework. * Please note that this certificate should allow usage for TLS web client authentication (as specified in RFC 3280) -1. Obtain TLS certificate and private key for each plugin or group of plugins. +1. Obtain X.509 certificate and private key for each plugin or group of plugins. * Please note that this certificate should allow usage for TLS web server authentication (as specified in RFC 3280) 1. Obtain and locate the CA certificates that are necessary to authenticate framework and plugin certificates. @@ -84,6 +101,14 @@ Several modes of operation do not fully support secure communication: * tribe doesn't support secure communication; `snapteld` will refuse to start in tribe mode if configured with secure communication, * plugin and task autodiscovery doesn't support secure communication; `snapteld` will refuse to start with autodiscovery path and secure communication enabled. +### TLS setup requirements + +Snap plugin security is subject to following constraints: +* certificates must be valid for use with following cipher suites: + * TLS_RSA_WITH_AES_128_GCM_SHA256, + * TLS_RSA_WITH_AES_256_GCM_SHA384. +* certificates should allow usage for TLS web client or server authentication, as specified in RFC 3280 (server usage is for plugins). + ### Obtaining self-signed TLS certificates for tests The following intstructions will result in TLS certificate files. These files may be used for manual tests.