chrome/browser/mac/code_sign_clone_manager.h - chromium/src - Git at Google

 // Copyright 2024 The Chromium Authors
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

 #ifndef CHROME_BROWSER_MAC_CODE_SIGN_CLONE_MANAGER_H_
 #define CHROME_BROWSER_MAC_CODE_SIGN_CLONE_MANAGER_H_

 #include "base/feature_list.h"
 #include "base/files/file_path.h"
 #include "base/functional/callback_helpers.h"
 #include "base/timer/timer.h"
 #include "content/public/common/main_function_params.h"

 namespace code_sign_clone_manager {

 BASE_DECLARE_FEATURE(kMacAppCodeSignClone);
 BASE_DECLARE_FEATURE(kMacAppCodeSignCloneRenameAsBundle);

 //
 // Manages a temporary copy-on-write clone of an app bundle. The temporary clone
 // crucially has its main executable replaced with a hard link to the source's
 // main executable. This is intended for use by the browser app to keep in-use
 // files available on the filesystem after a staged update. This is in service
 // of keeping the app's code signature statically valid and in agreement with
 // its dynamic code signature after a staged update. See
 // https://crbug.com/338582873 for more details.
 //
 // During initialization, the app bundle in `src_path` will be APFS
 // copy-on-write cloned to a temporary directory. The main executable in the
 // clone is then replaced with a hard link to the `src_path` main executable.
 // The hard linked main executable is crucial in passing dynamic code signature
 // validation after an update is staged. For dynamic validation, we need to keep
 // a reachable path to the main executable alive on the filesystem, which is why
 // it is hard linked. To support support static code signature validation, the
 // hard linked main executable needs to be surrounded by a bundle structure that
 // validates. The rest of the cloned files make up this bundle structure and
 // support static code signature validation.
 //
 // Creation of this clone is best effort, there are no guarantees of success.
 // Some failure cases include running the source app bundle from:
 //   * not-APFS (because filesystem clones are only supported on APFS)
 //   * a read-only filesystem (because this needs to write to the same
 //   filesystem that the app is running from)
 //   * a non-root filesystem (because the clone is built in
 //   `/private/var/folders/...`, which is on the root filesystem)
 //
 // Upon destruction, the temporary directory hosting the clone will be deleted.
 //
 // Clone creation and deletion will take place in the background and will not
 // block. Background clone creation will take place in the calling process on a
 // background thread to prevent blocking startup. Care has been taken to
 // optimize clone creation to avoid resource contention on startup. Background
 // clone deletion will take place from a helper process. This is to prevent
 // blocking browser shutdown, with the added benefit of keeping in-use files
 // available on the filesystem until the very end of the browser process.
 //
 // Cloning and hard linking the main executable was chosen as it is the least
 // expensive out of the explored options (tested with Google Chrome M125 on an
 // M1 Max Mac).
 //
 // `clonefile` + `link` the main executable: ~10ms
 // Hard linking the whole app tree: best approach ~60ms
 //   * `-[NSFileManager linkItemAtURL:toURL:error:]`: ~120ms
 //   * `base::FileEnumerator`: ~80ms
 //   * `readdir`, `getattrlistbulk`, `fts` only `stat`ing dirs: ~60ms
 //
 // In the common case, both options (`clonefile` vs. hard link-based) take up no
 // extra disk space, aside from directory entries, while `clonefile` involves
 // the least amount of touching of the disk. The only disadvantage of
 // `clonefile` is that it’s currently APFS-only. The purely hard link-based
 // approaches would be more broadly applicable (on HFS+ for example). This is
 // not a major concern given how ubiquitous APFS on macOS has become.
 //
 // Each instance of Chrome will create a new temporary clone of itself at
 // startup even if one already exists. In this way each instance of Chrome
 // maintains a reference to its specific in-use files, keeping them accessible
 // on the filesystem until exit. Once the last instance of Chrome that maintains
 // a reference to the in-use files exits and its cleanup helper runs, the files
 // will become inaccessible on the filesystem and their disk blocks will be
 // freed.
 //
 // The clone is given a ".bundle" extension to avoid Launch Services issues; see
 // https://crbug.com/381199182 for more details.
 //
 // Example path to the cloned app bundle:
 //   /private/var/folders/c4/ygf_t4gn0tx0k1y1hm32hh6w00b_4p/X/org.chromium.Chromium.code_sign_clone/code_sign_clone.tKdILk/Chromium.app.bundle
 //
 // Each clone contains an instance-specific snapshot of an on-disk
 // representation of Chrome. The bundles are verifiable by both dynamic and
 // static code signature checks.
 //
 class CodeSignCloneManager {
  public:
   using CloneCallback = base::OnceCallback<void(base::FilePath)>;

   //
   // `src_path` is the path to the app bundle to be cloned.
   //
   // `main_executable_name` is the name of the main executable to be hard
   // linked. The name must be an entry in the "Contents/MacOS" directory within
   // the `src_path`.
   //
   // `callback` is called after the clone has been created or if an error
   // occurs.
   //
   CodeSignCloneManager(const base::FilePath& src_path,
                        const base::FilePath& main_executable_name,
                        CloneCallback callback = base::DoNothing());
   CodeSignCloneManager(const CodeSignCloneManager&) = delete;
   CodeSignCloneManager& operator=(const CodeSignCloneManager&) = delete;
   ~CodeSignCloneManager();

   static void SetTemporaryDirectoryPathForTesting(const base::FilePath& path);
   static void ClearTemporaryDirectoryPathForTesting();
   static void SetDirhelperPathForTesting(const base::FilePath& path);
   static void ClearDirhelperPathForTesting();
   static base::FilePath GetCloneTemporaryDirectoryForTesting();
   bool get_needs_cleanup_for_testing() { return needs_cleanup_; }

  private:
   void Clone(const base::FilePath& src_path,
              const base::FilePath& main_executable_name,
              CloneCallback callback);
   void StartCloneExistsTimer(const base::FilePath& clone_app_path,
                              const base::FilePath& main_executable_name);
   void StopCloneExistsTimer();
   void CloneExistsTimerFire(const base::FilePath& clone_app_path,
                             const base::FilePath& main_executable_name);

   std::string unique_temp_dir_suffix_;
   base::RepeatingTimer clone_exists_timer_;
   scoped_refptr<base::SequencedTaskRunner> task_runner_;
   bool needs_cleanup_ = false;
 };

 namespace internal {

 // The entry point into the background clone cleanup process. This is not a user
 // API.
 int ChromeCodeSignCloneCleanupMain(content::MainFunctionParams main_parameters);

 //
 // Checks if a file is open more than once, globally (across all processes on a
 // host), including the calling process.
 //
 // Usage of this check is fairly niche. It does not provide any information
 // about which process has a reference to an open file. For that see
 // `proc_listpidspath` (The linked header is from macOS 14.5).
 // https://github.com/apple-oss-distributions/xnu/blob/xnu-10063.121.3/libsyscall/wrappers/libproc/libproc.h
 //
 // This function simply checks if a file is exclusively opened. Performance
 // concerns may be a reason to use this function over `proc_listpidspath`, which
 // needs to loop over the process tree.
 //
 // Note: File descriptors that have been `dup`ed or inherited only count as
 // being opened once for this check’s purpose.
 //
 enum class FileOpenMoreThanOnce {
   kNo = 0,
   kYes = 1,
   kError = 2,
 };
 FileOpenMoreThanOnce IsFileOpenMoreThanOnce(const base::FilePath& file_path);
 FileOpenMoreThanOnce IsFileOpenMoreThanOnce(int file_descriptor);

 }  // namespace internal

 }  // namespace code_sign_clone_manager

 #endif  // CHROME_BROWSER_MAC_CODE_SIGN_CLONE_MANAGER_H_
	// Copyright 2024 The Chromium Authors
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.

	#ifndef CHROME_BROWSER_MAC_CODE_SIGN_CLONE_MANAGER_H_
	#define CHROME_BROWSER_MAC_CODE_SIGN_CLONE_MANAGER_H_

	#include "base/feature_list.h"
	#include "base/files/file_path.h"
	#include "base/functional/callback_helpers.h"
	#include "base/timer/timer.h"
	#include "content/public/common/main_function_params.h"

	namespace code_sign_clone_manager {

	BASE_DECLARE_FEATURE(kMacAppCodeSignClone);
	BASE_DECLARE_FEATURE(kMacAppCodeSignCloneRenameAsBundle);

	//
	// Manages a temporary copy-on-write clone of an app bundle. The temporary clone
	// crucially has its main executable replaced with a hard link to the source's
	// main executable. This is intended for use by the browser app to keep in-use
	// files available on the filesystem after a staged update. This is in service
	// of keeping the app's code signature statically valid and in agreement with
	// its dynamic code signature after a staged update. See
	// https://crbug.com/338582873 for more details.
	//
	// During initialization, the app bundle in `src_path` will be APFS
	// copy-on-write cloned to a temporary directory. The main executable in the
	// clone is then replaced with a hard link to the `src_path` main executable.
	// The hard linked main executable is crucial in passing dynamic code signature
	// validation after an update is staged. For dynamic validation, we need to keep
	// a reachable path to the main executable alive on the filesystem, which is why
	// it is hard linked. To support support static code signature validation, the
	// hard linked main executable needs to be surrounded by a bundle structure that
	// validates. The rest of the cloned files make up this bundle structure and
	// support static code signature validation.
	//
	// Creation of this clone is best effort, there are no guarantees of success.
	// Some failure cases include running the source app bundle from:
	// * not-APFS (because filesystem clones are only supported on APFS)
	// * a read-only filesystem (because this needs to write to the same
	// filesystem that the app is running from)
	// * a non-root filesystem (because the clone is built in
	// `/private/var/folders/...`, which is on the root filesystem)
	//
	// Upon destruction, the temporary directory hosting the clone will be deleted.
	//
	// Clone creation and deletion will take place in the background and will not
	// block. Background clone creation will take place in the calling process on a
	// background thread to prevent blocking startup. Care has been taken to
	// optimize clone creation to avoid resource contention on startup. Background
	// clone deletion will take place from a helper process. This is to prevent
	// blocking browser shutdown, with the added benefit of keeping in-use files
	// available on the filesystem until the very end of the browser process.
	//
	// Cloning and hard linking the main executable was chosen as it is the least
	// expensive out of the explored options (tested with Google Chrome M125 on an
	// M1 Max Mac).
	//
	// `clonefile` + `link` the main executable: ~10ms
	// Hard linking the whole app tree: best approach ~60ms
	// * `-[NSFileManager linkItemAtURL:toURL:error:]`: ~120ms
	// * `base::FileEnumerator`: ~80ms
	// * `readdir`, `getattrlistbulk`, `fts` only `stat`ing dirs: ~60ms
	//
	// In the common case, both options (`clonefile` vs. hard link-based) take up no
	// extra disk space, aside from directory entries, while `clonefile` involves
	// the least amount of touching of the disk. The only disadvantage of
	// `clonefile` is that it’s currently APFS-only. The purely hard link-based
	// approaches would be more broadly applicable (on HFS+ for example). This is
	// not a major concern given how ubiquitous APFS on macOS has become.
	//
	// Each instance of Chrome will create a new temporary clone of itself at
	// startup even if one already exists. In this way each instance of Chrome
	// maintains a reference to its specific in-use files, keeping them accessible
	// on the filesystem until exit. Once the last instance of Chrome that maintains
	// a reference to the in-use files exits and its cleanup helper runs, the files
	// will become inaccessible on the filesystem and their disk blocks will be
	// freed.
	//
	// The clone is given a ".bundle" extension to avoid Launch Services issues; see
	// https://crbug.com/381199182 for more details.
	//
	// Example path to the cloned app bundle:
	// /private/var/folders/c4/ygf_t4gn0tx0k1y1hm32hh6w00b_4p/X/org.chromium.Chromium.code_sign_clone/code_sign_clone.tKdILk/Chromium.app.bundle
	//
	// Each clone contains an instance-specific snapshot of an on-disk
	// representation of Chrome. The bundles are verifiable by both dynamic and
	// static code signature checks.
	//
	class CodeSignCloneManager {
	public:
	using CloneCallback = base::OnceCallback<void(base::FilePath)>;

	//
	// `src_path` is the path to the app bundle to be cloned.
	//
	// `main_executable_name` is the name of the main executable to be hard
	// linked. The name must be an entry in the "Contents/MacOS" directory within
	// the `src_path`.
	//
	// `callback` is called after the clone has been created or if an error
	// occurs.
	//
	CodeSignCloneManager(const base::FilePath& src_path,
	const base::FilePath& main_executable_name,
	CloneCallback callback = base::DoNothing());
	CodeSignCloneManager(const CodeSignCloneManager&) = delete;
	CodeSignCloneManager& operator=(const CodeSignCloneManager&) = delete;
	~CodeSignCloneManager();

	static void SetTemporaryDirectoryPathForTesting(const base::FilePath& path);
	static void ClearTemporaryDirectoryPathForTesting();
	static void SetDirhelperPathForTesting(const base::FilePath& path);
	static void ClearDirhelperPathForTesting();
	static base::FilePath GetCloneTemporaryDirectoryForTesting();
	bool get_needs_cleanup_for_testing() { return needs_cleanup_; }

	private:
	void Clone(const base::FilePath& src_path,
	const base::FilePath& main_executable_name,
	CloneCallback callback);
	void StartCloneExistsTimer(const base::FilePath& clone_app_path,
	const base::FilePath& main_executable_name);
	void StopCloneExistsTimer();
	void CloneExistsTimerFire(const base::FilePath& clone_app_path,
	const base::FilePath& main_executable_name);

	std::string unique_temp_dir_suffix_;
	base::RepeatingTimer clone_exists_timer_;
	scoped_refptr<base::SequencedTaskRunner> task_runner_;
	bool needs_cleanup_ = false;
	};

	namespace internal {

	// The entry point into the background clone cleanup process. This is not a user
	// API.
	int ChromeCodeSignCloneCleanupMain(content::MainFunctionParams main_parameters);

	//
	// Checks if a file is open more than once, globally (across all processes on a
	// host), including the calling process.
	//
	// Usage of this check is fairly niche. It does not provide any information
	// about which process has a reference to an open file. For that see
	// `proc_listpidspath` (The linked header is from macOS 14.5).
	// https://github.com/apple-oss-distributions/xnu/blob/xnu-10063.121.3/libsyscall/wrappers/libproc/libproc.h
	//
	// This function simply checks if a file is exclusively opened. Performance
	// concerns may be a reason to use this function over `proc_listpidspath`, which
	// needs to loop over the process tree.
	//
	// Note: File descriptors that have been `dup`ed or inherited only count as
	// being opened once for this check’s purpose.
	//
	enum class FileOpenMoreThanOnce {
	kNo = 0,
	kYes = 1,
	kError = 2,
	};
	FileOpenMoreThanOnce IsFileOpenMoreThanOnce(const base::FilePath& file_path);
	FileOpenMoreThanOnce IsFileOpenMoreThanOnce(int file_descriptor);

	} // namespace internal

	} // namespace code_sign_clone_manager

	#endif // CHROME_BROWSER_MAC_CODE_SIGN_CLONE_MANAGER_H_