Merge pull request #8488 from JamesDeFabia/14356CodeSigning

HPCC-14356 Document Code Signing options

Reviewed-By: Richard Chapman <rchapman@hpccsystems.com>

docs/ECLLanguageReference/ECLR_mods/ExtrSvcs-ExternalServicesImpl.xml

@@ -30,6 +30,10 @@
 
   <programlisting>Extern "C" _declspec(dllexport) unsigned _cdecl Countchars(const unsigned len, const char *string)</programlisting>
 
+  <para><emphasis role="bold">Note</emphasis>: The use of an external SERVICE
+  may be restricted to signed modules. See Code Signing in the ECL
+  Programmer's Guide.</para>
+
   <sect2 id="DLL_Initialization">
     <title>.SO Initialization</title>
 

docs/ECLProgrammersGuide/PRG_Mods/CodeSign.xml

@@ -0,0 +1,147 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<sect1 id="code-signing">
+  <title><emphasis role="strong">Code Signing, Embedded languages, and
+  Security</emphasis></title>
+
+  <para>Versions of HPCC Systems<superscript>®</superscript> platform prior to
+  6.0.0 have always allowed some control over which operations were permitted
+  in ECL code. This was done, among other reasons, as a way to ensure that
+  operations like PIPE or embedded C++ could not be used to circumvent access
+  controls on files by reading them directly from the operating system.</para>
+
+  <para>Version 6.0.0 (and above) has two features to provide more flexibility
+  over the control of these operations.</para>
+
+  <itemizedlist>
+    <listitem>
+      <para>We now limit which SERVICE functions are called at compile time
+      using the FOLD attribute. Typically, for security reasons , FOLD should
+      only be enabled in signed modules.</para>
+    </listitem>
+
+    <listitem>
+      <para>You can configure the access rights (which control the ability to
+      use PIPE, embed C++, or restrict the use of a SERVICE) to be dependent
+      on the code being signed. This means that we can provide signed code in
+      the ECL Standard Library that makes use of these features, without
+      opening them up for anyone to call anything.</para>
+    </listitem>
+  </itemizedlist>
+
+  <sect2 id="ECLCCOptions">
+    <title>ECLCC Configuration Settings</title>
+
+    <para>In Configuration Manager, the ECLCC Server component has a tab named
+    <emphasis role="bold">Options</emphasis>. This tab allows you to enter
+    name value pairs for permissions to execute various types of embedded code
+    or plug-ins.</para>
+
+    <para><emphasis role="bold">Name</emphasis></para>
+
+    <para><informaltable colsep="1" frame="all" rowsep="1">
+        <tgroup cols="2">
+          <colspec colwidth="75.80pt" />
+
+          <colspec />
+
+          <tbody>
+            <row>
+              <entry><emphasis>-allow</emphasis></entry>
+
+              <entry>Allow the option specified.</entry>
+            </row>
+
+            <row>
+              <entry><emphasis>-deny</emphasis></entry>
+
+              <entry>Deny the option specified.</entry>
+            </row>
+
+            <row>
+              <entry><emphasis>-allowsigned</emphasis></entry>
+
+              <entry>Allow the option specified if the code has been signed
+              and the key is present.</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </informaltable></para>
+
+    <para>Note: Parts of the Standard Library may not function if the use of
+    C++ and external definitions is denied. In general, <emphasis
+    role="bold">allowsigned</emphasis> is preferred.</para>
+
+    <para><emphasis role="bold">Cluster</emphasis></para>
+
+    <para>Specify the cluster for which this rule applies.</para>
+
+    <para><emphasis role="bold">Value</emphasis></para>
+
+    <informaltable colsep="1" frame="all" rowsep="1">
+      <tgroup cols="2">
+        <colspec colwidth="75.80pt" />
+
+        <colspec />
+
+        <tbody>
+          <row>
+            <entry><emphasis>cpp</emphasis></entry>
+
+            <entry>Allow/Deny C++ and other embedded languages. For languages
+            other than C++ and Cassandra, an optional plug-in must also be
+            installed</entry>
+          </row>
+
+          <row>
+            <entry><emphasis>pipe</emphasis></entry>
+
+            <entry>Allow/Deny using external applications using the PIPE
+            command.</entry>
+          </row>
+
+          <row>
+            <entry><emphasis>extern</emphasis></entry>
+
+            <entry>Allow/Deny an external function (SERVICE)</entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </informaltable>
+
+    <para></para>
+  </sect2>
+
+  <sect2 id="codesigning">
+    <title>Code Signing</title>
+
+    <para>Code signing is similar to the way that emails can be signed to
+    prove that they are from who they say they are and they have not been
+    tampered with, using the standard gpg package.</para>
+
+    <para>A file that has been signed will have an attached signature
+    containing a cryptographic hash of the file contents with the signer’s
+    private key. Anyone in possession of the signer’s public key can then
+    verify that the signature is valid and that the content is
+    unchanged.</para>
+
+    <para>We have signed the SERVICE definitions provided by the ECL standard
+    plug-ins and included the public key in the HPCC platform installation.
+    Code that tries to use service definitions that are signed will continue
+    to work as before but, code that tries to call arbitrary library functions
+    using user-supplied SERVICE definitions will give compile errors, if the
+    code is unsigned, and the extern setting (see above) is set to deny or
+    allowsigned.</para>
+
+    <para>System administrators can install additional keys on the ECLCC
+    Server machine, so if you want to use your own service definitions, they
+    can be signed using a key that has been installed in this way:</para>
+
+    <para><programlisting>gpg --output &lt;signed-ecl&gt; --default-key &lt;key-id&gt; --clearsign &lt;ecl-file-to-sign&gt;</programlisting></para>
+
+    <para>Using this method, a trusted person can sign code to indicate that
+    it is acceptable for untrusted people to use, without allowing the
+    untrusted people to execute arbitrary code.</para>
+  </sect2>
+</sect1>

docs/ECLProgrammersGuide/PrGd-Includer.xml

@@ -177,4 +177,14 @@
                 xpointer="element(/1)"
                 xmlns:xi="http://www.w3.org/2001/XInclude" />
   </chapter>
+
+  <chapter>
+    <title>Embedded Languages and Data stores</title>
+
+    <xi:include href="ECLProgrammersGuide/PRG_Mods/CodeSign.xml"
+                xpointer="element(/1)"
+                xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+    <para />
+  </chapter>
 </book>