Systems such as information flow control security, capability based security systems and DSLs for working with encrypted data.. etc can be built in the Haskell language simply as a library. However they require guarantees about the properties of the Haskell language that aren't true in the general case where uses of functions like unsafePerformIO are allowed. Safe Haskell is designed to give users enough guarantees about the safety properties of compiled code so that such secure systems can be built.

As an example lets define an interface for a plugin system where the plugin authors are untrusted, possibly malicious third-parties. We do this by restricting the plugin interface to pure functions or to a restricted IO monad that we have defined that only allows a safe subset of IO actions to be executed. We define the plugin interface here so that it requires the plugin module, Danger, to export a single computation, Danger.runMe, of type RIO (), where RIO is a new monad defined as follows:

        -- Either of the following Safe Haskell pragmas would do
        {-# LANGUAGE Trustworthy #-}
        {-# LANGUAGE Safe #-}

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

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

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

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

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

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

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

        runMe :: RIO ()
        runMe = ...
      

Before going into the Safe Haskell details, lets point out some of the reasons this design would fail without Safe Haskell:

To stop these attacks Safe Haskell can be used. This is done by compiling the RIO module with the -XTrustworthy flag and compiling the Danger module with the -XSafe flag.

The use of the -XSafe flag to compile the Danger module restricts the features of Haskell that can be used to a safe subset. This includes disallowing unsafePerformIO, Template Haskell, pure FFI functions, RULES and restricting the operation of Overlapping Instances. The -XSafe flag also restricts the modules can be imported by Danger to only those that are considered trusted. Trusted modules are those compiled with -XSafe, where GHC provides a mechanical guarantee that the code is safe. Or those modules compiled with -XTrustworthy, where the module author claims that the module is Safe.

This is why the RIO module is compiled with -XTrustworthy, to allow the Danger module to import it. The -XTrustworthy flag doesn't place any restrictions on the module like -XSafe does. Instead the module author claims that while code may use unsafe features internally, it only exposes an API that can used in a safe manner. The use of -XTrustworthy by itself marks the module as trusted. There is an issue here as -XTrustworthy may be used by an arbitrary module and module author. To control the use of trustworthy modules it is recommended to use the -fpackage-trust flag. This flag adds an extra requirement to the trust check for trustworthy modules, such that for trustworthy modules to be considered trusted, and allowed to be used in -XSafe compiled code, the client C compiling the code must tell GHC that they trust the package the trustworthy module resides in. This is essentially a way of for C to say, while this package contains trustworthy modules that can be used by untrusted modules compiled with -XSafe , I trust the author(s) of this package and trust the modules only expose a safe API. The trust of a package can be changed at any time, so if a vulnerability found in a package, C can declare that package untrusted so that any future compilation against that package would fail. For a more detailed overview of this mechanism see Section 7.26.4, “Trust and Safe Haskell Modes”.

In the example, Danger can import module RIO because RIO is marked trustworthy. Thus, Danger can make use of the rioReadFile and rioWriteFile functions to access permitted file names. The main application then imports both RIO and Danger. To run the plugin, it calls RIO.runRIO Danger.runMe within the IO monad. The application is safe in the knowledge that the only IO to ensue will be to files whose paths were approved by the pathOK test.

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

The above definition of trust has an issue. Any module can be compiled with -XTrustworthy and it will be trusted regardless of what it does. To control this there is an additional definition of package trust (enabled with the -fpackage-trust flag). The point of package trusts is to require that the client C explicitly say which packages are allowed to contain trustworthy modules. That is, C establishes that it trusts a package P and its author and so trust the modules in P that use -XTrustworthy. When package trust is enabled, any modules that are considered trustworthy but reside in a package that isn't trusted are not considered trusted. A more formal definition is given in the next section.

When the -fpackage-trust flag is enabled, whether or not a module is trusted depends on a notion of trust for packages, which is determined by the client C invoking GHC (i.e. you). A package P is trusted when one of these hold:

In either case, C is the only authority on package trust. It is up to the client to decide which packages they trust.

When the -fpackage-trust flag is used a module M from package P is trusted by a client C if and only if:

For the first trust definition the trust guarantee is provided by GHC through the restrictions imposed by the safe language. For the second definition of trust, the guarantee is provided initially by the module author. The client C then establishes that they trust the module author by indicating they trust the package the module resides in. This trust chain is required as GHC provides no guarantee for -XTrustworthy compiled modules.

The reason there are two modes of checking trust is that the extra requirement enabled by -fpackage-trust causes the design of Safe Haskell to be invasive. Packages using Safe Haskell when the flag is enabled may or may not compile depending on the state of trusted packages on a users machine. A maintainer of a package foo that uses Safe Haskell so that security conscious Haskellers can use foo now may have other users of foo who don't know or care about Safe Haskell complaining about compilation problems they are having with foobecause a package barthat foo requires, isn't trusted on their machine. In this sense, the -fpackage-trust flag can be thought of as a flag to properly turn on Safe Haskell while without it, it's operating in a covert fashion.

Having the -fpackage-trust flag also nicely unifies the semantics of how Safe Haskell works when used explicitly and how modules are inferred as safe.

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

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

Suppose a client C decides to trust package P. Then does C trust module M? To decide, GHC must check M's imports — M imports System.IO.Unsafe. M was compiled with -XTrustworthy, so P's author takes responsibility for that import. C trusts P's author, so C trusts M to only use its unsafe imports in a safe and consistent manner with respect to the API M exposes. M also has a safe import of Buggle, so for this import P's author takes no responsibility for the safety, so GHC must check whether Buggle is trusted by C. Is it? Well, it is compiled with -XSafe, so the code in Buggle itself is machine-checked to be OK, but again under the assumption that all of Buggle's imports are trusted by C. Prelude comes from base, which C trusts, and is compiled with -XTrustworthy (While Prelude is typically imported implicitly, it still obeys the same rules outlined here). So Buggle is considered trusted.

Notice that C didn't need to trust package Wuggle; the machine checking is enough. C only needs to trust packages that contain -XTrustworthy modules.