Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

HPCC-14356 Document Code Signing options #8488

Merged
merged 3 commits into from
Apr 15, 2016
Merged

HPCC-14356 Document Code Signing options #8488

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2031e54
HPCC-14356 Document Code Signing options
Apr 13, 2016
53c8d61
HPCC-14356 Edits based upon review
Apr 14, 2016
6c82b6b
HPCC-14356 Edits based upon review
Apr 15, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
149 changes: 149 additions & 0 deletions docs/ECLProgrammersGuide/PRG_Mods/CodeSign.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,149 @@
<?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, primarily, as a way to ensure that operations
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would have said "among other reasons" rather than "primarily" - it's a protection against errors/incompetence as well as against malicious access.

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Limiting what can be folded IS a new change but it's not directly related to the signing/security change (any more - it was at first until I realized they were really separate issues).

You should probably document the FOLD attribute (on a service or a definition within a service) at the appropriate location in the docs. Link from there to here to indicate that use of SERVICE may be restricted to signed modules.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"FOLD on a service or function definition within it requires additional rights."

This sentence needs removing as it is not true

using the FOLD attribute. FOLD on a service or function definition
within it requires additional rights. 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 declare a SERVICE as FOLDable) to be dependent
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove the words "as foldable" - the restriction is on the use of SERVICE at all (since we need to protect runtime as well as compile time)

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>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that parts of the standard library may not function if embedded c++ and use of external definitions are denied. In general allowsigned is preferred.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence is present on line 73 (below the table)


<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>

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@richardkchapman Here is the sentence

<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>foldextern</emphasis></entry>

<entry>Allow/Deny SERVICE functions using FOLD</entry>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one and the next are combined into one setting (called extern) and there is no need to reference FOLD.

</row>

<row>
<entry><emphasis>extern</emphasis></entry>

<entry>Allow/Deny an external function</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
signing has not been used.</para>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"if the code is unsigned, and the allow-extern setting (see above) is set to deny or allowsigned"


<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>
10 changes: 10 additions & 0 deletions docs/ECLProgrammersGuide/PrGd-Includer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>