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