Commit 7e9e48cd authored by dterei's avatar dterei

SafeHaskell: Initial work on documentation

parent 527ca691
......@@ -599,6 +599,26 @@
<entry>dynamic</entry>
<entry>-</entry>
</row>
<row>
<entry><option>-trust</option> <replaceable>P</replaceable></entry>
<entry>Expose package <replaceable>P</replaceable> and set it to be
trusted</entry>
<entry>static/<literal>:set</literal></entry>
<entry>-</entry>
</row>
<row>
<entry><option>-distrust</option> <replaceable>P</replaceable></entry>
<entry>Expose package <replaceable>P</replaceable> and set it to be
distrusted</entry>
<entry>static/<literal>:set</literal></entry>
<entry>-</entry>
</row>
<row>
<entry><option>-distrust-all</option> </entry>
<entry>Distrust all packages by default</entry>
<entry>static/<literal>:set</literal></entry>
<entry>-</entry>
</row>
</tbody>
</tgroup>
</informaltable>
......@@ -1033,6 +1053,30 @@
<entry>dynamic</entry>
<entry><option>-XNoPackageImports</option></entry>
</row>
<row>
<entry><option>-XSafe</option></entry>
<entry>Enable the <link linkend="safe-haskell">Safe Haskell</link> Safe mode.</entry>
<entry>dynamic</entry>
<entry><option>-</option></entry>
</row>
<row>
<entry><option>-XTrustworthy</option></entry>
<entry>Enable the <link linkend="safe-haskell">Safe Haskell</link> Trustworthy mode.</entry>
<entry>dynamic</entry>
<entry><option>-</option></entry>
</row>
<row>
<entry><option>-XSafeLanguage</option></entry>
<entry>Enable the <link linkend="safe-haskell">Safe Haskell</link> Safe Language.</entry>
<entry>dynamic</entry>
<entry><option>-</option></entry>
</row>
<row>
<entry><option>-XSafeImports</option></entry>
<entry>Enable <link linkend="safe-imports-ext">Safe Imports</link>.</entry>
<entry>dynamic</entry>
<entry><option>-</option></entry>
</row>
</tbody>
</tgroup>
</informaltable>
......
......@@ -1897,6 +1897,25 @@ import "network" Network.Socket
another, rendering any package-qualified imports broken.</para>
</sect2>
<sect2 id="safe-imports-ext">
<title>Safe imports</title>
<para>With the <option>-XSafeImports</option> flag, GHC extends
the import declaration syntax to take an optional <literal>safe</literal>
keyword after the <literal>import</literal> keyword. This feature
is part of the Safe Haskell GHC extension. For example:</para>
<programlisting>
import safe qualified Network.Socket as NS
</programlisting>
<para>would import the module <literal>Network.Socket</literal>
with compilation only succeeding if Network.Socket can be
safely imported. For a description of when a import is
considered safe see <xref linkend="safe-haskell"/></para>
</sect2>
<sect2 id="syntax-stolen">
<title>Summary of stolen syntax</title>
......@@ -9411,7 +9430,6 @@ standard behaviour.
</sect1>
<!-- Emacs stuff:
;;; Local Variables: ***
;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
......
......@@ -4,6 +4,7 @@
&glasgowexts;
&parallel;
&safehaskell;
</chapter>
......
......@@ -101,6 +101,13 @@ $ ghc-pkg list
directly.
</para>
<para>Similar to a package's hidden status is a package's trusted
status. A package can be either trusted or not trusted (distrusted).
By default packages are distrusted. This property of a package only
plays a role when compiling code using GHC's Safe Haskell feature
(see <xref linkend="safe-haskell"/>).
</para>
<para>To see which modules are provided by a package use the
<literal>ghc-pkg</literal> command (see <xref linkend="package-management"/>):</para>
......@@ -265,6 +272,53 @@ exposed-modules: Network.BSD,
<literal>-package mypkg-1.2</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-trust</option> <replaceable>P</replaceable>
<indexterm><primary><option>-trust</option></primary>
</indexterm></term>
<listitem>
<para>This option causes the install package <replaceable>P
</replaceable> to be both exposed and trusted by GHC. This
command functions in the in a very similar way to the <option>
-package</option> command but in addition sets the selected
packaged to be trusted by GHC, regardless of the contents of
the package database. (see <xref linkend="safe-haskell"/>).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-distrust</option> <replaceable>P</replaceable>
<indexterm><primary><option>-distrust</option></primary>
</indexterm></term>
<listitem>
<para>This option causes the install package <replaceable>P
</replaceable> to be both exposed and distrusted by GHC. This
command functions in the in a very similar way to the <option>
-package</option> command but in addition sets the selected
packaged to be distrusted by GHC, regardless of the contents of
the package database. (see <xref linkend="safe-haskell"/>).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-distrust-all</option>
<indexterm><primary><option>-distrust-all</option></primary>
</indexterm></term>
<listitem>
<para>Ignore the trusted flag on installed packages, and distrust
them by default. If you use this flag and Safe Haskell then any
packages you require to be trusted (including <literal>base
</literal>) need to be explicitly trusted using <option>-trust
</option> options. This option does not change the exposed/hidden
status of a package, so it isn't equivalent to applying <option>
-distrust</option> to all packages on the system. (see
<xref linkend="safe-haskell"/>).
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
......@@ -623,6 +677,15 @@ haskell98-1.0.1.0
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ghc-pkg check</literal></term>
<listitem>
<para>Check consistency of dependencies in the package
database, and report packages that have missing
dependencies.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ghc-pkg expose <replaceable>P</replaceable></literal></term>
<listitem>
......@@ -632,18 +695,25 @@ haskell98-1.0.1.0
</varlistentry>
<varlistentry>
<term><literal>ghc-pkg check</literal></term>
<term><literal>ghc-pkg hide <replaceable>P</replaceable></literal></term>
<listitem>
<para>Check consistency of dependencies in the package
database, and report packages that have missing
dependencies.</para>
<para>Sets the <literal>exposed</literal> flag for package
<replaceable>P</replaceable> to <literal>False</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ghc-pkg hide <replaceable>P</replaceable></literal></term>
<term><literal>ghc-pkg trust <replaceable>P</replaceable></literal></term>
<listitem>
<para>Sets the <literal>exposed</literal> flag for package
<para>Sets the <literal>trusted</literal> flag for package
<replaceable>P</replaceable> to <literal>True</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ghc-pkg distrust <replaceable>P</replaceable></literal></term>
<listitem>
<para>Sets the <literal>trusted</literal> flag for package
<replaceable>P</replaceable> to <literal>False</literal>.</para>
</listitem>
</varlistentry>
......@@ -1093,6 +1163,7 @@ exposed-modules: System.Posix System.Posix.DynamicLinker.Module
System.Posix.Signals.Exts System.Posix.Semaphore
System.Posix.SharedMem
hidden-modules:
trusted: False
import-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0
library-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0
hs-libraries: HSunix-2.3.1.0
......@@ -1323,6 +1394,16 @@ haddock-html: /usr/share/doc/ghc/html/libraries/unix
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>trusted</literal>
<indexterm><primary><literal>trusted</literal></primary><secondary>package specification</secondary></indexterm>
</term>
<listitem>
<para>(bool) Whether the package is trusted or not.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>import-dirs</literal>
......
<?xml version="1.0" encoding="iso-8859-1"?>
<sect1 id="safe-haskell">
<title>Safe Haskell</title>
Safe Haskell is an extension to the Haskell language supported by GHC, that
provides certain safety guarantees about Haskell code compiled using this
extension. It allows people to build more advance security mechanisms on top
of Haskell and for the safe execution of untrusted Haskell code. Its purpose
isn't to provide a complete secure execution environment for Haskell code but
to give users enough guarantees about the Haskell language to be able to
build such systems. Its design is similar to the safe and unsafe module
system supported by the Modula-3 language.
The design of Safe Haskell covers the following aspects:
<itemizedlist>
<listitem>A <link linkend="safe-language">safe language</link>dialect of
Haskell that provides guarantees about the code. Mainly it allows the
types and module boundaries to be trusted.
</listitem>
<listitem>A new <emphasis>safe import</emphasis> extension that specifies
the module being imported must be trusted.
</listitem>
<listitem>A definition of <emphasis>trust</emphasis> (or safety) and how it
operates, along with ways of defining and changing the trust of modules
and packages.
</listitem>
</itemizedlist>
<sect2 id="safe-language">
<title>Safe Language</title>
The Safe Haskell <emphasis>Safe language</emphasis> guarantees the
following properties:
<itemizedlist>
<listitem><emphasis>Referential transparency.</emphasis> Functions
in the Safe language are deterministic, evaluating them will not
cause any side effects. Functions in the <emphasis>IO</emphasis>
monad are still allowed and behave as usual but any pure function
as according to the functions type is guaranteed to indeed be
pure. This property allows a user of the Safe language to trust
the types of functions.
</listitem>
<listitem><emphasis>Module boundary control.</emphasis> Haskell code
compiled using the Safe language is guaranteed to only access
symbols that are publicly available to it through other modules
export lists. An import part of this is that safe compiled code
is not able to examine or create data values using data constructors
that the module cannot import. If a module M establishes some
invariants through careful use of its export list then code
compiled using the Safe language that imports M is guaranteed to
respect those invariants.
</listitem>
<listitem><emphasis>Semantic consistency.</emphasis> The Safe language
is strictly a subset of Haskell as implemented by GHC. Any expression
that compiles in the safe language has the same meaning as it does
when compiled in normal Haskell. In addtion, in any module that imports
a Safe language module, expressions that compile both with and without
the safe import have the same meaning in both cases. That is, importing
a module using the Safe language cannot change the meaning of existing
code that isn't dependent on that module.
</listitem>
</itemizedlist>
Put simply, these three properties guarantee that you can trust the types
in the Safe language, can trust module export lists are respected
in the Safe language and that code which succesfully compiles in the Safe
language has the same meaning as it normally would.
</sect2>
<sect2 id="safe-imports">
<title>Safe Imports</title>
Safe Haskell enables a small extension to the usual import syntax of
Haskell, adding a <emphasis>safe</emphasis> keyword:
<programlisting>
impdecl -> import [safe] [qualified] modid [as modid] [impspec]
</programlisting>
When used, the module being imported with the safe keyword must be a trusted
module, otherwise a compilation error will occur. The safe import extension
is enabled by either of the <emphasis>-XSafe</emphasis>,
<emphasis>-XTrustworthy</emphasis>, <emphasis>-XSafeLanguage</emphasis> or
<emphasis>-XSafeImports</emphasis> flags and corresponding PRAGMA's. When
either the <empahsis>-XSafe</empahsis> or
<emphasis>-XSafeLanguage</emphasis> flag is used, all imports are assumed to
be safe imports.
</sect2>
<sect2 id="safe-trust">
<title>Trust</title>
The Safe Haskell extension introduces the following two new language flags:
<itemizedlist>
<listitem><emphasis>-XSafe:</emphasis> Enables the Safe language dialect,
asking GHC to guarantee trust. The safe language dialect requires that
all imports be trusted or a compile error will occur.</listitem>
<listitem><emphasis>-XTrustworthy:</emphasis> Means that while this module
may invoke unsafe functions internally, the module's author claims that
it exports an API that can't be used in an unsafe way. This doesn't enable
the Safe language or place any restrictions on the allowed Haskell code.
The trust guarantee is provided by the module author, not GHC. Modules
imported with the <emphasis>safe</emphasis> import feature are required
to be trusted but otherwise unsafe modules can be imported as usual.
</listitem>
</itemizedlist>
The definition of trust for a module <emphasis>M</emphasis>, residing in
a package <emphasis>P</emphasis> for a user of GHC, a client
<emphasis>C</emphasis> (someone who is compiling a source module with GHC,
aka you!), is defined as follows:
A <emphasis>package P is trusted by client C</emphasis> if and only if one of
these conditions hold:
<itemizedlist>
<listitem>C's package database records that P is trusted (and no
command line arguments override this).</listitem>
<listitem>C's command-line flags say to trust it regardless of the
what is recorded in the package database.</listitem>
</itemizedlist>
It is important to note that C is the only authority on package trust. It is
up to the client to decide which packages they trust.
A <emphasis>module M is trusted by a client C</emphasis> if and only if:
<itemizedlist>
<listitem>Both of these hold:
<itemizedlist>
<listitem> The module was compiled with <emphasis>-XSafe</emphasis></listitem>
<listitem> All of M's direct imports are trusted by C</listitem>
</itemizedlist>
</listitem>
<listitem><emphasis>OR</emphasis> all of these hold:
<itemizedlist>
<listitem>The module was compiled with <emphasis>-XTrustworthy</emphasis></listitem>
<listitem>All of M's direct safe imports are trusted by C</listitem>
<listitem>Package P is trusted by C</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
For the first trust definition the trust guarantee is provided by GHC
through the restrictions imposed by the Safe language. For the second
definition of trust, the guarantee is provided initially by the
module author. The client C then establishes that they trust the
module author by indicating they trust the package the module resides
in. This trust chain is required as GHC provides no guarantee for
<emphasis>-XTrustworthy</emphasis> compiled modules.
</sect2>
</sect1>
<!-- Emacs stuff:
;;; Local Variables: ***
;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
;;; End: ***
-->
......@@ -13,6 +13,7 @@
<!ENTITY glasgowexts SYSTEM "glasgow_exts.xml" >
<!ENTITY packages SYSTEM "packages.xml" >
<!ENTITY parallel SYSTEM "parallel.xml" >
<!ENTITY safehaskell SYSTEM "safe_haskell.xml" >
<!ENTITY phases SYSTEM "phases.xml" >
<!ENTITY separate SYSTEM "separate_compilation.xml" >
<!ENTITY bugs SYSTEM "bugs.xml" >
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment