safe_haskell.rst 31.6 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87
.. _safe-haskell:

Safe Haskell
============

.. index::
   single: safe haskell

Safe Haskell is an extension to the Haskell language that is implemented
in GHC as of version 7.2. It allows for unsafe code to be securely
included in a trusted code base by restricting the features of GHC
Haskell the code is allowed to use. Put simply, it makes the types of
programs trustable.

While a primary use case of Safe Haskell is running untrusted code, Safe
Haskell doesn't provide this directly. Instead, Safe Haskell provides
strict type safety. Without Safe Haskell, GHC allows many exceptions to
the type system which can subvert any abstractions. By providing strict
type safety, Safe Haskell enables developers to build their own library
level sandbox mechanisms to run untrusted code.

While Safe Haskell is an extension, it actually runs in the background
for every compilation with GHC. It does this to track the type
violations of modules to infer their safety, even when they aren't
explicitly using Safe Haskell. Please refer to section
:ref:`safe-inference` for more details of this.

The design of Safe Haskell covers the following aspects:

- A :ref:`safe language <safe-language>` dialect of Haskell that provides
  stricter guarantees about the code. It allows types and module boundaries to
  be trusted.

- A *safe import* extension that specifies that the module being imported must
  be trusted.

- A definition of *trust* (or safety) and how it operates, along with ways of
  defining and changing the trust of modules and packages.

Safe Haskell, however, *does not offer* compilation safety. During
compilation time it is possible for arbitrary processes to be launched,
using for example the :ref:`custom pre-processor <pre-processor>` 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 Safe Haskell flags. This is discussed further in section
:ref:`safe-compilation`.

.. _safe-use-cases:

Uses of Safe Haskell
--------------------

.. index::
   single: safe haskell uses

Safe Haskell has been designed with two use cases in mind:

-  Enforcing strict type safety at compile time
-  Compiling and executing untrusted code

Strict type-safety (good style)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Haskell offers a powerful type system and separation of pure and effectual
functions through the ``IO`` monad. However, there are several loop holes in the
type system, the most obvious being the ``unsafePerformIO :: IO a -> a``
function. The safe language dialect of Safe Haskell disallows the use of such
functions. This can be useful restriction as it makes Haskell code easier to
analyse and reason about. It also codifies the existing culture in the Haskell
community of trying to avoid unsafe functions unless absolutely necessary. As
such, using the safe language (through the ``-XSafe`` flag) can be thought of as
a way of enforcing good style, similar to the function of ``-Wall``.

Building secure systems (restricted IO Monads)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. index::
   single: secure haskell

Systems such as information flow control security, capability based
security systems and DSLs for working with encrypted data.. etc can be
built in the Haskell language as a library. However they require
guarantees about the properties of Haskell that aren't true in general
due to the presence of functions like ``unsafePerformIO``. Safe Haskell
gives users enough guarantees about the type system to allow them to
build such secure systems.

88
As an example, let's define an interface for a plugin system where the
89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
plugin authors are untrusted, possibly malicious third-parties. We do
this by restricting the plugin interface to pure functions or to a
restricted ``IO`` monad that we have defined. The restricted ``IO``
monad will only allow a safe subset of ``IO`` actions to be executed. We
define the plugin interface so that it requires the plugin module,
``Danger``, to export a single computation, ``Danger.runMe``, of type
``RIO ()``, where ``RIO`` is a monad defined as follows:

