<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="properties">
	<title>Security Properties of RCE Features</title>
	<para>
		This section provides a concise overview of the security properties of
		various RCE features, especially those related to network activity,
		security, and information transmission. It is intended to support
		security reviews and decisions before deploying and using RCE in your
		organization. For a general overview of RCE's features and operation,
		please refer to the standard RCE User Guide (available at
		<uri>https://rcenvironment.de/pages/documentation/documentation.html
		</uri>
		for the latest 10.x release) and the RCE Website (
		<uri>https://rcenvironment.de</uri>
		).
	</para>
	<section id="default_network">
		<title>Security Properties of RCE's Default ("LocalNet") Network Connections </title>
		<para> The default or "internal" network connections of RCE (informally called "LocalNet"
			connections) are designed for close collaboration within a working group, and are only
			intended to be used within trusted networks. If you require secure connections across
			the boundaries of trusted networks (especially across the internet), or collaborate with
			external partners, the encrypted and authenticated <link linkend="uplink">SSH
				Uplink</link> connections should be used instead. </para>
		<para> A default RCE installation does <emphasis>not</emphasis> open a network port for these
			connections unless explicitly configured to do so. </para>
		<para> For a general overview of RCE's default network approach, please refer to the standard RCE
			User Guide (available at
				<uri>https://rcenvironment.de/pages/documentation/documentation.html</uri>  for the
			latest release). </para>
		<para> If RCE is configured to accept incoming network connections, the port number(s) to be used
			can be freely chosen within the range permitted by the operating system. As RCE should
			never be run with elevated privileges (SYSTEM, root, or equivalent), this typically
			limits RCE to ports 1024 and above.</para>
		<para> Incoming connections can be restricted to certain IPv4 addresses. However, these filters
			are static, so this feature is only useful for either restricting connections to
			localhost for local multi-instance setups, or setting up networks between few, static,
			and long-living nodes. Both setups are fairly untypical, but may still be of use in
			certain situations. </para>
		
		<!-- TODO describe which features can be remotely accessed via the default network -->
		<!-- TODO describe the relation to the the tool authorization system -->
	</section>
	<section id="ssh_server_port">
		<title>Security Properties of RCE's SSH Server Port</title>
		<para> RCE offers a built-in SSH server port, which is disabled by default: An RCE installation
			does not open a port for accepting SSH connections unless explicitly configured to do
			so. This port is provided using the Java library Apache SSHD (
				<uri>https://mina.apache.org/sshd-project/</uri> ). We regularily review this and
			other related libraries for security updates, and issue new RCE releases when
			necessary.</para>
		<para> If RCE's SSH server port is enabled, the port number may be
			freely chosen.
		</para>
		<para> The accounts used to log into this SSH port are completely
			independent of system accounts; RCE provides its own account
			management.
		</para>
		<para> Account passwords are never saved in plaintext. For login
			verification, only salted BCrypt hashes are stored. SSH key files are
			supported.
		</para>
		<para> For each SSH account, a single authorization role is selected,
			which defines which actions are permitted for this account (e.g.
			workflow monitoring).
		</para>
		<para> These SSH accounts, each with its assigned role and its
			password hash or SSH public key string, are stored in a JSON file
			within the instance's "profile" directory The location of this
			profile directory can be customized.
		</para>
		<para> Accounts can be added or removed by using a provided text mode
			UI, or by manually inserting or deleting entries in the JSON file.
		</para>
		<para> Connecting to RCE's SSH port does not create or allow any TCP
			port forwardings; this feature of standard SSH is disabled.
		</para>
		<para> Each RCE instance automatically creates its own SSH server key
			pair once the SSH port is enabled. The key data is stored in the RCE
			instance's profile directory.
		</para>
		<para> Client-side strict host key checking is disabled, and a warning
			is logged when the server-side key has changed. As the SSH login only
			provides a first line of security, with the actual service security
			provided by the RCE authorization system, even a successful MITM
			attack would not have a significant impact. Additionally, without
			access to the real login credentials, an attacker would have to
			perform successful MITM attacks on all incoming connections to the
			relay server, effectively replacing it completely. Such a scenario is
			highly unlikely, especially because even on success, such an attack
			would not impact the security of the service authorization system
			itself (as noted above).
		</para>
		<para> RCE's SSH port supports three modes of operation: <itemizedlist>
				<listitem>
					<para> a custom command shell for RCE administration commands; Unlike standard
						SSH, this feature <emphasis>never</emphasis> provides a direct system shell.
					</para>
				</listitem>
				<listitem>
					<para> the deprecated "SSH Remote Access" feature (to be replaced in RCE 11.0);
					</para>
				</listitem>
				<listitem>
					<para> the new "SSH Uplink" feature (released as experimental feature in RCE
						10.0) </para>
				</listitem>
			</itemizedlist> The latter SSH Uplink feature is the recommended mode for offering tools
			as services to users outside of your organization. Unlike "SSH Remote Access", this mode
			was specifically designed for this purpose. Further, a special SSH authorization role is
			provided to restrict SSH accounts to using this mode exclusively. Notably, this also
			completely disables access to the interactive RCE command shell. </para>
	</section>
	<section id="uplink"><title>Security Properties of RCE's Uplink Feature</title>
		<para> This protocol was specifically designed to allow different
			organizations to provide tool execution services to each other. As
			this naturally involves creating network connections over the
			boundaries of organization's networks, security is the top priority
			of its design and implementation. For a general overview of its
			network approach, please see the "administration" section below.
		</para>
		<para> From an administrator's point of view, the main novelty compared to the older "SSH Remote
			Access" feature is that it is designed to connect different organizations over a shared
			"relay" server that can be placed outside the organization's internal network. This
			eliminates the need to open any incoming network ports in the organization's firewalls.
			Connections are only established from the internal network to the outside (e.g. the
			internet), but are never required in the opposite direction. </para>
		<para> It is of course also possible to use this feature completely
			inside the organization's network, for example for securely providing
			tool execution services between different departments.
		</para>
		<para> Although the current implementation is built on top of the SSH protocol, the actual Uplink
			protocol is not tied to it. SSH is used as the default transport mechanism as it
			provides well-tested encryption and login authorization. Technically, this mechanism
			could be replaced by any other that provides similar features. For example, the Uplink
			protocol could be expanded/adapted to support TLS connections, which would provide
			support for CA-based server certificates. At this time, however, there are no specific
			plans to implement this. Please contact us at <email>rce@dlr.de</email> if this feature
			would be relevant for you.</para>
		<!-- TODO outline what data is sent as part of the protocol, and where it is transmitted to -->
		<!-- TODO describe the interaction with RCE's Tool Integration -->
		<!-- TODO describe the interaction with local/default networks, especially regarding tool forwarding --> 
	</section>
	<section id="tool_integration">
		<title>Security Properties of RCE's Tool Integration</title>
		<para> For general information about RCE's Tool Integration concepts
			and configuration, please refer to the RCE User Guide (available here
			for the latest 10.x release).
		</para>
		<para> From a security perspective, the service-providing side of Tool
			Integration consists of a dedicated user (typically an administrator
			or engineer familiar with the tool) defining a static script that
			controls the tool's invocation. Typical tasks in this script are
			custom input pre-processing or conversion, invoking one or more
			command-line tools, and assembling the final (external) data output.
		</para>
		<para> All inputs and outputs of the service representing the tool is
			explicitly defined as part of the Tool Integration setup. Inputs and
			outputs are standardized to data types like Integer, Float, String,
			File, Directory, Vector, Matrix, or Table.
		</para>
		<para> Beyond input data and (optionally) tool properties, the caller
			of the tool has no means of influencing the tool's execution.
		</para>
		<para> The tool script is executed by passing it to <code>bash</code> on Linux or <code>cmd</code>
			on Windows. (To reiterate: This script is <emphasis>static</emphasis>, and always
			defined by a dedicated user on the <emphasis>providing</emphasis> side,
				<emphasis>never</emphasis> by the caller.) However, RCE has no general control over
			the operations that the administrator/tool integrator performs within that script.
			Safely handling the data that is received via configured properties or the tool's input
			data channels lies in the responsibility of the script author. </para>
		<para>As part of the tool script editor, RCE offers some support for preventing typical
			pitfalls in this area. For example, property strings are automatically double-quoted
			when they are inserted into the editor. Also, certain known-unsafe string contents are
			disallowed to be inserted into script code; when these are received by the tool, the
			tool execution is aborted with an error message.</para>
		<!-- TODO describe tool properties, tool inputs, and how they are accessed from within the script in more detail. -->
		<para> The only data that is implicitly published from a tool's execution is the standard and
			error output of the executing tools, as well as execution time data. If this is
			undesired, standard shell/batch features can typically be used to suppress this
			output.</para>
	</section>
	<section id="tool_authorization">
		<title>Security Properties of RCE's Tool Authorization System</title>
		<para> Tools can be assigned to any set of authorization groups, which
			makes them accessible to any user that is a member of that group.
		</para>
		<para> This assignment is defined on the machine where this tool is
			"integrated" (ie, where it is defined to be actually run; see the
			"Tool Integration" section in the RCE User Guide for details).
		</para>
		<para> There is no central authority for group membership. This is an
			intentional design decision to keep the authorization system flexible
			and lightweight.
		</para>
		<para> This decentralized approach has, among other things, the
			benefit of removing administrative overhead when setting up groups
			between different organizations, for example in the typical use case
			of a research project with partners from different organizations.
		</para>
		<para> Each group membership is defined by access to a secret 256 bit
			key. From a user's perspective, this key works like a password
			required to access a specific group. These group keys are imported
			into RCE instances as text strings, after which they are available on
			this instance until they are removed.
		</para>
		<para> The text snippets used to give users access to a certain group
			should be transported in a secure way, for example via an intranet
			page with access control.
		</para>
		<para> Users can create any number of authorization groups using their
			RCE clients.
		</para>
		<para> Due to the decentralized nature of the authorization groups,
			there is no global password change mechanism, or a central way of
			revoking group memberships. If this is a concern, periodic group
			rotation should be used. This can be realized, for example, by using
			an intranet page with organization-specific access control where the
			current group access codes are posted.
		</para>
		<para>
			The group keys that were created or imported into an RCE instance are
			stored in an encrypted form using the Secure Storage implementation
			of the Eclipse platform (
			<uri>https://www.eclipse.org/</uri>
			). Each user's secure RCE data is encrypted with a random 256 bit
			master key that is stored in the user's home directory. This way,
			even if a user accidentally shares his/her whole RCE profile
			directory to a public location, nobody else can gain access to the
			stored group keys.
		</para>
		<para> RCE provides console commands for listing all active
			authorization groups and their assignments, which can be used for
			automated auditing.
		</para>
	</section>
</chapter>
