Fix more documentation wibbles
[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 module ``M``
566 should ensure that ``M``\'s public API (the symbols exposed by its export list)
567 can't be used in an unsafe manner. This mean that symbols exported should
568 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
584    Exposes package ⟨pkg⟩ if it was hidden and considers it a
585    trusted package regardless of the package database.
586
587 .. ghc-flag:: -distrust ⟨pkg⟩
588
589    Exposes package ⟨pkg⟩ if it was hidden and considers it
590    an untrusted package regardless of the package database.
591
592 .. ghc-flag:: -distrust-all-packages
593
594    Considers all packages distrusted unless they are
595    explicitly set to be trusted by subsequent command-line options.
596
597 To set a package's trust property in the package database please refer
598 to :ref:`packages`.
599
600 .. _safe-inference:
601
602 Safe Haskell Inference
603 ----------------------
604
605 .. index::
606    single: safe inference
607
608 In the case where a module is compiled without one of :ghc-flag:`-XSafe`,
609 :ghc-flag:`-XTrustworthy` or :ghc-flag:`-XUnsafe` being used, GHC will try to figure out
610 itself if the module can be considered safe. This safety inference will
611 never mark a module as trustworthy, only as either unsafe or as safe.
612 GHC uses a simple method to determine this for a module M: If M would
613 compile without error under the :ghc-flag:`-XSafe` flag, then M is marked as
614 safe. Otherwise, it is marked as unsafe.
615
616 When should you use Safe Haskell inference and when should you use an
617 explicit :ghc-flag:`-XSafe` flag? The later case should be used when you have a
618 hard requirement that the module be safe. This is most useful for the
619 :ref:`safe-use-cases` of Safe Haskell: running untrusted code. Safe
620 inference is meant to be used by ordinary Haskell programmers. Users who
621 probably don't care about Safe Haskell.
622
623 Haskell library authors have a choice. Most should just use Safe
624 inference. Assuming you avoid any unsafe features of the language then
625 your modules will be marked safe. Inferred vs. Explicit has the
626 following trade-offs:
627
628 - *Inferred* — This works well and adds no dependencies on the Safe Haskell type
629   of any modules in other packages. It does mean that the Safe Haskell type of
630   your own modules could change without warning if a dependency changes. One
631   way to deal with this is through the use of :ref:`Safe Haskell warning flags
632   <safe-flag-summary>` that will warn if GHC infers a Safe Haskell type
633   different from expected.
634
635 - *Explicit* — This gives your library a stable Safe Haskell type that others
636   can depend on. However, it will increase the chance of compilation failure
637   when your package dependencies change.
638
639 .. _safe-flag-summary:
640
641 Safe Haskell Flag Summary
642 -------------------------
643
644 .. index::
645    single: Safe Haskell flags
646
647 In summary, Safe Haskell consists of the following three language flags:
648
649 .. ghc-flag:: -XSafe
650
651     :since: 7.2.1
652
653     Restricts the module to the safe language. All of the module's
654     direct imports must be trusted, but the module itself need not
655     reside in a trusted package, because the compiler vouches for its
656     trustworthiness. The "safe" keyword is allowed but meaningless in
657     import statements, as regardless, every import is required to be
658     safe.
659
660     - *Module Trusted* — Yes
661     - *Haskell Language* — Restricted to Safe Language
662     - *Imported Modules* — All forced to be safe imports, all must be trusted.
663
664 .. ghc-flag:: -XTrustworthy
665
666     :since: 7.2.1
667
668     This establishes that the module is trusted, but the guarantee is
669     provided by the module's author. A client of this module then
670     specifies that they trust the module author by specifying they trust
671     the package containing the module. :ghc-flag:`-XTrustworthy` doesn't restrict the
672     module to the safe language. It does however restrict the resolution of
673     overlapping instances to only allow :ref:`safe overlapping instances
674     <safe-overlapping-instances>`. It also allows the use of the safe import
675     keyword.
676
677     - *Module Trusted*  — Yes.
678     - *Module Trusted*  (:ghc-flag:`-fpackage-trust` enabled) — Yes but only if the package
679       the module resides in is also trusted.
680     - *Haskell Language*  — Unrestricted, except only safe overlapping instances
681       allowed.
682     - *Imported Modules* — Under control of module author which ones must be
683       trusted.
684
685 .. ghc-flag:: -XUnsafe
686
687     :since: 7.4.1
688
689     Mark a module as unsafe so that it can't be imported by code
690     compiled with :ghc-flag:`-XSafe`. Also enable the Safe Import extension so that a
691     module can require
692     a dependency to be trusted.
693
694     - *Module Trusted* — No
695     - *Haskell Language* — Unrestricted
696     - *Imported Modules* — Under control of module author which ones must be
697       trusted.
698
699 And one general flag:
700
701 .. ghc-flag:: -fpackage-trust
702     When enabled, turn on an extra check for a trustworthy module ``M``,
703     requiring the package that ``M`` resides in be considered trusted, for ``M``
704     to be considered trusted.
705
706 And three warning flags:
707
708 .. ghc-flag:: -Wunsafe
709
710     Issue a warning if the module being compiled is regarded to be
711     unsafe. Should be used to check the safety type of modules when
712     using safe inference.
713
714 .. ghc-flag:: -Wsafe
715
716     Issue a warning if the module being compiled is regarded to be safe.
717     Should be used to check the safety type of modules when using safe
718     inference.
719
720 .. ghc-flag:: -Wtrustworthy-safe
721
722     Issue a warning if the module being compiled is marked as
723     -XTrustworthy but it could instead be marked as
724     -XSafe , a more informative bound. Can be used to detect once a Safe Haskell
725     bound can be improved as dependencies are updated.
726
727 .. _safe-compilation:
728
729 Safe Compilation
730 ----------------
731
732 .. index::
733    single: safe compilation
734
735 GHC includes a variety of flags that allow arbitrary processes to be run
736 at compilation time. One such example is the
737 :ref:`custom pre-processor <pre-processor>` flag. Another is the ability of
738 Template Haskell to execute Haskell code at compilation time, including
739 IO actions. Safe Haskell *does not address this danger* (although,
740 Template Haskell is a disallowed feature).
741
742 Due to this, it is suggested that when compiling untrusted source code
743 that has had no manual inspection done, the following precautions be
744 taken:
745
746 -  Compile in a sandbox, such as a chroot or similar container
747    technology. Or simply as a user with very reduced system access.
748
749 -  Compile untrusted code with the ``-XSafe``
750    flag being specified on the command line. This will ensure that
751    modifications to the source being compiled can't disable the use of
752    the Safe Language as the command line flag takes precedence over a
753    source level pragma.
754
755 -  Ensure that all untrusted code is imported as a
756    :ref:`safe import <safe-imports>` and that the :ghc-flag:`-fpackage-trust`
757    flag (see :ref:`flag <safe-package-trust>`) is used with packages from
758    untrusted sources being marked as untrusted.
759
760 There is a more detailed discussion of the issues involved in
761 compilation safety and some potential solutions on the
762 :ghc-wiki:`GHC Wiki <SafeHaskell/SafeCompilation>`.
763
764 Additionally, the use of :ref:`annotations <annotation-pragmas>` is forbidden,
765 as that would allow bypassing Safe Haskell restrictions. See :ghc-ticket:`10826`
766 for details.