js/public/Principals.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  * vim: set ts=8 sts=2 et sw=2 tw=80:
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 /* JSPrincipals and related interfaces. */
   8
   9 #ifndef js_Principals_h
  10 #define js_Principals_h
  11
  12 #include "mozilla/Atomics.h"
  13
  14 #include <stdint.h>
  15
  16 #include "jspubtd.h"
  17
  18 struct JSStructuredCloneReader;
  19 struct JSStructuredCloneWriter;
  20
  21 struct JSPrincipals {
  22   /* Don't call "destroy"; use reference counting macros below. */
  23   mozilla::Atomic<int32_t, mozilla::SequentiallyConsistent> refcount{0};
  24
  25 #ifdef JS_DEBUG
  26   /* A helper to facilitate principals debugging. */
  27   uint32_t debugToken;
  28 #endif
  29
  30   JSPrincipals() = default;
  31
  32   void setDebugToken(uint32_t token) {
  33 #ifdef JS_DEBUG
  34     debugToken = token;
  35 #endif
  36   }
  37
  38   /*
  39    * Write the principals with the given |writer|. Return false on failure,
  40    * true on success.
  41    */
  42   virtual bool write(JSContext* cx, JSStructuredCloneWriter* writer) = 0;
  43
  44   /*
  45    * Whether the principal corresponds to a System or AddOn Principal.
  46    * Technically this also checks for an ExpandedAddonPrincipal.
  47    */
  48   virtual bool isSystemOrAddonPrincipal() = 0;
  49
  50   /*
  51    * This is not defined by the JS engine but should be provided by the
  52    * embedding.
  53    */
  54   JS_PUBLIC_API void dump();
  55 };
  56
  57 extern JS_PUBLIC_API void JS_HoldPrincipals(JSPrincipals* principals);
  58
  59 extern JS_PUBLIC_API void JS_DropPrincipals(JSContext* cx,
  60                                             JSPrincipals* principals);
  61
  62 // Return whether the first principal subsumes the second. The exact meaning of
  63 // 'subsumes' is left up to the browser. Subsumption is checked inside the JS
  64 // engine when determining, e.g., which stack frames to display in a backtrace.
  65 typedef bool (*JSSubsumesOp)(JSPrincipals* first, JSPrincipals* second);
  66
  67 /*
  68  * Used to check if a CSP instance wants to disable eval() and friends.
  69  * See GlobalObject::isRuntimeCodeGenEnabled() in vm/GlobalObject.cpp.
  70  */
  71 typedef bool (*JSCSPEvalChecker)(JSContext* cx, JS::HandleString code);
  72
  73 struct JSSecurityCallbacks {
  74   JSCSPEvalChecker contentSecurityPolicyAllows;
  75   JSSubsumesOp subsumes;
  76 };
  77
  78 extern JS_PUBLIC_API void JS_SetSecurityCallbacks(
  79     JSContext* cx, const JSSecurityCallbacks* callbacks);
  80
  81 extern JS_PUBLIC_API const JSSecurityCallbacks* JS_GetSecurityCallbacks(
  82     JSContext* cx);
  83
  84 /*
  85  * Code running with "trusted" principals will be given a deeper stack
  86  * allocation than ordinary scripts. This allows trusted script to run after
  87  * untrusted script has exhausted the stack. This function sets the
  88  * runtime-wide trusted principal.
  89  *
  90  * This principals is not held (via JS_HoldPrincipals/JS_DropPrincipals).
  91  * Instead, the caller must ensure that the given principals stays valid for as
  92  * long as 'cx' may point to it. If the principals would be destroyed before
  93  * 'cx', JS_SetTrustedPrincipals must be called again, passing nullptr for
  94  * 'prin'.
  95  */
  96 extern JS_PUBLIC_API void JS_SetTrustedPrincipals(JSContext* cx,
  97                                                   JSPrincipals* prin);
  98
  99 typedef void (*JSDestroyPrincipalsOp)(JSPrincipals* principals);
 100
 101 /*
 102  * Initialize the callback that is called to destroy JSPrincipals instance
 103  * when its reference counter drops to zero. The initialization can be done
 104  * only once per JS runtime.
 105  */
 106 extern JS_PUBLIC_API void JS_InitDestroyPrincipalsCallback(
 107     JSContext* cx, JSDestroyPrincipalsOp destroyPrincipals);
 108
 109 /*
 110  * Read a JSPrincipals instance from the given |reader| and initialize the out
 111  * paratemer |outPrincipals| to the JSPrincipals instance read.
 112  *
 113  * Return false on failure, true on success. The |outPrincipals| parameter
 114  * should not be modified if false is returned.
 115  *
 116  * The caller is not responsible for calling JS_HoldPrincipals on the resulting
 117  * JSPrincipals instance, the JSReadPrincipalsOp must increment the refcount of
 118  * the resulting JSPrincipals on behalf of the caller.
 119  */
 120 using JSReadPrincipalsOp = bool (*)(JSContext* cx,
 121                                     JSStructuredCloneReader* reader,
 122                                     JSPrincipals** outPrincipals);
 123
 124 /*
 125  * Initialize the callback that is called to read JSPrincipals instances from a
 126  * buffer. The initialization can be done only once per JS runtime.
 127  */
 128 extern JS_PUBLIC_API void JS_InitReadPrincipalsCallback(
 129     JSContext* cx, JSReadPrincipalsOp read);
 130
 131 namespace JS {
 132
 133 class MOZ_RAII AutoHoldPrincipals {
 134   JSContext* cx_;
 135   JSPrincipals* principals_ = nullptr;
 136
 137  public:
 138   explicit AutoHoldPrincipals(JSContext* cx, JSPrincipals* principals = nullptr)
 139       : cx_(cx) {
 140     reset(principals);
 141   }
 142
 143   ~AutoHoldPrincipals() { reset(nullptr); }
 144
 145   void reset(JSPrincipals* principals) {
 146     if (principals) {
 147       JS_HoldPrincipals(principals);
 148     }
 149     if (principals_) {
 150       JS_DropPrincipals(cx_, principals_);
 151     }
 152     principals_ = principals;
 153   }
 154
 155   JSPrincipals* get() const { return principals_; }
 156 };
 157
 158 }  // namespace JS
 159
 160 #endif /* js_Principals_h */