Big-Data-HPC-Platform/docs/ECLProgrammersGuide/PRG_Mods/CodeSign.xml

<?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>Code Signing, Embedded languages, and Security</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 plugins.</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. If cluster is left
    blank, the restriction applies to all clusters in the environment.</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 plugin 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>

          <row>
            <entry><emphasis>datafile</emphasis></entry>

            <entry>(Valid only for --allowedsigned). This specifies that
            access to data is only allowed if the code has been signed and the
            key is present.</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
    plugins 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>