users_guide: Convert mkUserGuidePart generation to a Sphinx extension
[ghc.git] / docs / users_guide / safe_haskell.rst
1 .. _safe-haskell:
2
3 Safe Haskell
4 ============
5
6 .. index::
7    single: safe haskell
8
9 Safe Haskell is an extension to the Haskell language that is implemented
10 in GHC as of version 7.2. It allows for unsafe code to be securely
11 included in a trusted code base by restricting the features of GHC
12 Haskell the code is allowed to use. Put simply, it makes the types of
13 programs trustable.
14
15 While a primary use case of Safe Haskell is running untrusted code, Safe
16 Haskell doesn't provide this directly. Instead, Safe Haskell provides
17 strict type safety. Without Safe Haskell, GHC allows many exceptions to
18 the type system which can subvert any abstractions. By providing strict
19 type safety, Safe Haskell enables developers to build their own library
20 level sandbox mechanisms to run untrusted code.
21
22 While Safe Haskell is an extension, it actually runs in the background
23 for every compilation with GHC. It does this to track the type
24 violations of modules to infer their safety, even when they aren't
25 explicitly using Safe Haskell. Please refer to section
26 :ref:`safe-inference` for more details of this.
27
28 The design of Safe Haskell covers the following aspects:
29
30 - A :ref:`safe language <safe-language>` dialect of Haskell that provides
31   stricter guarantees about the code. It allows types and module boundaries to
32   be trusted.
33
34 - A *safe import* extension that specifies that the module being imported must
35   be trusted.
36
37 - A definition of *trust* (or safety) and how it operates, along with ways of
38   defining and changing the trust of modules and packages.
39
40 Safe Haskell, however, *does not offer* compilation safety. During
41 compilation time it is possible for arbitrary processes to be launched,
42 using for example the :ref:`custom pre-processor <pre-processor>` flag.
43 This can be manipulated to either compromise a user's system at
44 compilation time, or to modify the source code just before compilation
45 to try to alter Safe Haskell flags. This is discussed further in section
46 :ref:`safe-compilation`.
47
48 .. _safe-use-cases:
49
50 Uses of Safe Haskell
51 --------------------
52
53 .. index::
54    single: safe haskell uses
55
56 Safe Haskell has been designed with two use cases in mind:
57
58 -  Enforcing strict type safety at compile time
59 -  Compiling and executing untrusted code
60
61 Strict type-safety (good style)
62 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
63
64 Haskell offers a powerful type system and separation of pure and effectual
65 functions through the ``IO`` monad. However, there are several loop holes in the
66 type system, the most obvious being the ``unsafePerformIO :: IO a -> a``
67 function. The safe language dialect of Safe Haskell disallows the use of such
68 functions. This can be useful restriction as it makes Haskell code easier to
69 analyse and reason about. It also codifies the existing culture in the Haskell
70 community of trying to avoid unsafe functions unless absolutely necessary. As
71 such, using the safe language (through the ``-XSafe`` flag) can be thought of as
72 a way of enforcing good style, similar to the function of ``-Wall``.
73
74 Building secure systems (restricted IO Monads)
75 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
76
77 .. index::
78    single: secure haskell
79
80 Systems such as information flow control security, capability based
81 security systems and DSLs for working with encrypted data.. etc can be
82 built in the Haskell language as a library. However they require
83 guarantees about the properties of Haskell that aren't true in general
84 due to the presence of functions like ``unsafePerformIO``. Safe Haskell
85 gives users enough guarantees about the type system to allow them to
86 build such secure systems.
87
88 As an example, let's define an interface for a plugin system where the
89 plugin authors are untrusted, possibly malicious third-parties. We do
90 this by restricting the plugin interface to pure functions or to a
91 restricted ``IO`` monad that we have defined. The restricted ``IO``
92 monad will only allow a safe subset of ``IO`` actions to be executed. We
93 define the plugin interface so that it requires the plugin module,
94 ``Danger``, to export a single computation, ``Danger.runMe``, of type
95 ``RIO ()``, where ``RIO`` is a monad defined as follows:
96
97 ::
98
99     -- While we use `Safe', the `Trustworthy' pragma would also be
100     -- fine. We simply want to ensure that:
101     -- 1) The module exports an interface that untrusted code can't
102     --    abuse.
103     -- 2) Untrusted code can import this module.
104     --
105     {-# LANGUAGE Safe #-}
106
107     module RIO (RIO(), runRIO, rioReadFile, rioWriteFile) where
108
109     -- Notice that symbol UnsafeRIO is not exported from this module!
110     newtype RIO a = UnsafeRIO { runRIO :: IO a }
111
112     instance Monad RIO where
113         return = UnsafeRIO . return
114         (UnsafeRIO m) >>= k = UnsafeRIO $ m >>= runRIO . k
115
116     -- Returns True iff access is allowed to file name
117     pathOK :: FilePath -> IO Bool
118     pathOK file = {- Implement some policy based on file name -}
119
120     rioReadFile :: FilePath -> RIO String
121     rioReadFile file = UnsafeRIO $ do
122         ok <- pathOK file
123         if ok then readFile file else return ""
124
125     rioWriteFile :: FilePath -> String -> RIO ()
126     rioWriteFile file contents = UnsafeRIO $ do
127         ok <- pathOK file
128         if ok then writeFile file contents else return ()
129
130 We then compile the ``Danger`` plugin using the new Safe Haskell
131 ``-XSafe`` flag:
132 ::
133
134     {-# LANGUAGE Safe #-}
135     module Danger ( runMe ) where
136
137     runMe :: RIO ()
138     runMe = ...
139
140 Before going into the Safe Haskell details, let's point out some of the
141 reasons this security mechanism would fail without Safe Haskell:
142
143 - The design attempts to restrict the operations that ``Danger`` can perform by
144   using types, specifically the ``RIO`` type wrapper around ``IO`` . The author
145   of ``Danger`` can subvert this though by simply writing arbitrary ``IO``
146   actions and using ``unsafePerformIO :: IO a -> a`` to execute them as pure
147   functions.
148
149 - The design also relies on ``Danger`` not being able to access the
150   ``UnsafeRIO`` constructor. Unfortunately Template Haskell can be used to
151   subvert module boundaries and so could be used to gain access to this
152   constructor.
153
154 - There is no way to place restrictions on the modules that ``Danger`` can
155   import. This gives the author of ``Danger`` a very large attack surface,
156   essentially any package currently installed on the system. Should any of
157   these packages have a vulnerability, then the ``Danger`` module can exploit
158   it.
159
160 Safe Haskell prevents all these attacks. This is done by compiling the
161 RIO module with the :ghc-flag:`-XSafe` or :ghc-flag:`-XTrustworthy` flag and compiling
162 ``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 Haskell that can be used to a `safe subset <#safe-language>`__. This
166 includes disallowing ``unsafePerformIO``, Template Haskell, pure FFI
167 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 Safe.
174
175 This is why the RIO module is compiled with :ghc-flag:`-XSafe` or
176 :ghc-flag:`-XTrustworthy`>, to allow the ``Danger`` module to import it. The
177 :ghc-flag:`-XTrustworthy` flag doesn't place any restrictions on the module like
178 :ghc-flag:`-XSafe` does (expect to restrict overlapping instances to `safe
179 overlapping instances <#safe-overlapping-instances>`__). Instead the
180 module author claims that while code may use unsafe features internally,
181 it only exposes an API that can used in a safe manner.
182
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 :ghc-flag:`-XTrustworthy` doesn't offer any guarantees about the module, unlike
186 :ghc-flag:`-XSafe`. To control the use of trustworthy modules it is recommended
187 to use the :ghc-flag:`-fpackage-trust` flag. This flag adds an extra requirement
188 to the trust check for trustworthy modules. It requires that for a
189 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 that they trust the package the trustworthy module resides in. This is
192 essentially a way of for C to say, while this package contains
193 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 only expose a safe API. The trust of a package can be changed at any
196 time, so if a vulnerability found in a package, C can declare that
197 package untrusted so that any future compilation against that package
198 would fail. For a more detailed overview of this mechanism see
199 :ref:`safe-trust`.
200
201 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 ``rioReadFile`` and ``rioWriteFile`` functions to access permitted file
204 names. The main application then imports both ``RIO`` and ``Danger``. To
205 run the plugin, it calls ``RIO.runRIO Danger.runMe`` within the ``IO``
206 monad. The application is safe in the knowledge that the only ``IO`` to
207 ensue will be to files whose paths were approved by the ``pathOK`` test.
208
209 .. _safe-language:
210
211 Safe Language
212 -------------
213
214 .. index::
215    single: safe language
216
217 The Safe Haskell *safe language* (enabled by ``-XSafe``) guarantees the
218 following properties:
219
220 - *Referential transparency* — The types can be trusted. Any pure function, is
221   guaranteed to be pure. Evaluating them is deterministic and won't cause any
222   side effects. Functions in the ``IO`` monad are still allowed and behave as
223   usual. So, for example, the ``unsafePerformIO :: IO a -> a`` function is
224   disallowed in the safe language to enforce this property.
225
226 - *Module boundary control* — Only symbols that are publicly available through
227   other module export lists can be accessed in the safe language. Values using
228   data constructors not exported by the defining module, cannot be examined or
229   created. As such, if a module ``M`` establishes some invariants through
230   careful use of its export list, then code written in the safe language that
231   imports ``M`` is guaranteed to respect those invariants.
232
233 - *Semantic consistency* — For any module that imports a module written in the
234   safe language, expressions that compile both with and without the safe import
235   have the same meaning in both cases. That is, importing a module written in
236   the safe language cannot change the meaning of existing code that isn't
237   dependent on that module. So, for example, there are some restrictions placed
238   on the use of :ref:`OverlappingInstances <instance-overlap>`, as these can
239   violate this property.
240
241 - *Strict subset* — The safe language is strictly a subset of Haskell as
242   implemented by GHC. Any expression that compiles in the safe language has the
243   same meaning as it does when compiled in normal Haskell.
244
245 These four properties guarantee that in the safe language you can trust
246 the types, can trust that module export lists are respected, and can
247 trust that code that successfully compiles has the same meaning as it
248 normally would.
249
250 To achieve these properties, in the safe language dialect we disable
251 completely the following features:
252
253 - ``TemplateHaskell`` — Can be used to gain access to constructors and abstract
254   data types that weren't exported by a module, subverting module boundaries.
255
256 Furthermore, we restrict the following features:
257
258 - ``ForeignFunctionInterface`` — Foreign import declarations that import a
259   function with a non-``IO`` type are disallowed.
260
261 - ``RULES`` — Rewrite rules defined in a module M compiled with :ghc-flag:`-XSafe` are
262   dropped. Rules defined in Trustworthy modules that ``M`` imports are still
263   valid and will fire as usual.
264
265 - ``OverlappingInstances`` — There is no restriction on the creation of
266   overlapping instances, but we do restrict their use at a particular call
267   site. This is a detailed restriction, please refer to :ref:`Safe Overlapping
268   Instances <safe-overlapping-instances>` for details.
269
270 - ``GeneralisedNewtypeDeriving`` — GND is not allowed in the safe language. This
271   is due to the ability of it to violate module boundaries when module authors
272   forget to put nominal role annotations on their types as appropriate. For
273   this reason, the ``Data.Coerce`` module is also considered unsafe. We are
274   hoping to find a better solution here in the future.
275
276 - ``GHC.Generics`` — Hand crafted instances of the ``Generic`` type class are
277   not allowed in Safe Haskell. Such instances aren't strictly unsafe, but
278   there is an important invariant that a ``Generic`` instance should adhere to
279   the structure of the data type for which the instance is defined, and
280   allowing manually implemented ``Generic`` instances would break that
281   invariant. Derived instances (through the :ghc-flag:`-XDeriveGeneric`
282   extension) are still allowed. Note that the only allowed
283   :ref:`deriving strategy <deriving-strategies>` for deriving ``Generic`` under
284   Safe Haskell is ``stock``, as another strategy (e.g., ``anyclass``) would
285   produce an instance that violates the invariant.
286
287   Refer to the
288   :ref:`generic programming <generic-programming>` section for more details.
289
290 .. _safe-overlapping-instances:
291
292 Safe Overlapping Instances
293 ~~~~~~~~~~~~~~~~~~~~~~~~~~
294
295 Due to the semantic consistency guarantee of Safe Haskell, we must
296 restrict the function of overlapping instances. We don't restrict their
297 ability to be defined, as this is a global property and not something we
298 can determine by looking at a single module. Instead, when a module
299 calls a function belonging to a type-class, we check that the instance
300 resolution done is considered 'safe'. This check is enforced for modules
301 compiled with both ``-XSafe`` and ``-XTrustworthy``.
302
303 More specifically, consider the following modules:
304
305 ::
306
307             {-# LANGUAGE Safe #-}
308             module Class (TC(..)) where
309               class TC a where { op :: a -> String }
310
311             {-# LANGUAGE Safe #-}
312             module Dangerous (TC(..)) where
313               import Class
314
315               instance
316                 {-# OVERLAPS #-}
317                 TC [Int] where { op _ = "[Int]" }
318
319             {-# LANGUAGE Safe #-}
320             module TCB_Runner where
321               import Class
322               import Dangerous
323
324               instance
325                 TC [a] where { op _ = "[a]" }
326
327               f :: String
328               f = op ([1,2,3,4] :: [Int])
329
330 Both module ``Class`` and module ``Dangerous`` will compile under :ghc-flag:`-XSafe`
331 without issue. However, in module ``TCB_Runner``, we must check if the call
332 to ``op`` in function ``f`` is safe.
333
334 What does it mean to be Safe? That importing a module compiled with
335 :ghc-flag:`-XSafe` shouldn't change the meaning of code that compiles fine
336 without importing the module. This is the Safe Haskell property known as
337 *semantic consistency*.
338
339 In our situation, module ``TCB_Runner`` compiles fine without importing
340 module ``Dangerous``. So when deciding which instance to use for the call to
341 ``op``, if we determine the instance ``TC [Int]`` from module Dangerous
342 is the most specific, this is unsafe. This prevents code written by
343 third-parties we don't trust (which is compiled using ``-XSafe`` in Safe
344 Haskell) from changing the behaviour of our existing code.
345
346 Specifically, we apply the following rule to determine if a type-class
347 method call is *unsafe* when overlapping instances are involved:
348
349 -  Most specific instance, ``Ix``, defined in an ``-XSafe`` compiled module.
350 -  ``Ix`` is an orphan instance or a multi-parameter-type-class.
351 -  At least one overlapped instance, ``Iy``, is both:
352
353    -  From a different module than ``Ix``
354    -  ``Iy`` is not marked ``OVERLAPPABLE``
355
356 This is a slightly involved heuristic, but captures the situation of an
357 imported module ``N`` changing the behaviour of existing code. For example,
358 if the second condition isn't violated, then the module author ``M`` must
359 depend either on a type-class or type defined in ``N``.
360
361 When an particular type-class method call is considered unsafe due to
362 overlapping instances, and the module being compiled is using :ghc-flag:`-XSafe`
363 or :ghc-flag:`-XTrustworthy`, then compilation will fail. For :ghc-flag:`-XUnsafe`, no
364 restriction is applied, and for modules using safe inference, they will
365 be inferred unsafe.
366
367 .. _safe-imports:
368
369 Safe Imports
370 ------------
371
372 .. index::
373    single: safe imports
374
375 Safe Haskell enables a small extension to the usual import syntax of
376 Haskell, adding a ``safe`` keyword:
377
378 .. code-block:: none
379
380     impdecl -> import [safe] [qualified] modid [as modid] [impspec]
381
382 When used, the module being imported with the safe keyword must be a
383 trusted module, otherwise a compilation error will occur. The safe
384 import extension is enabled by either of the ``-XSafe`` , ``-XTrustworthy`` , or
385 ``-XUnsafe`` flags. When the ``-XSafe`` flag is used, the ``safe`` keyword is
386 allowed but meaningless, as every import is treated as a safe import.
387
388 .. _safe-trust:
389
390 Trust and Safe Haskell Modes
391 ----------------------------
392
393 .. index::
394    single: safe haskell trust
395    single: trust
396
397 Safe Haskell introduces the following three language flags:
398
399 - :ghc-flag:`-XSafe` — Enables the safe language dialect, asking GHC to guarantee trust.
400   The safe language dialect requires that all imports be trusted or a
401   compilation error will occur. Safe Haskell will also infer this safety type
402   for modules automatically when possible. Please refer to section
403   :ref:`safe-inference` for more details of this.
404
405 - :ghc-flag:`-XTrustworthy` — Means that while this module may invoke unsafe functions
406   internally, the module's author claims that it exports an API that can't be
407   used in an unsafe way. This doesn't enable the safe language. It does however
408   restrict the resolution of overlapping instances to only allow :ref:`safe
409   overlapping instances <safe-overlapping-instances>`. The trust guarantee is
410   provided by the module author, not GHC. An import statement with the ``safe``
411   keyword results in a compilation error if the imported module is not trusted.
412   An import statement without the keyword behaves as usual and can import any
413   module whether trusted or not.
414
415 - :ghc-flag:`-XUnsafe` — Marks the module being compiled as unsafe so that modules
416   compiled using :ghc-flag:`-XSafe` can't import it. You may want to explicitly mark a
417   module unsafe when it exports internal constructors that can be used to
418   violate invariants.
419
420 While these are flags, they also correspond to Safe Haskell module types
421 that a module can have. You can think of using these as declaring an
422 explicit contract (or type) that a module must have. If it is invalid,
423 then compilation will fail. GHC will also infer the correct type for
424 Safe Haskell, please refer to section :ref:`safe-inference` for more
425 details.
426
427 The procedure to check if a module is trusted or not depends on if the
428 :ghc-flag:`-fpackage-trust` flag is present. The check is similar in both cases
429 with the :ghc-flag:`-fpackage-trust` flag enabling an extra requirement for
430 trustworthy modules to be regarded as trusted.
431
432 Trust check (``-fpackage-trust`` disabled)
433 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
434
435 .. index::
436    single: trust check
437
438 A module ``M`` in a package ``P`` is trusted by a client C if and only if:
439
440 - Both of these hold:
441
442    -  The module was compiled with :ghc-flag:`-XSafe`
443    -  All of M's direct imports are trusted by C
444
445 - *or* all of these hold:
446
447    -  The module was compiled with :ghc-flag:`-XTrustworthy`
448    -  All of ``M``\'s direct *safe imports* are trusted by C
449
450 The above definition of trust has an issue. Any module can be compiled
451 with :ghc-flag:`-XTrustworthy` and it will be trusted. To control this, there is
452 an additional definition of package trust (enabled with the
453 :ghc-flag:`-fpackage-trust` flag). The point of package trust is to require that
454 the client C explicitly say which packages are allowed to contain
455 trustworthy modules. Trustworthy packages are only trusted if they
456 reside in a package trusted by C.
457
458 Trust check (``-fpackage-trust`` enabled)
459 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
460
461 .. index::
462    single: trust check
463    single: -fpackage-trust
464
465 When the :ghc-flag:`-fpackage-trust` flag is enabled, whether or not a module is
466 trusted depends on if certain packages are trusted. Package trust is
467 determined by the client C invoking GHC (i.e. you).
468
469 Specifically, a package *P is trusted* when one of these hold:
470
471 -  C's package database records that ``P`` is trusted (and no command-line
472    arguments override this)
473 -  C's command-line flags say to trust ``P`` regardless of what is recorded
474    in the package database.
475
476 In either case, C is the only authority on package trust. It is up to
477 the client to decide which `packages they trust <#safe-package-trust>`__.
478
479 When the :ghc-flag:`-fpackage-trust` flag is used a *module M from package P is
480 trusted by a client C* if and only if:
481
482 -  Both of these hold:
483
484    -  The module was compiled with :ghc-flag:`-XSafe`
485    -  All of ``M``\'s direct imports are trusted by C
486
487 -  *or* all of these hold:
488
489    -  The module was compiled with :ghc-flag:`-XTrustworthy`
490    -  All of ``M``\'s direct safe imports are trusted by C
491    -  Package ``P`` is trusted by C
492
493 For the first trust definition the trust guarantee is provided by GHC
494 through the restrictions imposed by the safe language. For the second
495 definition of trust, the guarantee is provided initially by the module
496 author. The client C then establishes that they trust the module author
497 by indicating they trust the package the module resides in. This trust
498 chain is required as GHC provides no guarantee for :ghc-flag:`-XTrustworthy`
499 compiled modules.
500
501 The reason there are two modes of checking trust is that the extra
502 requirement enabled by :ghc-flag:`-fpackage-trust` causes the design of Safe
503 Haskell to be invasive. Packages using Safe Haskell when the flag is
504 enabled may or may not compile depending on the state of trusted
505 packages on a user's machine. This is both fragile, and causes
506 compilation failures for everyone, even if they aren't trying to use any
507 of the guarantees provided by Safe Haskell. Disabling
508 :ghc-flag:`-fpackage-trust` by default and turning it into a flag makes Safe
509 Haskell an opt-in extension rather than an always on feature.
510
511 .. _safe-trust-example:
512
513 Example
514 ~~~~~~~
515
516 ::
517
518     Package Wuggle:
519         {-# LANGUAGE Safe #-}
520         module Buggle where
521             import Prelude
522             f x = ...blah...
523
524     Package P:
525         {-# LANGUAGE Trustworthy #-}
526         module M where
527             import System.IO.Unsafe
528             import safe Buggle
529
530 Suppose a client C decides to trust package ``P`` and package ``base``. Then
531 does C trust module ``M``? Well ``M`` is marked :ghc-flag:`-XTrustworthy`, so we don't
532 restrict the language. However, we still must check ``M``\'s imports:
533
534 - First, ``M`` imports ``System.IO.Unsafe``. This is an unsafe module, however
535   ``M`` was compiled with :ghc-flag:`-XTrustworthy` , so ``P``\'s author takes
536   responsibility for that import. ``C`` trusts ``P``\'s author, so this import
537   is fine.
538
539 - Second, ``M`` safe imports ``Buggle``. For this import ``P``\'s author takes
540   no responsibility for the safety, instead asking GHC to check whether
541   ``Buggle`` is trusted by ``C``. Is it?
542
543 - ``Buggle``, is compiled with ``-XSafe``, so the code is machine-checked to be
544   OK, but again under the assumption that all of ``Buggle``\'s imports are
545   trusted by ``C``. We must recursively check all imports!
546
547 - Buggle only imports ``Prelude``, which is compiled with :ghc-flag:`-XTrustworthy`.
548   ``Prelude`` resides in the ``base`` package, which ``C`` trusts, and (we'll
549   assume) all of ``Prelude``\'s imports are trusted. So ``C`` trusts
550   ``Prelude``, and so ``C`` also trusts Buggle. (While ``Prelude`` is typically
551   imported implicitly, it still obeys the same rules outlined here).
552
553 Notice that C didn't need to trust package Wuggle; the machine checking
554 is enough. C only needs to trust packages that contain :ghc-flag:`-XTrustworthy`
555 modules.
556
557 .. _trustworthy-guarantees:
558
559 Trustworthy Requirements
560 ~~~~~~~~~~~~~~~~~~~~~~~~
561
562 .. index::
563    single: trustworthy
564
565 Module authors using the :ghc-flag:`-XTrustworthy` language extension for a
566 module ``M`` should ensure that ``M``\'s public API (the symbols exposed by its
567 export list) can't be used in an unsafe manner. This mean that symbols exported
568 should respect type safety and referential transparency.
569
570 .. _safe-package-trust:
571
572 Package Trust
573 ~~~~~~~~~~~~~
574
575 .. index::
576    single: package trust
577
578 Safe Haskell gives packages a new Boolean property, that of trust.
579 Several new options are available at the GHC command-line to specify the
580 trust property of packages:
581
582 .. ghc-flag:: -trust ⟨pkg⟩
583     :shortdesc: Expose package ⟨pkg⟩ and set it to be trusted. See
584         :ref:`safe-haskell`.
585     :type: dynamic/ ``:set``
586     :category:
587
588     Exposes package ⟨pkg⟩ if it was hidden and considers it a
589     trusted package regardless of the package database.
590
591 .. ghc-flag:: -distrust ⟨pkg⟩
592     :shortdesc: Expose package ⟨pkg⟩ and set it to be distrusted. See
593         :ref:`safe-haskell`.
594     :type: dynamic/ ``:set``
595     :category:
596
597     Exposes package ⟨pkg⟩ if it was hidden and considers it
598     an untrusted package regardless of the package database.
599
600 .. ghc-flag:: -distrust-all-packages
601     :shortdesc: Distrust all packages by default. See :ref:`safe-haskell`.
602     :type: dynamic/ ``:set``
603     :category:
604
605     Considers all packages distrusted unless they are
606     explicitly set to be trusted by subsequent command-line options.
607
608 To set a package's trust property in the package database please refer
609 to :ref:`packages`.
610
611 .. _safe-inference:
612
613 Safe Haskell Inference
614 ----------------------
615
616 .. index::
617    single: safe inference
618
619 In the case where a module is compiled without one of :ghc-flag:`-XSafe`,
620 :ghc-flag:`-XTrustworthy` or :ghc-flag:`-XUnsafe` being used, GHC will try to figure out
621 itself if the module can be considered safe. This safety inference will
622 never mark a module as trustworthy, only as either unsafe or as safe.
623 GHC uses a simple method to determine this for a module M: If M would
624 compile without error under the :ghc-flag:`-XSafe` flag, then M is marked as
625 safe. Otherwise, it is marked as unsafe.
626
627 When should you use Safe Haskell inference and when should you use an
628 explicit :ghc-flag:`-XSafe` flag? The later case should be used when you have a
629 hard requirement that the module be safe. This is most useful for the
630 :ref:`safe-use-cases` of Safe Haskell: running untrusted code. Safe
631 inference is meant to be used by ordinary Haskell programmers. Users who
632 probably don't care about Safe Haskell.
633
634 Haskell library authors have a choice. Most should just use Safe
635 inference. Assuming you avoid any unsafe features of the language then
636 your modules will be marked safe. Inferred vs. Explicit has the
637 following trade-offs:
638
639 - *Inferred* — This works well and adds no dependencies on the Safe Haskell type
640   of any modules in other packages. It does mean that the Safe Haskell type of
641   your own modules could change without warning if a dependency changes. One
642   way to deal with this is through the use of :ref:`Safe Haskell warning flags
643   <safe-flag-summary>` that will warn if GHC infers a Safe Haskell type
644   different from expected.
645
646 - *Explicit* — This gives your library a stable Safe Haskell type that others
647   can depend on. However, it will increase the chance of compilation failure
648   when your package dependencies change.
649
650 .. _safe-flag-summary:
651
652 Safe Haskell Flag Summary
653 -------------------------
654
655 .. index::
656    single: Safe Haskell flags
657
658 In summary, Safe Haskell consists of the following three language flags:
659
660 .. ghc-flag:: -XSafe
661     :shortdesc: Enable the :ref:`Safe Haskell <safe-haskell>` Safe mode.
662     :type: dynamic
663     :category:
664
665     :since: 7.2.1
666
667     Restricts the module to the safe language. All of the module's
668     direct imports must be trusted, but the module itself need not
669     reside in a trusted package, because the compiler vouches for its
670     trustworthiness. The "safe" keyword is allowed but meaningless in
671     import statements, as regardless, every import is required to be
672     safe.
673
674     - *Module Trusted* — Yes
675     - *Haskell Language* — Restricted to Safe Language
676     - *Imported Modules* — All forced to be safe imports, all must be trusted.
677
678 .. ghc-flag:: -XTrustworthy
679     :shortdesc: Enable the :ref:`Safe Haskell <safe-haskell>` Trustworthy mode.
680     :type: dynamic
681     :category:
682
683     :since: 7.2.1
684
685     This establishes that the module is trusted, but the guarantee is
686     provided by the module's author. A client of this module then
687     specifies that they trust the module author by specifying they trust
688     the package containing the module. :ghc-flag:`-XTrustworthy` doesn't restrict the
689     module to the safe language. It does however restrict the resolution of
690     overlapping instances to only allow :ref:`safe overlapping instances
691     <safe-overlapping-instances>`. It also allows the use of the safe import
692     keyword.
693
694     - *Module Trusted*  — Yes.
695     - *Module Trusted*  (:ghc-flag:`-fpackage-trust` enabled) — Yes but only if the package
696       the module resides in is also trusted.
697     - *Haskell Language*  — Unrestricted, except only safe overlapping instances
698       allowed.
699     - *Imported Modules* — Under control of module author which ones must be
700       trusted.
701
702 .. ghc-flag:: -XUnsafe
703     :shortdesc: Enable :ref:`Safe Haskell <safe-haskell>` Unsafe mode.
704     :type: dynamic
705     :category:
706
707     :since: 7.4.1
708
709     Mark a module as unsafe so that it can't be imported by code
710     compiled with :ghc-flag:`-XSafe`. Also enable the Safe Import extension so that a
711     module can require
712     a dependency to be trusted.
713
714     - *Module Trusted* — No
715     - *Haskell Language* — Unrestricted
716     - *Imported Modules* — Under control of module author which ones must be
717       trusted.
718
719 And one general flag:
720
721 .. ghc-flag:: -fpackage-trust
722     :shortdesc: Enable :ref:`Safe Haskell <safe-haskell>` trusted package
723         requirement for trustworthy modules.
724     :type: dynamic
725     :category:
726
727     When enabled, turn on an extra check for a trustworthy module ``M``,
728     requiring the package that ``M`` resides in be considered trusted, for ``M``
729     to be considered trusted.
730
731 And three warning flags:
732
733 .. ghc-flag:: -Wunsafe
734     :shortdesc: warn if the module being compiled is regarded to be unsafe.
735         See :ref:`safe-haskell`
736     :type: dynamic
737     :reverse: -Wno-unsafe
738     :category:
739
740     Issue a warning if the module being compiled is regarded to be
741     unsafe. Should be used to check the safety type of modules when
742     using safe inference.
743
744 .. ghc-flag:: -Wsafe
745     :shortdesc: warn if the module being compiled is regarded to be safe.
746     :type: dynamic
747     :reverse: -Wno-safe
748     :category:
749
750     Issue a warning if the module being compiled is regarded to be safe.
751     Should be used to check the safety type of modules when using safe
752     inference.
753
754 .. ghc-flag:: -Wtrustworthy-safe
755     :shortdesc: warn if the module being compiled is marked as
756         :ghc-flag:`-XTrustworthy` but it could instead be marked as
757         :ghc-flag:`-XSafe`, a more informative bound.
758     :type: dynamic
759     :reverse: -Wno-safe
760     :category:
761
762     Issue a warning if the module being compiled is marked as
763     -XTrustworthy but it could instead be marked as
764     -XSafe , a more informative bound. Can be used to detect once a Safe Haskell
765     bound can be improved as dependencies are updated.
766
767 .. _safe-compilation:
768
769 Safe Compilation
770 ----------------
771
772 .. index::
773    single: safe compilation
774
775 GHC includes a variety of flags that allow arbitrary processes to be run
776 at compilation time. One such example is the
777 :ref:`custom pre-processor <pre-processor>` flag. Another is the ability of
778 Template Haskell to execute Haskell code at compilation time, including
779 IO actions. Safe Haskell *does not address this danger* (although,
780 Template Haskell is a disallowed feature).
781
782 Due to this, it is suggested that when compiling untrusted source code
783 that has had no manual inspection done, the following precautions be
784 taken:
785
786 -  Compile in a sandbox, such as a chroot or similar container
787    technology. Or simply as a user with very reduced system access.
788
789 -  Compile untrusted code with the ``-XSafe``
790    flag being specified on the command line. This will ensure that
791    modifications to the source being compiled can't disable the use of
792    the Safe Language as the command line flag takes precedence over a
793    source level pragma.
794
795 -  Ensure that all untrusted code is imported as a
796    :ref:`safe import <safe-imports>` and that the :ghc-flag:`-fpackage-trust`
797    flag (see :ref:`flag <safe-package-trust>`) is used with packages from
798    untrusted sources being marked as untrusted.
799
800 There is a more detailed discussion of the issues involved in
801 compilation safety and some potential solutions on the
802 :ghc-wiki:`GHC Wiki <SafeHaskell/SafeCompilation>`.
803
804 Additionally, the use of :ref:`annotations <annotation-pragmas>` is forbidden,
805 as that would allow bypassing Safe Haskell restrictions. See :ghc-ticket:`10826`
806 for details.