653b74133992a5e95aa86ddc7b5f8c0832529e90
[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 users 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, lets 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, lets 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 - ``Data.Typeable`` — Hand crafted instances of the Typeable type class are not allowed
277   in Safe Haskell as this can easily be abused to unsafely coerce
278   between types. Derived instances (through the :ghc-flag:`-XDeriveDataTypeable`
279   extension) are still allowed.
280
281 - ``GHC.Generics`` — Hand crafted instances of the ``Generic`` type class are
282   not allowed in Safe Haskell. Such instances aren't strictly unsafe, but
283   there is an important invariant that a ``Generic`` instance should adhere to
284   the structure of the data type for which the instance is defined, and
285   allowing manually implemented ``Generic`` instances would break that
286   invariant. Derived instances (through the :ghc-flag:`-XDeriveGeneric`
287   extension) are still allowed. Note that the only allowed
288   :ref:`deriving strategy <deriving-strategies>` for deriving ``Generic`` under
289   Safe Haskell is ``stock``, as another strategy (e.g., ``anyclass``) would
290   produce an instance that violates the invariant.
291
292   Refer to the
293   :ref:`generic programming <generic-programming>` section for more details.
294
295 .. _safe-overlapping-instances:
296
297 Safe Overlapping Instances
298 ~~~~~~~~~~~~~~~~~~~~~~~~~~
299
300 Due to the semantic consistency guarantee of Safe Haskell, we must
301 restrict the function of overlapping instances. We don't restrict their
302 ability to be defined, as this is a global property and not something we
303 can determine by looking at a single module. Instead, when a module
304 calls a function belonging to a type-class, we check that the instance
305 resolution done is considered 'safe'. This check is enforced for modules
306 compiled with both ``-XSafe`` and ``-XTrustworthy``.
307
308 More specifically, consider the following modules:
309
310 ::
311
312             {-# LANGUAGE Safe #-}
313             module Class (TC(..)) where
314               class TC a where { op :: a -> String }
315
316             {-# LANGUAGE Safe #-}
317             module Dangerous (TC(..)) where
318               import Class
319
320               instance
321                 {-# OVERLAPS #-}
322                 TC [Int] where { op _ = "[Int]" }
323
324             {-# LANGUAGE Safe #-}
325             module TCB_Runner where
326               import Class
327               import Dangerous
328
329               instance
330                 TC [a] where { op _ = "[a]" }
331
332               f :: String
333               f = op ([1,2,3,4] :: [Int])
334
335 Both module ``Class`` and module ``Dangerous`` will compile under :ghc-flag:`-XSafe`
336 without issue. However, in module ``TCB_Runner``, we must check if the call
337 to ``op`` in function ``f`` is safe.
338
339 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 without importing the module. This is the Safe Haskell property known as
342 *semantic consistency*.
343
344 In our situation, module ``TCB_Runner`` compiles fine without importing
345 module ``Dangerous``. So when deciding which instance to use for the call to
346 ``op``, if we determine the instance ``TC [Int]`` from module Dangerous
347 is the most specific, this is unsafe. This prevents code written by
348 third-parties we don't trust (which is compiled using ``-XSafe`` in Safe
349 Haskell) from changing the behaviour of our existing code.
350
351 Specifically, we apply the following rule to determine if a type-class
352 method call is *unsafe* when overlapping instances are involved:
353
354 -  Most specific instance, ``Ix``, defined in an ``-XSafe`` compiled module.
355 -  ``Ix`` is an orphan instance or a multi-parameter-type-class.
356 -  At least one overlapped instance, ``Iy``, is both:
357
358    -  From a different module than ``Ix``
359    -  ``Iy`` is not marked ``OVERLAPPABLE``
360
361 This is a slightly involved heuristic, but captures the situation of an
362 imported module ``N`` changing the behaviour of existing code. For example,
363 if the second condition isn't violated, then the module author ``M`` must
364 depend either on a type-class or type defined in ``N``.
365
366 When an particular type-class method call is considered unsafe due to
367 overlapping instances, and the module being compiled is using :ghc-flag:`-XSafe`
368 or :ghc-flag:`-XTrustworthy`, then compilation will fail. For :ghc-flag:`-XUnsafe`, no
369 restriction is applied, and for modules using safe inference, they will
370 be inferred unsafe.
371
372 .. _safe-imports:
373
374 Safe Imports
375 ------------
376
377 .. index::
378    single: safe imports
379
380 Safe Haskell enables a small extension to the usual import syntax of
381 Haskell, adding a ``safe`` keyword:
382
383 ::
384
385     impdecl -> import [safe] [qualified] modid [as modid] [impspec]
386
387 When used, the module being imported with the safe keyword must be a
388 trusted module, otherwise a compilation error will occur. The safe
389 import extension is enabled by either of the ``-XSafe`` , ``-XTrustworthy`` , or
390 ``-XUnsafe`` flags. When the ``-XSafe`` flag is used, the ``safe`` keyword is
391 allowed but meaningless, as every import is treated as a safe import.
392
393 .. _safe-trust:
394
395 Trust and Safe Haskell Modes
396 ----------------------------
397
398 .. index::
399    single: safe haskell trust
400    single: trust
401
402 Safe Haskell introduces the following three language flags:
403
404 - :ghc-flag:`-XSafe` — Enables the safe language dialect, asking GHC to guarantee trust.
405   The safe language dialect requires that all imports be trusted or a
406   compilation error will occur. Safe Haskell will also infer this safety type
407   for modules automatically when possible. Please refer to section
408   :ref:`safe-inference` for more details of this.
409
410 - :ghc-flag:`-XTrustworthy` — Means that while this module may invoke unsafe functions
411   internally, the module's author claims that it exports an API that can't be
412   used in an unsafe way. This doesn't enable the safe language. It does however
413   restrict the resolution of overlapping instances to only allow :ref:`safe
414   overlapping instances <safe-overlapping-instances>`. The trust guarantee is
415   provided by the module author, not GHC. An import statement with the ``safe``
416   keyword results in a compilation error if the imported module is not trusted.
417   An import statement without the keyword behaves as usual and can import any
418   module whether trusted or not.
419
420 - :ghc-flag:`-XUnsafe` — Marks the module being compiled as unsafe so that modules
421   compiled using :ghc-flag:`-XSafe` can't import it. You may want to explicitly mark a
422   module unsafe when it exports internal constructors that can be used to
423   violate invariants.
424
425 While these are flags, they also correspond to Safe Haskell module types
426 that a module can have. You can think of using these as declaring an
427 explicit contract (or type) that a module must have. If it is invalid,
428 then compilation will fail. GHC will also infer the correct type for
429 Safe Haskell, please refer to section :ref:`safe-inference` for more
430 details.
431
432 The procedure to check if a module is trusted or not depends on if the
433 :ghc-flag:`-fpackage-trust` flag is present. The check is similar in both cases
434 with the :ghc-flag:`-fpackage-trust` flag enabling an extra requirement for
435 trustworthy modules to be regarded as trusted.
436
437 Trust check (``-fpackage-trust`` disabled)
438 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
439
440 .. index::
441    single: trust check
442
443 A module ``M`` in a package ``P`` is trusted by a client C if and only if:
444
445 - Both of these hold:
446
447    -  The module was compiled with :ghc-flag:`-XSafe`
448    -  All of M's direct imports are trusted by C
449
450 - *or* all of these hold:
451
452    -  The module was compiled with :ghc-flag:`-XTrustworthy`
453    -  All of ``M``\'s direct *safe imports* are trusted by C
454
455 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 the client C explicitly say which packages are allowed to contain
460 trustworthy modules. Trustworthy packages are only trusted if they
461 reside in a package trusted by C.
462
463 Trust check (``-fpackage-trust`` enabled)
464 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
465
466 .. index::
467    single: trust check
468    single: -fpackage-trust
469
470 When the :ghc-flag:`-fpackage-trust` flag is enabled, whether or not a module is
471 trusted depends on if certain packages are trusted. Package trust is
472 determined by the client C invoking GHC (i.e. you).
473
474 Specifically, a package *P is trusted* when one of these hold:
475
476 -  C's package database records that ``P`` is trusted (and no command-line
477    arguments override this)
478 -  C's command-line flags say to trust ``P`` regardless of what is recorded
479    in the package database.
480
481 In either case, C is the only authority on package trust. It is up to
482 the client to decide which `packages they trust <#safe-package-trust>`__.
483
484 When the :ghc-flag:`-fpackage-trust` flag is used a *module M from package P is
485 trusted by a client C* if and only if:
486
487 -  Both of these hold:
488
489    -  The module was compiled with :ghc-flag:`-XSafe`
490    -  All of ``M``\'s direct imports are trusted by C
491
492 -  *or* all of these hold:
493
494    -  The module was compiled with :ghc-flag:`-XTrustworthy`
495    -  All of ``M``\'s direct safe imports are trusted by C
496    -  Package ``P`` is trusted by C
497
498 For the first trust definition the trust guarantee is provided by GHC
499 through the restrictions imposed by the safe language. For the second
500 definition of trust, the guarantee is provided initially by the module
501 author. The client C then establishes that they trust the module author
502 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 compiled modules.
505
506 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 Haskell to be invasive. Packages using Safe Haskell when the flag is
509 enabled may or may not compile depending on the state of trusted
510 packages on a users machine. This is both fragile, and causes
511 compilation failures for everyone, even if they aren't trying to use any
512 of the guarantees provided by Safe Haskell. Disabling
513 :ghc-flag:`-fpackage-trust` by default and turning it into a flag makes Safe
514 Haskell an opt-in extension rather than an always on feature.
515
516 .. _safe-trust-example:
517
518 Example
519 ~~~~~~~
520
521 ::
522
523     Package Wuggle:
524         {-# LANGUAGE Safe #-}
525         module Buggle where
526             import Prelude
527             f x = ...blah...
528
529     Package P:
530         {-# LANGUAGE Trustworthy #-}
531         module M where
532             import System.IO.Unsafe
533             import safe Buggle
534
535 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 restrict the language. However, we still must check ``M``\'s imports:
538
539 - 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   responsibility for that import. ``C`` trusts ``P``\'s author, so this import
542   is fine.
543
544 - Second, ``M`` safe imports ``Buggle``. For this import ``P``\'s author takes
545   no responsibility for the safety, instead asking GHC to check whether
546   ``Buggle`` is trusted by ``C``. Is it?
547
548 - ``Buggle``, is compiled with ``-XSafe``, so the code is machine-checked to be
549   OK, but again under the assumption that all of ``Buggle``\'s imports are
550   trusted by ``C``. We must recursively check all imports!
551
552 - Buggle only imports ``Prelude``, which is compiled with :ghc-flag:`-XTrustworthy`.
553   ``Prelude`` resides in the ``base`` package, which ``C`` trusts, and (we'll
554   assume) all of ``Prelude``\'s imports are trusted. So ``C`` trusts
555   ``Prelude``, and so ``C`` also trusts Buggle. (While ``Prelude`` is typically
556   imported implicitly, it still obeys the same rules outlined here).
557
558 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 modules.
561
562 .. _trustworthy-guarantees:
563
564 Trustworthy Requirements
565 ~~~~~~~~~~~~~~~~~~~~~~~~
566
567 .. index::
568    single: trustworthy
569
570 Module authors using the :ghc-flag:`-XTrustworthy` language extension for a module ``M``
571 should ensure that ``M``\'s public API (the symbols exposed by its export list)
572 can't be used in an unsafe manner. This mean that symbols exported should
573 respect type safety and referential transparency.
574
575 .. _safe-package-trust:
576
577 Package Trust
578 ~~~~~~~~~~~~~
579
580 .. index::
581    single: package trust
582
583 Safe Haskell gives packages a new Boolean property, that of trust.
584 Several new options are available at the GHC command-line to specify the
585 trust property of packages:
586
587 .. ghc-flag:: -trust ⟨pkg⟩
588
589    Exposes package ⟨pkg⟩ if it was hidden and considers it a
590    trusted package regardless of the package database.
591
592 .. ghc-flag:: -distrust ⟨pkg⟩
593
594    Exposes package ⟨pkg⟩ if it was hidden and considers it
595    an untrusted package regardless of the package database.
596
597 .. ghc-flag:: -distrust-all-packages
598
599    Considers all packages distrusted unless they are
600    explicitly set to be trusted by subsequent command-line options.
601
602 To set a package's trust property in the package database please refer
603 to :ref:`packages`.
604
605 .. _safe-inference:
606
607 Safe Haskell Inference
608 ----------------------
609
610 .. index::
611    single: safe inference
612
613 In the case where a module is compiled without one of :ghc-flag:`-XSafe`,
614 :ghc-flag:`-XTrustworthy` or :ghc-flag:`-XUnsafe` being used, GHC will try to figure out
615 itself if the module can be considered safe. This safety inference will
616 never mark a module as trustworthy, only as either unsafe or as safe.
617 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 safe. Otherwise, it is marked as unsafe.
620
621 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 hard requirement that the module be safe. This is most useful for the
624 :ref:`safe-use-cases` of Safe Haskell: running untrusted code. Safe
625 inference is meant to be used by ordinary Haskell programmers. Users who
626 probably don't care about Safe Haskell.
627
628 Haskell library authors have a choice. Most should just use Safe
629 inference. Assuming you avoid any unsafe features of the language then
630 your modules will be marked safe. Inferred vs. Explicit has the
631 following trade-offs:
632
633 - *Inferred* — This works well and adds no dependencies on the Safe Haskell type
634   of any modules in other packages. It does mean that the Safe Haskell type of
635   your own modules could change without warning if a dependency changes. One
636   way to deal with this is through the use of :ref:`Safe Haskell warning flags
637   <safe-flag-summary>` that will warn if GHC infers a Safe Haskell type
638   different from expected.
639
640 - *Explicit* — This gives your library a stable Safe Haskell type that others
641   can depend on. However, it will increase the chance of compilation failure
642   when your package dependencies change.
643
644 .. _safe-flag-summary:
645
646 Safe Haskell Flag Summary
647 -------------------------
648
649 .. index::
650    single: Safe Haskell flags
651
652 In summary, Safe Haskell consists of the following three language flags:
653
654 .. ghc-flag:: -XSafe
655
656     :since: 7.2.1
657
658     Restricts the module to the safe language. All of the module's
659     direct imports must be trusted, but the module itself need not
660     reside in a trusted package, because the compiler vouches for its
661     trustworthiness. The "safe" keyword is allowed but meaningless in
662     import statements, as regardless, every import is required to be
663     safe.
664
665     - *Module Trusted* — Yes
666     - *Haskell Language* — Restricted to Safe Language
667     - *Imported Modules* — All forced to be safe imports, all must be trusted.
668
669 .. ghc-flag:: -XTrustworthy
670
671     :since: 7.2.1
672
673     This establishes that the module is trusted, but the guarantee is
674     provided by the module's author. A client of this module then
675     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     module to the safe language. It does however restrict the resolution of
678     overlapping instances to only allow :ref:`safe overlapping instances
679     <safe-overlapping-instances>`. It also allows the use of the safe import
680     keyword.
681
682     - *Module Trusted*  — Yes.
683     - *Module Trusted*  (:ghc-flag:`-fpackage-trust` enabled) — Yes but only if the package
684       the module resides in is also trusted.
685     - *Haskell Language*  — Unrestricted, except only safe overlapping instances
686       allowed.
687     - *Imported Modules* — Under control of module author which ones must be
688       trusted.
689
690 .. ghc-flag:: -XUnsafe
691
692     :since: 7.4.1
693
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     module can require
697     a dependency to be trusted.
698
699     - *Module Trusted* — No
700     - *Haskell Language* — Unrestricted
701     - *Imported Modules* — Under control of module author which ones must be
702       trusted.
703
704 And one general flag:
705
706 .. ghc-flag:: -fpackage-trust
707     When enabled, turn on an extra check for a trustworthy module ``M``,
708     requiring the package that ``M`` resides in be considered trusted, for ``M``
709     to be considered trusted.
710
711 And three warning flags:
712
713 .. ghc-flag:: -Wunsafe
714
715     Issue a warning if the module being compiled is regarded to be
716     unsafe. Should be used to check the safety type of modules when
717     using safe inference.
718
719 .. ghc-flag:: -Wsafe
720
721     Issue a warning if the module being compiled is regarded to be safe.
722     Should be used to check the safety type of modules when using safe
723     inference.
724
725 .. ghc-flag:: -Wtrustworthy-safe
726
727     Issue a warning if the module being compiled is marked as
728     -XTrustworthy but it could instead be marked as
729     -XSafe , a more informative bound. Can be used to detect once a Safe Haskell
730     bound can be improved as dependencies are updated.
731
732 .. _safe-compilation:
733
734 Safe Compilation
735 ----------------
736
737 .. index::
738    single: safe compilation
739
740 GHC includes a variety of flags that allow arbitrary processes to be run
741 at compilation time. One such example is the
742 :ref:`custom pre-processor <pre-processor>` flag. Another is the ability of
743 Template Haskell to execute Haskell code at compilation time, including
744 IO actions. Safe Haskell *does not address this danger* (although,
745 Template Haskell is a disallowed feature).
746
747 Due to this, it is suggested that when compiling untrusted source code
748 that has had no manual inspection done, the following precautions be
749 taken:
750
751 -  Compile in a sandbox, such as a chroot or similar container
752    technology. Or simply as a user with very reduced system access.
753
754 -  Compile untrusted code with the ``-XSafe``
755    flag being specified on the command line. This will ensure that
756    modifications to the source being compiled can't disable the use of
757    the Safe Language as the command line flag takes precedence over a
758    source level pragma.
759
760 -  Ensure that all untrusted code is imported as a
761    :ref:`safe import <safe-imports>` and that the :ghc-flag:`-fpackage-trust`
762    flag (see :ref:`flag <safe-package-trust>`) is used with packages from
763    untrusted sources being marked as untrusted.
764
765 There is a more detailed discussion of the issues involved in
766 compilation safety and some potential solutions on the
767 :ghc-wiki:`GHC Wiki <SafeHaskell/SafeCompilation>`.
768
769 Additionally, the use of :ref:`annotations <annotation-pragmas>` is forbidden,
770 as that would allow bypassing Safe Haskell restrictions. See :ghc-ticket:`10826`
771 for details.