::

    -- While we use `Safe', the `Trustworthy' pragma would also be
    -- fine. We simply want to ensure that:
    -- 1) The module exports an interface that untrusted code can't
    --    abuse.
    -- 2) Untrusted code can import this module.
    --
    {-# LANGUAGE Safe #-}

    module RIO (RIO(), runRIO, rioReadFile, rioWriteFile) where

    -- Notice that symbol UnsafeRIO is not exported from this module!
    newtype RIO a = UnsafeRIO { runRIO :: IO a }

    instance Monad RIO where
        return = UnsafeRIO . return
        (UnsafeRIO m) >>= k = UnsafeRIO $ m >>= runRIO . k

    -- Returns True iff access is allowed to file name
    pathOK :: FilePath -> IO Bool
    pathOK file = {- Implement some policy based on file name -}

    rioReadFile :: FilePath -> RIO String
    rioReadFile file = UnsafeRIO $ do
        ok <- pathOK file
        if ok then readFile file else return ""

    rioWriteFile :: FilePath -> String -> RIO ()
    rioWriteFile file contents = UnsafeRIO $ do
        ok <- pathOK file
        if ok then writeFile file contents else return ()

We then compile the ``Danger`` plugin using the new Safe Haskell
``-XSafe`` flag:
::

    {-# LANGUAGE Safe #-}
    module Danger ( runMe ) where

    runMe :: RIO ()
    runMe = ...

140
Before going into the Safe Haskell details, let's point out some of the
141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160
reasons this security mechanism would fail without Safe Haskell:

- The design attempts to restrict the operations that ``Danger`` can perform by
  using types, specifically the ``RIO`` type wrapper around ``IO`` . The author
  of ``Danger`` can subvert this though by simply writing arbitrary ``IO``
  actions and using ``unsafePerformIO :: IO a -> a`` to execute them as pure
  functions.

- The design also relies on ``Danger`` not being able to access the
  ``UnsafeRIO`` constructor. Unfortunately Template Haskell can be used to
  subvert module boundaries and so could be used to gain access to this
  constructor.

- There is no way to place restrictions on the modules that ``Danger`` can
  import. This gives the author of ``Danger`` a very large attack surface,
  essentially any package currently installed on the system. Should any of
  these packages have a vulnerability, then the ``Danger`` module can exploit
  it.

Safe Haskell prevents all these attacks. This is done by compiling the
161 162
RIO module with the :ghc-flag:`-XSafe` or :ghc-flag:`-XTrustworthy` flag and compiling
``Danger`` with the :ghc-flag:`-XSafe` flag. We explain each below.
163

164
The use of :ghc-flag:`-XSafe` to compile ``Danger`` restricts the features of
165 166 167
Haskell that can be used to a `safe subset <#safe-language>`__. This
includes disallowing ``unsafePerformIO``, Template Haskell, pure FFI
functions, RULES and restricting the operation of Overlapping Instances.
168
The :ghc-flag:`-XSafe` flag also restricts the modules can be imported by
169
``Danger`` to only those that are considered trusted. Trusted modules
170
are those compiled with :ghc-flag:`-XSafe`, where GHC provides a mechanical
171
guarantee that the code is safe. Or those modules compiled with
172
:ghc-flag:`-XTrustworthy`, where the module author claims that the module is
173 174
Safe.

175 176 177 178
This is why the RIO module is compiled with :ghc-flag:`-XSafe` or
:ghc-flag:`-XTrustworthy`>, to allow the ``Danger`` module to import it. The
:ghc-flag:`-XTrustworthy` flag doesn't place any restrictions on the module like
:ghc-flag:`-XSafe` does (expect to restrict overlapping instances to `safe
179 180 181 182
overlapping instances <#safe-overlapping-instances>`__). Instead the
module author claims that while code may use unsafe features internally,
it only exposes an API that can used in a safe manner.

183
However, the unrestricted use of :ghc-flag:`-XTrustworthy` is a problem as an
184
arbitrary module can use it to mark themselves as trusted, yet
185 186 187
:ghc-flag:`-XTrustworthy` doesn't offer any guarantees about the module, unlike
:ghc-flag:`-XSafe`. To control the use of trustworthy modules it is recommended
to use the :ghc-flag:`-fpackage-trust` flag. This flag adds an extra requirement
188 189
to the trust check for trustworthy modules. It requires that for a
trustworthy modules to be considered trusted, and allowed to be used in
190
:ghc-flag:`-XSafe` compiled code, the client C compiling the code must tell GHC
191 192 193
that they trust the package the trustworthy module resides in. This is
essentially a way of for C to say, while this package contains
trustworthy modules that can be used by untrusted modules compiled with
194
:ghc-flag:`-XSafe`, I trust the author(s) of this package and trust the modules
195 196 197 198 199 200 201
only expose a safe API. The trust of a package can be changed at any
time, so if a vulnerability found in a package, C can declare that
package untrusted so that any future compilation against that package
would fail. For a more detailed overview of this mechanism see
:ref:`safe-trust`.

In the example, ``Danger`` can import module ``RIO`` because ``RIO`` is
202
compiled with :ghc-flag:`-XSafe`. Thus, ``Danger`` can make use of the
203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260
``rioReadFile`` and ``rioWriteFile`` functions to access permitted file
names. The main application then imports both ``RIO`` and ``Danger``. To
run the plugin, it calls ``RIO.runRIO Danger.runMe`` within the ``IO``
monad. The application is safe in the knowledge that the only ``IO`` to
ensue will be to files whose paths were approved by the ``pathOK`` test.

.. _safe-language:

Safe Language
-------------

.. index::
   single: safe language

The Safe Haskell *safe language* (enabled by ``-XSafe``) guarantees the
following properties:

- *Referential transparency*  The types can be trusted. Any pure function, is
  guaranteed to be pure. Evaluating them is deterministic and won't cause any
  side effects. Functions in the ``IO`` monad are still allowed and behave as
  usual. So, for example, the ``unsafePerformIO :: IO a -> a`` function is
  disallowed in the safe language to enforce this property.

- *Module boundary control* — Only symbols that are publicly available through
  other module export lists can be accessed in the safe language. Values using
  data constructors not exported by the defining module, cannot be examined or
  created. As such, if a module ``M`` establishes some invariants through
  careful use of its export list, then code written in the safe language that
  imports ``M`` is guaranteed to respect those invariants.

- *Semantic consistency* — For any module that imports a module written in the
  safe language, expressions that compile both with and without the safe import
  have the same meaning in both cases. That is, importing a module written in
  the safe language cannot change the meaning of existing code that isn't
  dependent on that module. So, for example, there are some restrictions placed
  on the use of :ref:`OverlappingInstances <instance-overlap>`, as these can
  violate this property.

- *Strict subset*  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.

These four properties guarantee that in the safe language you can trust
the types, can trust that module export lists are respected, and can
trust that code that successfully compiles has the same meaning as it
normally would.

To achieve these properties, in the safe language dialect we disable
completely the following features:

- ``TemplateHaskell``  Can be used to gain access to constructors and abstract
  data types that weren't exported by a module, subverting module boundaries.

Furthermore, we restrict the following features:

- ``ForeignFunctionInterface`` — Foreign import declarations that import a
  function with a non-``IO`` type are disallowed.

261
- ``RULES`` — Rewrite rules defined in a module M compiled with :ghc-flag:`-XSafe` are
262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277
  dropped. Rules defined in Trustworthy modules that ``M`` imports are still
  valid and will fire as usual.

- ``OverlappingInstances`` — There is no restriction on the creation of
  overlapping instances, but we do restrict their use at a particular call
  site. This is a detailed restriction, please refer to :ref:`Safe Overlapping
  Instances <safe-overlapping-instances>` for details.

- ``GeneralisedNewtypeDeriving`` — GND is not allowed in the safe language. This
  is due to the ability of it to violate module boundaries when module authors
  forget to put nominal role annotations on their types as appropriate. For
  this reason, the ``Data.Coerce`` module is also considered unsafe. We are
  hoping to find a better solution here in the future.

- ``Data.Typeable`` — Hand crafted instances of the Typeable type class are not allowed
  in Safe Haskell as this can easily be abused to unsafely coerce
278
  between types. Derived instances (through the :ghc-flag:`-XDeriveDataTypeable`
279 280
  extension) are still allowed.

281 282 283 284 285 286
- ``GHC.Generics`` — Hand crafted instances of the ``Generic`` type class are
  not allowed in Safe Haskell. Such instances aren't strictly unsafe, but
  there is an important invariant that a ``Generic`` instance should adhere to
  the structure of the data type for which the instance is defined, and
  allowing manually implemented ``Generic`` instances would break that
  invariant. Derived instances (through the :ghc-flag:`-XDeriveGeneric`
Ryan Scott's avatar
Ryan Scott committed
287 288 289 290 291 292
  extension) are still allowed. Note that the only allowed
  :ref:`deriving strategy <deriving-strategies>` for deriving ``Generic`` under
  Safe Haskell is ``stock``, as another strategy (e.g., ``anyclass``) would
  produce an instance that violates the invariant.

  Refer to the
293 294
  :ref:`generic programming <generic-programming>` section for more details.

295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334
.. _safe-overlapping-instances:

Safe Overlapping Instances
~~~~~~~~~~~~~~~~~~~~~~~~~~

Due to the semantic consistency guarantee of Safe Haskell, we must
restrict the function of overlapping instances. We don't restrict their
ability to be defined, as this is a global property and not something we
can determine by looking at a single module. Instead, when a module
calls a function belonging to a type-class, we check that the instance
resolution done is considered 'safe'. This check is enforced for modules
compiled with both ``-XSafe`` and ``-XTrustworthy``.

More specifically, consider the following modules:

::

            {-# LANGUAGE Safe #-}
            module Class (TC(..)) where
              class TC a where { op :: a -> String }

            {-# LANGUAGE Safe #-}
            module Dangerous (TC(..)) where
              import Class

              instance
                {-# OVERLAPS #-}
                TC [Int] where { op _ = "[Int]" }

            {-# LANGUAGE Safe #-}
            module TCB_Runner where
              import Class
              import Dangerous

              instance
                TC [a] where { op _ = "[a]" }

              f :: String
              f = op ([1,2,3,4] :: [Int])

335
Both module ``Class`` and module ``Dangerous`` will compile under :ghc-flag:`-XSafe`
336 337 338 339
without issue. However, in module ``TCB_Runner``, we must check if the call
to ``op`` in function ``f`` is safe.

What does it mean to be Safe? That importing a module compiled with
340
:ghc-flag:`-XSafe` shouldn't change the meaning of code that compiles fine
341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366
without importing the module. This is the Safe Haskell property known as
*semantic consistency*.

In our situation, module ``TCB_Runner`` compiles fine without importing
module ``Dangerous``. So when deciding which instance to use for the call to
``op``, if we determine the instance ``TC [Int]`` from module Dangerous
is the most specific, this is unsafe. This prevents code written by
third-parties we don't trust (which is compiled using ``-XSafe`` in Safe
Haskell) from changing the behaviour of our existing code.

Specifically, we apply the following rule to determine if a type-class
method call is *unsafe* when overlapping instances are involved:

-  Most specific instance, ``Ix``, defined in an ``-XSafe`` compiled module.
-  ``Ix`` is an orphan instance or a multi-parameter-type-class.
-  At least one overlapped instance, ``Iy``, is both:

   -  From a different module than ``Ix``
   -  ``Iy`` is not marked ``OVERLAPPABLE``

This is a slightly involved heuristic, but captures the situation of an
imported module ``N`` changing the behaviour of existing code. For example,
if the second condition isn't violated, then the module author ``M`` must
depend either on a type-class or type defined in ``N``.

When an particular type-class method call is considered unsafe due to
367 368
overlapping instances, and the module being compiled is using :ghc-flag:`-XSafe`
or :ghc-flag:`-XTrustworthy`, then compilation will fail. For :ghc-flag:`-XUnsafe`, no
369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403
restriction is applied, and for modules using safe inference, they will
be inferred unsafe.

.. _safe-imports:

Safe Imports
------------

.. index::
   single: safe imports

Safe Haskell enables a small extension to the usual import syntax of
Haskell, adding a ``safe`` keyword:

::

    impdecl -> import [safe] [qualified] modid [as modid] [impspec]

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 ``-XSafe`` , ``-XTrustworthy`` , or
``-XUnsafe`` flags. When the ``-XSafe`` flag is used, the ``safe`` keyword is
allowed but meaningless, as every import is treated as a safe import.

.. _safe-trust:

Trust and Safe Haskell Modes
----------------------------

.. index::
   single: safe haskell trust
   single: trust

Safe Haskell introduces the following three language flags:

404
- :ghc-flag:`-XSafe`  Enables the safe language dialect, asking GHC to guarantee trust.
405 406 407 408 409
  The safe language dialect requires that all imports be trusted or a
  compilation error will occur. Safe Haskell will also infer this safety type
  for modules automatically when possible. Please refer to section
  :ref:`safe-inference` for more details of this.

410
- :ghc-flag:`-XTrustworthy`  Means that while this module may invoke unsafe functions
411 412 413 414 415 416 417 418 419
  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. It does however
  restrict the resolution of overlapping instances to only allow :ref:`safe
  overlapping instances <safe-overlapping-instances>`. The trust guarantee is
  provided by the module author, not GHC. An import statement with the ``safe``
  keyword results in a compilation error if the imported module is not trusted.
  An import statement without the keyword behaves as usual and can import any
  module whether trusted or not.

420 421
- :ghc-flag:`-XUnsafe` — Marks the module being compiled as unsafe so that modules
  compiled using :ghc-flag:`-XSafe` can't import it. You may want to explicitly mark a
422 423 424 425 426 427 428 429 430 431 432
  module unsafe when it exports internal constructors that can be used to
  violate invariants.

While these are flags, they also correspond to Safe Haskell module types
that a module can have. You can think of using these as declaring an
explicit contract (or type) that a module must have. If it is invalid,
then compilation will fail. GHC will also infer the correct type for
Safe Haskell, please refer to section :ref:`safe-inference` for more
details.

The procedure to check if a module is trusted or not depends on if the
433 434
:ghc-flag:`-fpackage-trust` flag is present. The check is similar in both cases
with the :ghc-flag:`-fpackage-trust` flag enabling an extra requirement for
435 436 437 438 439 440 441 442 443 444 445 446
trustworthy modules to be regarded as trusted.

Trust check (``-fpackage-trust`` disabled)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. index::
   single: trust check

A module ``M`` in a package ``P`` is trusted by a client C if and only if:

- Both of these hold:

447
   -  The module was compiled with :ghc-flag:`-XSafe`
448 449 450 451
   -  All of M's direct imports are trusted by C

- *or* all of these hold:

452
   -  The module was compiled with :ghc-flag:`-XTrustworthy`
453 454 455
   -  All of ``M``\'s direct *safe imports* are trusted by C

The above definition of trust has an issue. Any module can be compiled
456
with :ghc-flag:`-XTrustworthy` and it will be trusted. To control this, there is
457
an additional definition of package trust (enabled with the
458
:ghc-flag:`-fpackage-trust` flag). The point of package trust is to require that
459 460 461 462 463 464 465 466 467 468 469
the client C explicitly say which packages are allowed to contain
trustworthy modules. Trustworthy packages are only trusted if they
reside in a package trusted by C.

Trust check (``-fpackage-trust`` enabled)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. index::
   single: trust check
   single: -fpackage-trust

470
When the :ghc-flag:`-fpackage-trust` flag is enabled, whether or not a module is
471 472 473 474 475 476 477 478 479 480 481 482 483
trusted depends on if certain packages are trusted. Package trust is
determined by the client C invoking GHC (i.e. you).

Specifically, a package *P is trusted* when one of these hold:

-  C's package database records that ``P`` is trusted (and no command-line
   arguments override this)
-  C's command-line flags say to trust ``P`` regardless of what is recorded
   in the package database.

In either case, C is the only authority on package trust. It is up to
the client to decide which `packages they trust <#safe-package-trust>`__.

484
When the :ghc-flag:`-fpackage-trust` flag is used a *module M from package P is
485 486 487 488
trusted by a client C* if and only if:

-  Both of these hold:

489
   -  The module was compiled with :ghc-flag:`-XSafe`
490 491 492 493
   -  All of ``M``\'s direct imports are trusted by C

-  *or* all of these hold:

494
   -  The module was compiled with :ghc-flag:`-XTrustworthy`
495 496 497 498 499 500 501 502
   -  All of ``M``\'s direct safe imports are trusted by C
   -  Package ``P`` is trusted by C

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
503
chain is required as GHC provides no guarantee for :ghc-flag:`-XTrustworthy`
504 505 506
compiled modules.

The reason there are two modes of checking trust is that the extra
507
requirement enabled by :ghc-flag:`-fpackage-trust` causes the design of Safe
508 509 510 511 512
Haskell to be invasive. Packages using Safe Haskell when the flag is
enabled may or may not compile depending on the state of trusted
packages on a users machine. This is both fragile, and causes
compilation failures for everyone, even if they aren't trying to use any
of the guarantees provided by Safe Haskell. Disabling
513
:ghc-flag:`-fpackage-trust` by default and turning it into a flag makes Safe
514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535
Haskell an opt-in extension rather than an always on feature.

.. _safe-trust-example:

Example
~~~~~~~

::

    Package Wuggle:
        {-# LANGUAGE Safe #-}
        module Buggle where
            import Prelude
            f x = ...blah...

    Package P:
        {-# LANGUAGE Trustworthy #-}
        module M where
            import System.IO.Unsafe
            import safe Buggle

Suppose a client C decides to trust package ``P`` and package ``base``. Then
536
does C trust module ``M``? Well ``M`` is marked :ghc-flag:`-XTrustworthy`, so we don't
537 538 539
restrict the language. However, we still must check ``M``\'s imports:

- First, ``M`` imports ``System.IO.Unsafe``. This is an unsafe module, however
540
  ``M`` was compiled with :ghc-flag:`-XTrustworthy` , so ``P``\'s author takes
541 542 543 544 545 546 547 548 549 550 551
  responsibility for that import. ``C`` trusts ``P``\'s author, so this import
  is fine.

- Second, ``M`` safe imports ``Buggle``. For this import ``P``\'s author takes
  no responsibility for the safety, instead asking GHC to check whether
  ``Buggle`` is trusted by ``C``. Is it?

- ``Buggle``, is compiled with ``-XSafe``, so the code is machine-checked to be
  OK, but again under the assumption that all of ``Buggle``\'s imports are
  trusted by ``C``. We must recursively check all imports!

552
- Buggle only imports ``Prelude``, which is compiled with :ghc-flag:`-XTrustworthy`.
553 554 555 556 557 558
  ``Prelude`` resides in the ``base`` package, which ``C`` trusts, and (we'll
  assume) all of ``Prelude``\'s imports are trusted. So ``C`` trusts
  ``Prelude``, and so ``C`` also trusts Buggle. (While ``Prelude`` is typically
  imported implicitly, it still obeys the same rules outlined here).

Notice that C didn't need to trust package Wuggle; the machine checking
559
is enough. C only needs to trust packages that contain :ghc-flag:`-XTrustworthy`
560 561 562 563 564 565 566 567 568 569
modules.

.. _trustworthy-guarantees:

Trustworthy Requirements
~~~~~~~~~~~~~~~~~~~~~~~~

.. index::
   single: trustworthy

570
Module authors using the :ghc-flag:`-XTrustworthy` language extension for a module ``M``
571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586
should ensure that ``M``\'s public API (the symbols exposed by its export list)
can't be used in an unsafe manner. This mean that symbols exported should
respect type safety and referential transparency.

.. _safe-package-trust:

Package Trust
~~~~~~~~~~~~~

.. index::
   single: package trust

Safe Haskell gives packages a new Boolean property, that of trust.
Several new options are available at the GHC command-line to specify the
trust property of packages:

587
.. ghc-flag:: -trust pkg
588

589 590
   Exposes package pkg if it was hidden and considers it a
   trusted package regardless of the package database.
591

592 593 594 595 596 597 598 599 600
.. ghc-flag:: -distrust pkg

   Exposes package pkg if it was hidden and considers it
   an untrusted package regardless of the package database.

.. ghc-flag:: -distrust-all-packages

   Considers all packages distrusted unless they are
   explicitly set to be trusted by subsequent command-line options.
601 602 603 604 605 606 607 608 609 610 611 612

To set a package's trust property in the package database please refer
to :ref:`packages`.

.. _safe-inference:

Safe Haskell Inference
----------------------

.. index::
   single: safe inference

613 614
In the case where a module is compiled without one of :ghc-flag:`-XSafe`,
:ghc-flag:`-XTrustworthy` or :ghc-flag:`-XUnsafe` being used, GHC will try to figure out
615 616 617
itself if the module can be considered safe. This safety inference will
never mark a module as trustworthy, only as either unsafe or as safe.
GHC uses a simple method to determine this for a module M: If M would
618
compile without error under the :ghc-flag:`-XSafe` flag, then M is marked as
619 620 621
safe. Otherwise, it is marked as unsafe.

When should you use Safe Haskell inference and when should you use an
622
explicit :ghc-flag:`-XSafe` flag? The later case should be used when you have a
623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653
hard requirement that the module be safe. This is most useful for the
:ref:`safe-use-cases` of Safe Haskell: running untrusted code. Safe
inference is meant to be used by ordinary Haskell programmers. Users who
probably don't care about Safe Haskell.

Haskell library authors have a choice. Most should just use Safe
inference. Assuming you avoid any unsafe features of the language then
your modules will be marked safe. Inferred vs. Explicit has the
following trade-offs:

- *Inferred*  This works well and adds no dependencies on the Safe Haskell type
  of any modules in other packages. It does mean that the Safe Haskell type of
  your own modules could change without warning if a dependency changes. One
  way to deal with this is through the use of :ref:`Safe Haskell warning flags
  <safe-flag-summary>` that will warn if GHC infers a Safe Haskell type
  different from expected.

- *Explicit*  This gives your library a stable Safe Haskell type that others
  can depend on. However, it will increase the chance of compilation failure
  when your package dependencies change.

.. _safe-flag-summary:

Safe Haskell Flag Summary
-------------------------

.. index::
   single: Safe Haskell flags

In summary, Safe Haskell consists of the following three language flags:

654
.. ghc-flag:: -XSafe
655

656 657
    :since: 7.2.1

658 659 660 661 662 663 664 665 666 667 668
    Restricts the module to the safe language. All of the module's
    direct imports must be trusted, but the module itself need not
    reside in a trusted package, because the compiler vouches for its
    trustworthiness. The "safe" keyword is allowed but meaningless in
    import statements, as regardless, every import is required to be
    safe.

    - *Module Trusted* — Yes
    - *Haskell Language* — Restricted to Safe Language
    - *Imported Modules* — All forced to be safe imports, all must be trusted.

669
.. ghc-flag:: -XTrustworthy
670

671 672
    :since: 7.2.1

673 674 675
    This establishes that the module is trusted, but the guarantee is
    provided by the module's author. A client of this module then
    specifies that they trust the module author by specifying they trust
676
    the package containing the module. :ghc-flag:`-XTrustworthy` doesn't restrict the
677 678 679 680 681
    module to the safe language. It does however restrict the resolution of
    overlapping instances to only allow :ref:`safe overlapping instances
    <safe-overlapping-instances>`. It also allows the use of the safe import
    keyword.

682 683 684 685
    - *Module Trusted*  — Yes.
    - *Module Trusted*  (:ghc-flag:`-fpackage-trust` enabled) — Yes but only if the package
      the module resides in is also trusted.
    - *Haskell Language*  — Unrestricted, except only safe overlapping instances
686 687 688 689
      allowed.
    - *Imported Modules* — Under control of module author which ones must be
      trusted.

690
.. ghc-flag:: -XUnsafe
691

692 693
    :since: 7.4.1

694
    Mark a module as unsafe so that it can't be imported by code
695
    compiled with :ghc-flag:`-XSafe`. Also enable the Safe Import extension so that a
696 697 698 699 700 701 702 703 704 705
    module can require
    a dependency to be trusted.

    - *Module Trusted*  No
    - *Haskell Language*  Unrestricted
    - *Imported Modules*  Under control of module author which ones must be
      trusted.

And one general flag:

706
.. ghc-flag:: -fpackage-trust
707 708 709 710 711 712
    When enabled, turn on an extra check for a trustworthy module ``M``,
    requiring the package that ``M`` resides in be considered trusted, for ``M``
    to be considered trusted.

And three warning flags:

713
.. ghc-flag:: -Wunsafe
714

715 716 717 718
    Issue a warning if the module being compiled is regarded to be
    unsafe. Should be used to check the safety type of modules when
    using safe inference.

719
.. ghc-flag:: -Wsafe
720

721 722 723 724
    Issue a warning if the module being compiled is regarded to be safe.
    Should be used to check the safety type of modules when using safe
    inference.

725
.. ghc-flag:: -Wtrustworthy-safe
726

727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760
    Issue a warning if the module being compiled is marked as
    -XTrustworthy but it could instead be marked as
    -XSafe , a more informative bound. Can be used to detect once a Safe Haskell
    bound can be improved as dependencies are updated.

.. _safe-compilation:

Safe Compilation
----------------

.. index::
   single: safe compilation

GHC includes a variety of flags that allow arbitrary processes to be run
at compilation time. One such example is the
:ref:`custom pre-processor <pre-processor>` flag. Another is the ability of
Template Haskell to execute Haskell code at compilation time, including
IO actions. Safe Haskell *does not address this danger* (although,
Template Haskell is a disallowed feature).

Due to this, it is suggested that when compiling untrusted source code
that has had no manual inspection done, the following precautions be
taken:

-  Compile in a sandbox, such as a chroot or similar container
   technology. Or simply as a user with very reduced system access.

-  Compile untrusted code with the ``-XSafe``
   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.

-  Ensure that all untrusted code is imported as a
761 762 763
   :ref:`safe import <safe-imports>` and that the :ghc-flag:`-fpackage-trust`
   flag (see :ref:`flag <safe-package-trust>`) is used with packages from
   untrusted sources being marked as untrusted.
764 765 766 767

There is a more detailed discussion of the issues involved in
compilation safety and some potential solutions on the
:ghc-wiki:`GHC Wiki <SafeHaskell/SafeCompilation>`.
768

769 770 771
Additionally, the use of :ref:`annotations <annotation-pragmas>` is forbidden,
as that would allow bypassing Safe Haskell restrictions. See :ghc-ticket:`10826`
for details.