packages feed

secp256k1-haskell-3.0.0: src/Crypto/Secp256k1/Internal/Context.hs

-- | The one libsecp256k1 context of the process.
--
-- == Purpose
--
-- Every function of libsecp256k1 takes a context: an object that holds the
-- callbacks for errors and the random blinding values that protect secret key
-- operations against side-channel leakage. Earlier versions of this package
-- made the caller create one and pass it to every function. That argument
-- carried no information, since any context gives the same results, yet it
-- ran through every signature of every program built on the package. Now the
-- package keeps a single context here and uses it for everything.
--
-- == Design
--
-- * __Created on first use.__ 'globalContext' is a top-level value, so the
--   runtime evaluates it once, the first time a function needs it, and every
--   later use gets the same pointer. 'unsafePerformIO' takes a lock on the
--   value while it runs (@unsafeDupablePerformIO@ does not), so two threads
--   that arrive together cannot both create a context. The @NOINLINE@ pragma
--   keeps the compiler from copying the definition to its uses, which would
--   make a context per use.
--
-- * __Randomized once, then read-only.__ The context is seeded with 32 bytes
--   from the operating system before anything else can see it, which is what
--   libsecp256k1 recommends. After that nothing writes to it, and the C
--   library allows any number of threads to read one context at once. This is
--   why there is no way to randomize it again: that writes to the context
--   while other threads may be reading it, which is a data race, and guarding
--   against it would put a lock around every operation.
--
-- * __Never aborts.__ The illegal-argument callback is replaced with one that
--   does nothing (see @cbits/illegal_callback.c@), so an invalid argument
--   makes a C function return 0 instead of aborting the process. Two rules
--   follow for every binding that uses the context. The return value of the C
--   function must always be checked, because after a failed check its outputs
--   are undefined. And a C function that ignores the result of an internal
--   check must get validated inputs, as 'Crypto.Secp256k1.combinePubKeys'
--   does for @secp256k1_ec_pubkey_combine@.
--
-- * __Never destroyed.__ The context lives as long as the process, like any
--   other global, so it has no finalizer. The operating system reclaims it at
--   exit.
--
-- * __Hidden.__ This module is not exposed by the package. If the pointer
--   could be reached from outside, any code could randomize or destroy the
--   context, or change its callbacks, under every other user of it. The
--   modules with the raw bindings, which take a context pointer, and the one
--   that creates contexts are hidden as well, so no code outside the package
--   can make, hold or name a context at all.
--
-- == What is given up
--
-- A program can no longer have several contexts, for example one per thread
-- or one per secret, and it can no longer refresh the blinding during a long
-- run. Neither changes any result. The blinding is defence in depth on top
-- of code that is already constant-time, and seeding it once per process is
-- what the C library asks for.
module Crypto.Secp256k1.Internal.Context (globalContext) where

import Control.Exception (mask_, onException)
import Control.Monad (unless, when)
import Crypto.Secp256k1.Internal.ContextOps
  ( LCtx,
    contextCreate,
    contextDestroy,
    contextRandomize,
    illegalCallbackFunPtr,
    setIllegalCallback,
    signVerify,
  )
import Crypto.Secp256k1.Internal.ForeignTypes (isSuccess)
import Crypto.Secp256k1.Internal.Util (withRandomSeed)
import Foreign (Ptr, nullPtr)
import System.IO.Unsafe (unsafePerformIO)

-- | The context that every binding of the package uses. It is created,
-- given the illegal-argument callback that does nothing, and randomized the
-- first time it is needed, and it is only read from then on, so any number of
-- threads may use it at once. See the module header for why it is built this
-- way.
--
-- Bindings must only pass it to C functions that take a @const@ context.
-- Never pass it to @secp256k1_context_randomize@,
-- @secp256k1_context_destroy@ or a function that sets a callback.
--
-- If the context cannot be created or randomized, for example because the
-- operating system gives no entropy, the error is raised by the function that
-- needed the context, and again by every later one.
globalContext :: Ptr LCtx
globalContext = unsafePerformIO . mask_ $ do
  ctx <- contextCreate signVerify
  when (ctx == nullPtr) $ error "Could not create secp256k1 context"
  setIllegalCallback ctx illegalCallbackFunPtr nullPtr
  ret <- withRandomSeed (contextRandomize ctx) `onException` contextDestroy ctx
  unless (isSuccess ret) $ do
    contextDestroy ctx
    error "Could not randomize secp256k1 context"
  return ctx
{-# NOINLINE globalContext #-}