// Copyright 2024 the V8 project authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef V8_OBJECTS_CASTING_H_
#define V8_OBJECTS_CASTING_H_
/**
* V8 Casting Guide
* ================
*
* This file defines the casting infrastructure for V8's tagged objects.
*
* Untrusted objects (e.g. JSObject) live in the sandbox and their Map can be
* tampered with. Trusted objects (e.g. BytecodeArray) live outside the
* sandbox in trusted space.
*
*
* 1. Release-Time Security Checks (Always-on CHECK or SBXCHECK)
* -------------------------------------------------------------
* These are required when type safety must be guaranteed at runtime under
* the V8 Sandbox attacker model.
*
* To | Untrusted Trusted
* From |
* --------------------------------------------------
* Object | CheckedCast <Impossible>*
* TrustedObject | - SbxCast
*
* * Note: A checked cast from a generic untrusted Object to a TrustedObject is
* impossible at runtime because untrusted pointers can point to arbitrary,
* unaligned memory, making a sound runtime type check impossible.
*
*
* 2. Debug-Only Validation Checks (DCHECK-only or no-op)
* ------------------------------------------------------
* These are used when type safety is statically guaranteed, validated via
* non-typesystem invariants, or when performance is critical.
*
* To | Untrusted Trusted
* From |
* --------------------------------------------------
* Object | Cast TrustedCast
* TrustedObject | - TrustedCast
* Uninitialized | UncheckedCast -
*
* * Note: "Uninitialized" refers to partially-initialized objects (e.g., during
* deserialization or construction) where CastTraits checks would fail.
*
*
* Guide to Cast Functions
* =======================
*
* Cast<T>
* -------
* The default cast for untrusted objects. Only performs a debug-only DCHECK.
* Since untrusted objects can be tampered with anyway, release-time checks
* provide no additional security.
*
* TrustedCast<T>
* --------------
* Use this for trusted objects when the type is known through external means
* but cannot be proven locally to the type system (e.g., trusted stack slots).
* Like Cast<T>, it only performs a debug-only DCHECK.
*
* WARNING: Never use TrustedCast<T> on pointers loaded from untrusted/sandbox-
* accessible fields, as an attacker can tamper with them and cause release-time
* type confusion. Use SbxCast<T> or TryCast<T> instead.
*
* SbxCast<T>
* ----------
* Use this when a trusted pointer is obtained from an untrusted source AND the
* TPT (Trusted Pointer Table) tag is shared among multiple types (1:N mapping).
* It performs an always-on SBXCHECK to prevent type-confusion attacks.
*
* CheckedCast<T>
* --------------
* Performs an always-on CHECK at release time. Use this when casting untrusted
* objects where correctness is absolutely critical.
*
* TryCast<T>
* ----------
* Performs a dynamic type check and returns a boolean. For trusted objects,
* this is specifically used for 1:N mappings where multiple instance types
* share the same TPT tag and you need to safely distinguish them at runtime.
*
* Note on 1:1 Mappings: For trusted objects with a 1:1 mapping between their
* InstanceType and their TPT tag (like BytecodeArray), no explicit cast is
* usually needed when reading from a field, as ReadTrustedPointerField<T>
* already ensures the correct type.
*
* UncheckedCast<T>
* ----------------
* Performs a raw cast with zero compile-time or runtime checks. Used when the
* object is partially initialized (so Is<T> checks would fail), or when the
* type is already proven.
*
* GCSafeCast<T>
* -------------
* Performs a debug-only GC-aware type check. Used only within garbage
* collection code paths.
*/
#include <type_traits>
#include "include/v8-source-location.h"
#include "src/base/logging.h"
#include "src/objects/tagged.h"
#include "src/sandbox/check.h"
namespace v8::internal {
// CastTraits<T> is a type trait that defines type checking behaviour for
// tagged object casting. The expected specialization is:
//
// template<>
// struct CastTraits<SomeObject> {
// template<typename From>
// static bool AllowFrom(Tagged<From> value) {
// return IsSomeObject(value);
// }
// };
//
// or, likely, just specializations of AllowFrom for Object and HeapObject,
// under the assumption that the HeapObject implementation is the same for all
// HeapObjects and the Object implementation has additional overhead in Smi
// checks.
//
// struct CastTraits<Object> {
// static bool AllowFrom(Tagged<HeapObject> value) {
// return IsSomeObject(value);
// }
// static bool AllowFrom(Tagged<Object> value) {
// return IsSomeObject(value);
// }
// };
//
template <typename To>
struct CastTraits;
class Oddball;
template <typename T>
concept NotGCedType = !std::is_base_of_v<HeapObject, T>;
// `Is<T>(value)` checks whether `value` is a tagged object of type `T`.
template <typename T, typename U>
inline bool Is(Tagged<U> value) {
return CastTraits<T>::AllowFrom(value);
}
template <typename T>
inline bool Is(const HeapObject* obj) {
return Is<T>(Tagged<HeapObject>(obj));
}
template <typename T, typename U>
inline bool Is(IndirectHandle<U> value);
template <typename T, typename U>
inline bool Is(DirectHandle<U> value);
// Is<T> checks for MaybeHandles are forbidden -- you need to first convert to
// a Handle with ToHandle or ToHandleChecked.
template <typename T, typename U>
bool Is(MaybeIndirectHandle<U> value) = delete;
template <typename T, typename U>
bool Is(MaybeDirectHandle<U> value) = delete;
// C++ versions for `Is<T>` that accept pointers and references.
template <typename To, typename From>
requires NotGCedType<To>
bool Is(const From& value) {
return CastTraits<std::remove_const_t<To>>::AllowFrom(value);
}
template <typename To, typename From>
requires NotGCedType<To>
bool Is(From& value) {
return Is<To>(const_cast<const From&>(value));
}
template <typename To, typename From>
requires NotGCedType<To>
bool Is(const From* value) {
return value && Is<To>(*value);
}
template <typename To, typename From>
requires NotGCedType<To>
bool Is(From* value) {
return value && Is<To>(*static_cast<const From*>(value));
}
// `UncheckedCast<T>(value)` casts `value` to a tagged object of type `T`,
// without checking the type of value.
template <typename To, typename From>
inline Tagged<To> UncheckedCast(Tagged<From> value) {
return Tagged<To>(value.ptr());
}
template <typename To, typename From>
inline IndirectHandle<To> UncheckedCast(IndirectHandle<From> value);
template <typename To, typename From>
inline MaybeIndirectHandle<To> UncheckedCast(MaybeIndirectHandle<From> value);
template <typename To, typename From>
inline DirectHandle<To> UncheckedCast(DirectHandle<From> value);
template <typename To, typename From>
inline MaybeDirectHandle<To> UncheckedCast(MaybeDirectHandle<From> value);
// HasCastImplementation is a concept that checks for the existence of
// Is<To>(Holder<From>) and UncheckedCast<To>(Holder<From>).
template <template <typename> class Holder, typename To, typename From>
concept HasTryCastImplementation = requires(Holder<From> value) {
{ Is<To>(value) } -> std::same_as<bool>;
{ UncheckedCast<To>(value) } -> std::same_as<Holder<To>>;
};
template <typename Derived, typename Base>
concept HasCppRefTryCastImplementation =
NotGCedType<Derived> && requires(Base& value) {
{ Is<Derived>(value) } -> std::same_as<bool>;
};
template <typename Derived, typename Base>
concept HasCppPointerTryCastImplementation =
NotGCedType<Derived> && requires(Base* value) {
{ Is<Derived>(value) } -> std::same_as<bool>;
};
// `TryCast<T>(value, &out)` casts `value` to a tagged object of type `T` and
// writes the value to `out`, returning true if the cast succeeded and false if
// it failed.
template <typename To, typename From, template <typename> class Holder>
requires HasTryCastImplementation<Holder, To, From>
inline bool TryCast(Holder<From> value, Holder<To>* out) {
static_assert(!is_subtype_v<To, TrustedObject> ||
is_subtype_v<From, Union<Smi, Oddball, TrustedObject>>,
"Type of untrusted objects cannot be checked reliably");
if (!Is<To>(value)) return false;
*out = UncheckedCast<To>(value);
return true;
}
template <typename Derived, typename Base>
requires HasCppRefTryCastImplementation<Derived, Base>
inline bool TryCast(Base& value, Derived** out) {
if (!Is<Derived>(value)) return false;
*out = static_cast<Derived*>(&value);
return true;
}
template <typename Derived, typename Base>
requires HasCppPointerTryCastImplementation<Derived, Base>
inline bool TryCast(Base* value, Derived** out) {
if (!Is<Derived>(value)) return false;
*out = static_cast<Derived*>(value);
return true;
}
#ifdef DEBUG
template <typename T>
bool GCAwareObjectTypeCheck(Tagged<Object> object, const Heap* heap);
#endif // DEBUG
// `GCSafeCast<T>(value)` casts `object` to a tagged object of type `T` and
// should be used when the cast can be called from within a GC. The case all
// includes a debug check that `object` is either a tagged object of type `T`,
// or one of few special cases possible during GC (see GCAwareObjectTypeCheck):
// 1) `object` was already evacuated and the forwarding address refers to a
// tagged object of type `T`.
// 2) During Scavenger, `object` is a large object.
// 3) During a conservative Scavenger, `object` is a pinned object.
template <typename T>
Tagged<T> GCSafeCast(Tagged<Object> object, const Heap* heap) {
DCHECK(GCAwareObjectTypeCheck<T>(object, heap));
return UncheckedCast<T>(object);
}
// Check if a value holder is null -- used for Cast DCHECKs, so that null
// handles pass the check.
template <typename T, typename U>
inline bool NullOrIs(Tagged<U> value) {
// Raw tagged values are not allowed to be null, just check Is<T>.
return Is<T>(value);
}
template <typename T, typename U>
inline bool NullOrIs(IndirectHandle<U> value) {
return value.is_null() || Is<T>(value);
}
template <typename T, typename U>
inline bool NullOrIs(DirectHandle<U> value) {
return value.is_null() || Is<T>(value);
}
template <typename T, typename U>
inline bool NullOrIs(MaybeIndirectHandle<U> value) {
IndirectHandle<U> handle;
return !value.ToHandle(&handle) || Is<T>(handle);
}
template <typename T, typename U>
inline bool NullOrIs(MaybeDirectHandle<U> value) {
DirectHandle<U> handle;
return !value.ToHandle(&handle) || Is<T>(handle);
}
template <typename Derived, typename Base>
bool NullOrIs(Base& value) {
return Is<Derived>(value);
}
template <typename Derived, typename Base>
bool NullOrIs(Base* value) {
return !value || Is<Derived>(*value);
}
// HasCastImplementation is a concept that checks for the existence of
// NullOrIs<To>(Holder<From>) and UncheckedCast<To>(Holder<From>).
template <template <typename> class Holder, typename To, typename From>
concept HasCastImplementation = requires(Holder<From> value) {
{ NullOrIs<To>(value) } -> std::same_as<bool>;
{ UncheckedCast<To>(value) } -> std::same_as<Holder<To>>;
};
template <typename Derived, typename Base>
concept HasCppRefCastImplementation =
NotGCedType<Derived> && requires(Base& value) {
{ Is<Derived>(value) } -> std::same_as<bool>;
};
template <typename Derived, typename Base>
concept HasCppPointerCastImplementation =
NotGCedType<Derived> && requires(Base* value) {
{ Is<Derived>(value) } -> std::same_as<bool>;
};
// `TrustedCast<T>(value)` casts `value` to a tagged object of type `T`, only
// doing a debug check that `value` is a tagged object of type `T`. Down-casts
// to trusted objects are allowed for callers which already ensured their
// correctness. Null-valued holders are allowed.
//
// WARNING: This must NEVER be used on pointers loaded from untrusted/sandbox-
// accessible fields, as an attacker can tamper with them and cause release-time
// type confusion. Use SbxCast<T> or TryCast<T> instead for those cases.
template <typename To, typename From, template <typename> class Holder>
requires HasCastImplementation<Holder, To, From>
inline Holder<To> TrustedCast(
Holder<From> value, SourceLocation loc = SourceLocation::CurrentIfDebug()) {
// Casting pointers to in-sandbox objects is allowed even with an active
// DisallowSandboxAccess scope (as casting itself doesn't access any memory).
// However, in debug builds the DCHECK below will need to access the Map of
// the object, so we need to temporarily enable sandbox access. If no
// DisallowSandboxAccess scope is active, this is a no-op.
DCHECK_WITH_SANDBOX_ACCESS_AND_MSG_AND_LOC(
NullOrIs<To>(value), V8_PRETTY_FUNCTION_VALUE_OR("Cast type check"), loc);
return UncheckedCast<To>(value);
}
// `SbxCast<T>(value)` casts `value` to a tagged object of trusted type `T`,
// with a sandbox-only dynamic type check ensuring that `value` is a tagged
// object of type `T`. This is required for security when the object was
// obtained from an untrusted source AND the TPT tag is shared among multiple
// types (1:N mapping). Null-valued holders are allowed.
template <typename To, typename From, template <typename> class Holder>
requires HasCastImplementation<Holder, To, From>
inline Holder<To> SbxCast(
Holder<From> value, SourceLocation loc = SourceLocation::CurrentIfDebug()) {
// Under the attacker model of the sandbox we cannot trust the type of
// in-sandbox objects for sandbox checks as these objects can be arbitrarily
// tampered with.
static_assert(is_subtype_v<To, TrustedObject>);
static_assert(is_subtype_v<From, Union<Smi, Oddball, TrustedObject>>,
"Type of untrusted objects cannot be checked reliably");
DCHECK_WITH_MSG_AND_LOC(NullOrIs<To>(value),
V8_PRETTY_FUNCTION_VALUE_OR("Cast type check"), loc);
SBXCHECK(NullOrIs<To>(value));
return UncheckedCast<To>(value);
}
template <typename Derived, typename Base>
requires HasCppRefCastImplementation<Derived, Base>
inline Derived& SbxCast(Base& from,
SourceLocation loc = SourceLocation::CurrentIfDebug()) {
DCHECK_WITH_MSG_AND_LOC(NullOrIs<Derived>(from),
V8_PRETTY_FUNCTION_VALUE_OR("Cast type check"), loc);
SBXCHECK(NullOrIs<Derived>(from));
return static_cast<Derived&>(from);
}
template <typename Derived, typename Base>
requires HasCppPointerCastImplementation<Derived, Base>
inline Derived* SbxCast(Base* from,
SourceLocation loc = SourceLocation::CurrentIfDebug()) {
DCHECK_WITH_MSG_AND_LOC(NullOrIs<Derived>(from),
V8_PRETTY_FUNCTION_VALUE_OR("Cast type check"), loc);
SBXCHECK(NullOrIs<Derived>(from));
return static_cast<Derived*>(from);
}
// `CheckedCast<T>(value)` casts `value` to a tagged object of type `T`,
// with a always-on dynamic type check ensuring that `value` is a tagged object
// of type `T`. Null-valued holders are allowed.
template <typename To, typename From, template <typename> class Holder>
requires HasCastImplementation<Holder, To, From>
inline Holder<To> CheckedCast(
Holder<From> value, SourceLocation loc = SourceLocation::CurrentIfDebug()) {
DCHECK_WITH_MSG_AND_LOC(NullOrIs<To>(value),
V8_PRETTY_FUNCTION_VALUE_OR("Cast type check"), loc);
CHECK(NullOrIs<To>(value));
return UncheckedCast<To>(value);
}
template <typename Derived, typename Base>
requires HasCppRefCastImplementation<Derived, Base>
inline Derived& CheckedCast(
Base& from, SourceLocation loc = SourceLocation::CurrentIfDebug()) {
DCHECK_WITH_MSG_AND_LOC(NullOrIs<Derived>(from),
V8_PRETTY_FUNCTION_VALUE_OR("Cast type check"), loc);
CHECK(NullOrIs<Derived>(from));
return static_cast<Derived&>(from);
}
template <typename Derived, typename Base>
requires HasCppPointerCastImplementation<Derived, Base>
inline Derived* CheckedCast(
Base* from, SourceLocation loc = SourceLocation::CurrentIfDebug()) {
DCHECK_WITH_MSG_AND_LOC(NullOrIs<Derived>(from),
V8_PRETTY_FUNCTION_VALUE_OR("Cast type check"), loc);
CHECK(NullOrIs<Derived>(from));
return static_cast<Derived*>(from);
}
// `Cast<T>(value)` casts `value` to a tagged object of type `T`, with a debug
// check that `value` is a tagged object of type `T`. Null-valued holders are
// allowed. Down-casts to trusted objects are not allowed to prevent mistakes.
template <typename To, typename From, template <typename> class Holder>
requires HasCastImplementation<Holder, To, From>
inline Holder<To> Cast(Holder<From> value,
SourceLocation loc = SourceLocation::CurrentIfDebug()) {
static_assert(
!is_subtype_v<To, TrustedObject> || is_subtype_v<From, To>,
"Down-casting to trusted objects is verboten. Pick one of:\n"
"* TryCast if the use is guarded by a test\n"
" if (Trusted t; TryCast(obj, &t)) { t->foo(); }\n"
"* (Checked|Sbx)Cast if the object is expected to be of a certain type\n"
" Tagged<Trusted> t = SbxCast<Trusted>(obj);\n"
"* TrustedCast if correct by construction (or other deprecated usage)\n"
" Tagged<Trusted> t = "
"TrustedCast<Trusted>(TrustedPointerField::ReadTrustedPointerField<"
"kTrustedTag>(obj, ...));\n");
return TrustedCast<To>(value, loc);
}
// TODO(leszeks): Figure out a way to make these cast to actual pointers rather
// than Tagged.
template <typename To, typename From>
requires std::is_base_of_v<HeapObject, From>
inline Tagged<To> UncheckedCast(const From* value) {
return UncheckedCast<To>(Tagged(value));
}
template <typename To, typename From>
requires std::is_base_of_v<HeapObject, From>
inline Tagged<To> TrustedCast(const From* value) {
return TrustedCast<To>(Tagged(value));
}
template <typename To, typename From>
requires std::is_base_of_v<HeapObject, From>
inline Tagged<To> CheckedCast(const From* value) {
return CheckedCast<To>(Tagged(value));
}
template <typename To, typename From>
requires std::is_base_of_v<HeapObject, From>
inline Tagged<To> SbxCast(const From* value) {
return SbxCast<To>(Tagged(value));
}
template <typename To, typename From>
requires std::is_base_of_v<HeapObject, From>
inline Tagged<To> Cast(const From* value,
SourceLocation loc = SourceLocation::CurrentIfDebug()) {
return Cast<To>(Tagged(value), loc);
}
template <typename Derived, typename Base>
requires HasCppRefCastImplementation<Derived, Base>
inline Derived& Cast(Base& from,
SourceLocation loc = SourceLocation::CurrentIfDebug()) {
DCHECK_WITH_MSG_AND_LOC(NullOrIs<Derived>(from),
V8_PRETTY_FUNCTION_VALUE_OR("Cast type check"), loc);
return static_cast<Derived&>(from);
}
template <typename Derived, typename Base>
requires HasCppPointerCastImplementation<Derived, Base>
inline Derived* Cast(Base* from,
SourceLocation loc = SourceLocation::CurrentIfDebug()) {
DCHECK_WITH_MSG_AND_LOC(NullOrIs<Derived>(from),
V8_PRETTY_FUNCTION_VALUE_OR("Cast type check"), loc);
return static_cast<Derived*>(from);
}
// `Is<T>(maybe_weak_value)` specialization for possible weak values and strong
// target `T`, that additionally first checks whether `maybe_weak_value` is
// actually a strong value (or a Smi, which can't be weak).
template <typename T, typename U>
inline bool Is(Tagged<MaybeWeak<U>> value) {
// Cast from maybe weak to strong needs to be strong or smi.
if constexpr (!is_maybe_weak_v<T>) {
if (!value.IsStrongOrSmi()) return false;
return CastTraits<T>::AllowFrom(Tagged<U>(value.ptr()));
} else {
// Dispatches to CastTraits<MaybeWeak<T>> below.
return CastTraits<T>::AllowFrom(value);
}
}
template <typename T, typename... U>
constexpr inline bool Is(Tagged<Union<U...>> value) {
using UnionU = Union<U...>;
if constexpr (is_weak_v<UnionU>) {
return Is<T>(Tagged<Weak<HeapObject>>(value));
} else if constexpr (is_maybe_weak_v<UnionU>) {
// Cleared values are always ok.
if (value.IsCleared()) return true;
// TODO(leszeks): Skip Smi check for values that are known to not be Smi.
if (value.IsSmi()) {
return Is<T>(Tagged<Smi>(value.ptr()));
}
return Is<T>(MakeStrong(value));
} else if constexpr (is_subtype_v<UnionU, HeapObject>) {
return Is<T>(Tagged<HeapObject>(value));
} else {
static_assert(is_subtype_v<UnionU, Object>);
return Is<T>(Tagged<Object>(value));
}
}
// Specialization for weak cast targets, which first converts the incoming
// value to a strong reference and then checks if the cast to the strong T
// is allowed. Cleared weak references always return true.
template <typename T>
struct CastTraits<Weak<T>> {
template <typename U>
static bool AllowFrom(Tagged<U> value) {
if constexpr (is_weak_v<U>) {
return CastTraits<T>::AllowFrom(MakeStrong(value));
}
if constexpr (is_maybe_weak_v<U>) {
// Cleared values are always ok.
if (value.IsCleared()) return true;
// TODO(leszeks): Skip Smi check for values that are known to not be Smi.
if (value.IsSmi()) return false;
return CastTraits<T>::AllowFrom(MakeStrong(value));
} else {
// Can't cast weak to non-weak.
return false;
}
}
};
template <typename... T>
struct CastTraits<Union<T...>> {
static inline bool AllowFrom(Tagged<Object> value) {
return (Is<T>(value) || ...);
}
static inline bool AllowFrom(Tagged<HeapObject> value) {
return (Is<T>(value) || ...);
}
};
template <>
struct CastTraits<Object> {
static inline bool AllowFrom(Tagged<Object> value) { return true; }
};
template <>
struct CastTraits<Smi> {
static inline bool AllowFrom(Tagged<Object> value) { return value.IsSmi(); }
static inline bool AllowFrom(Tagged<HeapObject> value) { return false; }
};
template <>
struct CastTraits<HeapObject> {
static inline bool AllowFrom(Tagged<Object> value) {
return value.IsHeapObject();
}
static inline bool AllowFrom(Tagged<HeapObject> value) { return true; }
};
} // namespace v8::internal
#endif // V8_OBJECTS_CASTING_H_