From b78b6b3472511c7e39d5c91b0449a59e0f361dcf Mon Sep 17 00:00:00 2001
From: David Terei <davidterei@gmail.com>
Date: Fri, 9 Nov 2012 16:33:36 -0800
Subject: add note about compilation safety to safe haskell docs

---
 docs/users_guide/safe_haskell.xml | 52 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

(limited to 'docs')

diff --git a/docs/users_guide/safe_haskell.xml b/docs/users_guide/safe_haskell.xml
index dc07b89bb8..8b777bbed2 100644
--- a/docs/users_guide/safe_haskell.xml
+++ b/docs/users_guide/safe_haskell.xml
@@ -44,6 +44,16 @@
   </itemizedlist>
   </para>
 
+  <para>
+  Safe Haskell, however, <emphasis>does not offer</emphasis> compilation
+  safety. During compilation time it is possible for arbitrary processes to be
+  launched, using for example the <link linkend="pre-processor">custom
+    pre-processor</link> flag. This can be manipulated to either compromise a
+  users system at compilation time, or to modify the source code just before
+  compilation to try to alter set Safe Haskell flags. This is discussed further
+  in section <xref linkend="safe-compilation"/>.
+  </para>
+
   <sect2 id="safe-use-cases">
     <title>Uses of Safe Haskell</title>
     <indexterm><primary>safe haskell uses</primary></indexterm>
@@ -722,6 +732,48 @@
     </variablelist>
   </sect2>
 
+  <sect2 id="safe-compilation">
+    <title>Safe Compilation</title>
+    <indexterm><primary>safe compilation</primary></indexterm>
+
+    <para>
+    GHC includes a variety of flags that allow arbitrary processes to be run at
+    compilation time. One such example is the <link
+      linkend="pre-processor">custom pre-processor</link> flag. Another is the
+    ability of Template Haskell to execute Haskell code at compilation time,
+    including IO actions. Safe Haskell <emphasis>does not address this
+      danger</emphasis> (although, Template Haskell is a disallowed feature).
+    </para>
+
+    <para>
+    Due to this, it is suggested that when compiling untrusted source code that
+    has had no manual inspection done, the following precautions be taken:
+    <itemizedlist>
+      <listitem>Compile in a sandbox, such as a chroot or similar container
+        technology. Or simply as a user with very reduced system
+        access.</listitem>
+      <listitem>Compile untrusted code with the <option>-XSafe</option> flag
+        being specified on the command line. This will ensure that modifications
+        to the source being compiled can't disable the use of the Safe Language
+        as the command line flag takes precedence over a source level
+        pragma.</listitem>
+      <listitem>Ensure that all untrusted code is imported as a
+        <link linkend="safe-imports">safe import</link><emphasis> and</emphasis>
+        that the <link linkend="safe-package-trust"><option>-fpackage-trust</option></link>
+        flag is used with packages from untrusted sources being marked as
+        untrusted.</listitem>
+    </itemizedlist>
+    </para>
+
+    <para>
+    There is a more detailed discussion of the issues involved in compilation
+    safety and some potential solutions on the <ulink
+      url="http://hackage.haskell.org/trac/ghc/wiki/SafeHaskell/SafeCompilation">GHC
+      Wiki</ulink>.
+    </para>
+
+  </sect2>
+
 </sect1>
 
 <!-- Emacs stuff:
-- 
cgit v1.2.1