File 4296-Clarify-documentation-of-cookie-handling.p... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 4296-Clarify-documentation-of-cookie-handling.patch of Package erlang

From e3bbd5d97857e9c83c61785276fb85267316a2ea Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Wed, 11 Aug 2021 12:43:13 +0200
Subject: [PATCH 6/9] Clarify documentation of cookie handling

---
 system/doc/reference_manual/distributed.xml | 87 ++++++++++++++++-----
 1 file changed, 69 insertions(+), 18 deletions(-)

diff --git a/system/doc/reference_manual/distributed.xml b/system/doc/reference_manual/distributed.xml
index 832a87c2d4..0ef5d3edc3 100644
--- a/system/doc/reference_manual/distributed.xml
+++ b/system/doc/reference_manual/distributed.xml
@@ -140,40 +140,91 @@ dilbert@uab</pre>
 
 <section>
 <title>Security</title>
+ <note>
+ 
+ "Security" here does not mean
+ cryptographically secure, but rather
+ security against accidental misuse,
+ such as preventing a node from connecting
+ to a cluster with which it is not intended to communicate.
+ 
+ 
+ Furthermore, the communication between nodes
+ is per default in clear text.
+ If you need strong security, please see
+ <seeguide marker="ssl:ssl_distribution">
+ Using TLS for Erlang Distribution
+ </seeguide>
+ in the SSL application's User's Guide.
+ 
+ 
+ Also, the default random cookie mentioned
+ in the following text is not very unpredictable.
+ A better one can be generated using primitives
+ in the <c>crypto</c> module, though this still does not make
+ the inital handshake cryptographically secure.
+ And inter-node communication is still in clear text.
+ 
+ </note>
 Authentication determines which nodes are allowed to communicate
 with each other. In a network of different Erlang nodes, it is
- built into the system at the lowest possible level. Each node has
- its own magic cookie, which is an Erlang atom.
- When a node tries to connect to another node, the magic cookies
- are compared. If they do not match, the connected node rejects
- the connection.
- At start-up, a node has a random atom assigned as its magic
- cookie and the cookie of other nodes is assumed to be
+ built into the system at the lowest possible level.
+ All nodes use a magic cookie,
+ which is an Erlang atom, when connecting another node.
+ During the connection setup, after node names have been exchanged,
+ the magic cookies the nodes present to each other are compared.
+ If they do not match, the connection is rejected.
+ The cookies themselves are never transferred,
+ instead they are compared using hashed challenges,
+ although not in a cryptographically secure manner.
+ At start-up, a node has a random atom assigned as its default
+ magic cookie and the cookie of other nodes is assumed to be
 <c>nocookie</c>. The first action of the Erlang network
 authentication server (<c>auth</c>) is then to read a file named
 <c>$HOME/.erlang.cookie</c>. If the file does not exist, it is
 created. The UNIX permissions mode of the file is set to octal
- 400 (read-only by user) and its contents are a random string. An
+ 400 (read-only by user) and its content is a random string. An
 atom <c>Cookie</c> is created from the contents of the file and
 the cookie of the local node is set to this using
- <c>erlang:set_cookie(node(), Cookie)</c>. This also makes
- the local node assume that all other nodes have the same cookie
- <c>Cookie</c>.
+ <c>erlang:set_cookie(node(), Cookie)</c>. This is
+ the default cookie that the local node will use towards
+ all other nodes.
 Thus, groups of users with identical cookie files get Erlang
- nodes that can communicate freely and without interference from
- the magic cookie system. Users who want to run nodes on separate
- file systems must make certain that their cookie files are
- identical on the different file systems.
+ nodes that can communicate freely since they have the same
+ magic cookie. Users who want to run nodes
+ where the cookie files are on different file systems
+ must make certain that their cookie files are identical.
 For a node <c>Node1</c> with magic cookie <c>Cookie</c> to be
- able to connect to, or accept a connection from, another node
- <c>Node2</c> with a different cookie <c>DiffCookie</c>,
+ able to connect to, and to accept a connection from, another node
+ <c>Node2</c> that uses a different cookie <c>DiffCookie</c>,
 the function <c>erlang:set_cookie(Node2, DiffCookie)</c> must
 first be called at <c>Node1</c>. Distributed systems with
- multiple user IDs can be handled in this way.
+ multiple home directories (differing cookie files)
+ can be handled in this way.
+ <note>
+ With this setup <c>Node1</c> and <c>Node2</c> agree
+ on which cookie to use: <c>Node1</c> uses its explicitly
+ configured <c>DiffCookie</c> for <c>Node2</c>,
+ and <c>Node2</c> uses its default cookie <c>DiffCookie</c>.
+ You can also use a <c>DiffCookie</c> that neither
+ <c>Node1</c> nor <c>Node2</c> has as its default cookie,
+ if you also call <c>erlang:set_cookie(Node1, DiffCookie)</c>
+ in <c>Node2</c> before establishing connection
+ Because node names are exchanged during connection setup
+ before cookies are selected, the setup works regardless
+ of which node that initiates the connection
+ Note that to configure <c>Node1</c> to use <c>Node2</c>'s
+ default cookie when communicating with <c>Node2</c>,
+ and vice versa results in a broken configuration
+ (if the cookies are different) because then both nodes
+ use the other node's (differing) cookie.
+ </note>
 The default when a connection is established between two nodes,
 is to immediately connect all other visible nodes as well. This
 way, there is always a fully connected network. If there are
 nodes with different cookies, this method can be inappropriate
+ (since it may not be feasible to configure
+ different cookies for all possible nodes)
 and the command-line flag <c>-connect_all false</c> must be set,
 see the <seecom marker="erts:erl">erl(1)</seecom>
 manual page in ERTS.
-- 
2.31.1

Places

File 4296-Clarify-documentation-of-cookie-handling.patch of Package erlang

Places