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 namespace JS {
  70 enum class RuntimeCode { JS, WASM };
  71 }  // namespace JS
  72
  73 /*
  74  * Used to check if a CSP instance wants to disable eval() and friends.
  75  * See JSContext::isRuntimeCodeGenEnabled() in vm/JSContext.cpp.
  76  *
  77  * `code` is the JavaScript source code passed to eval/Function, but nullptr
  78  * for Wasm.
  79  *
  80  * Returning `false` from this callback will prevent the execution/compilation
  81  * of the code.
  82  */
  83 typedef bool (*JSCSPEvalChecker)(JSContext* cx, JS::RuntimeCode kind,
  84                                  JS::HandleString code);
  85
  86 struct JSSecurityCallbacks {
  87   JSCSPEvalChecker contentSecurityPolicyAllows;
  88   JSSubsumesOp subsumes;
  89 };
  90
  91 extern JS_PUBLIC_API void JS_SetSecurityCallbacks(
  92     JSContext* cx, const JSSecurityCallbacks* callbacks);
  93
  94 extern JS_PUBLIC_API const JSSecurityCallbacks* JS_GetSecurityCallbacks(
  95     JSContext* cx);
  96
  97 /*
  98  * Code running with "trusted" principals will be given a deeper stack
  99  * allocation than ordinary scripts. This allows trusted script to run after
 100  * untrusted script has exhausted the stack. This function sets the
 101  * runtime-wide trusted principal.
 102  *
 103  * This principals is not held (via JS_HoldPrincipals/JS_DropPrincipals).
 104  * Instead, the caller must ensure that the given principals stays valid for as
 105  * long as 'cx' may point to it. If the principals would be destroyed before
 106  * 'cx', JS_SetTrustedPrincipals must be called again, passing nullptr for
 107  * 'prin'.
 108  */
 109 extern JS_PUBLIC_API void JS_SetTrustedPrincipals(JSContext* cx,
 110                                                   JSPrincipals* prin);
 111
 112 typedef void (*JSDestroyPrincipalsOp)(JSPrincipals* principals);
 113
 114 /*
 115  * Initialize the callback that is called to destroy JSPrincipals instance
 116  * when its reference counter drops to zero. The initialization can be done
 117  * only once per JS runtime.
 118  */
 119 extern JS_PUBLIC_API void JS_InitDestroyPrincipalsCallback(
 120     JSContext* cx, JSDestroyPrincipalsOp destroyPrincipals);
 121
 122 /*
 123  * Read a JSPrincipals instance from the given |reader| and initialize the out
 124  * paratemer |outPrincipals| to the JSPrincipals instance read.
 125  *
 126  * Return false on failure, true on success. The |outPrincipals| parameter
 127  * should not be modified if false is returned.
 128  *
 129  * The caller is not responsible for calling JS_HoldPrincipals on the resulting
 130  * JSPrincipals instance, the JSReadPrincipalsOp must increment the refcount of
 131  * the resulting JSPrincipals on behalf of the caller.
 132  */
 133 using JSReadPrincipalsOp = bool (*)(JSContext* cx,
 134                                     JSStructuredCloneReader* reader,
 135                                     JSPrincipals** outPrincipals);
 136
 137 /*
 138  * Initialize the callback that is called to read JSPrincipals instances from a
 139  * buffer. The initialization can be done only once per JS runtime.
 140  */
 141 extern JS_PUBLIC_API void JS_InitReadPrincipalsCallback(
 142     JSContext* cx, JSReadPrincipalsOp read);
 143
 144 namespace JS {
 145
 146 class MOZ_RAII AutoHoldPrincipals {
 147   JSContext* cx_;
 148   JSPrincipals* principals_ = nullptr;
 149
 150  public:
 151   explicit AutoHoldPrincipals(JSContext* cx, JSPrincipals* principals = nullptr)
 152       : cx_(cx) {
 153     reset(principals);
 154   }
 155
 156   ~AutoHoldPrincipals() { reset(nullptr); }
 157
 158   void reset(JSPrincipals* principals) {
 159     if (principals) {
 160       JS_HoldPrincipals(principals);
 161     }
 162     if (principals_) {
 163       JS_DropPrincipals(cx_, principals_);
 164     }
 165     principals_ = principals;
 166   }
 167
 168   JSPrincipals* get() const { return principals_; }
 169 };
 170
 171 }  // namespace JS
 172
 173 #endif /* js_Principals_h */