windows-development-sandbox 1.14.0 → 1.15.0

package/native/csharp/HcsHost/FolderAccess.cs

@@ -0,0 +1,361 @@
+// What wsb-share may expose, checked here in the elevated helper without relying on the unelevated caller: the plain
+// long path of an existing folder on a fixed local drive (ShareRequest.FolderProblem), not on a subst drive, opened
+// without following links and shared in the form Windows itself reports for that handle; never Windows, Program Files,
+// ProgramData, the profile root or another user's profile, nor this tool's storage or data folder (or a folder that
+// holds them); and only a folder the unelevated user can read (and write, for a writable share) themselves.
+using System;
+using System.ComponentModel;
+using System.IO;
+using System.Runtime.InteropServices;
+using System.Text;
+
+namespace AgentSandbox.HcsHost
+{
+    public static class FolderAccess
+    {
+        private const uint FileReadAttributes = 0x80;
+        private const uint FileShareAll = 0x7;
+        /// <summary>Read and write, never delete: while the handle is held the folder cannot be renamed or replaced.</summary>
+        private const uint FileShareReadWrite = 0x3;
+        private const uint OpenExisting = 3;
+        private const uint FlagBackupSemantics = 0x02000000;
+        private const uint FlagOpenReparsePoint = 0x00200000;
+        private const uint AttributeDirectory = 0x10;
+        private const uint AttributeReparsePoint = 0x400;
+        private const uint TokenQuery = 0x0008;
+        private const uint TokenDuplicate = 0x0002;
+        private const int TokenLinkedTokenClass = 19;
+        private const int SecurityIdentification = 1;
+        private const uint OwnerGroupDacl = 0x1 | 0x2 | 0x4;
+        private const uint FileGenericRead = 0x120089;
+        private const uint FileGenericWrite = 0x120116;
+        private const uint FileGenericExecute = 0x1200A0;
+        private const uint FileAllAccess = 0x1F01FF;
+        private const uint FileTraverse = 0x20;
+        private static readonly IntPtr InvalidHandle = new IntPtr(-1);
+
+        [StructLayout(LayoutKind.Sequential)]
+        private struct GenericMapping
+        {
+            public uint GenericRead;
+            public uint GenericWrite;
+            public uint GenericExecute;
+            public uint GenericAll;
+        }
+
+        [StructLayout(LayoutKind.Sequential)]
+        private struct ByHandleFileInformation
+        {
+            public uint FileAttributes;
+            public long CreationTime;
+            public long LastAccessTime;
+            public long LastWriteTime;
+            public uint VolumeSerialNumber;
+            public uint FileSizeHigh;
+            public uint FileSizeLow;
+            public uint NumberOfLinks;
+            public uint FileIndexHigh;
+            public uint FileIndexLow;
+        }
+
+        private static class NativeMethods
+        {
+            [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+            public static extern IntPtr CreateFileW(string name, uint access, uint share, IntPtr security, uint disposition, uint flags, IntPtr template);
+
+            [DllImport("kernel32.dll", SetLastError = true)]
+            public static extern bool GetFileInformationByHandle(IntPtr file, out ByHandleFileInformation info);
+
+            [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+            public static extern uint GetFinalPathNameByHandleW(IntPtr file, StringBuilder path, uint length, uint flags);
+
+            [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+            public static extern uint QueryDosDeviceW(string device, StringBuilder target, uint length);
+
+            [DllImport("kernel32.dll", SetLastError = true)]
+            public static extern bool CloseHandle(IntPtr handle);
+
+            [DllImport("kernel32.dll")]
+            public static extern IntPtr GetCurrentProcess();
+
+            [DllImport("advapi32.dll", SetLastError = true)]
+            public static extern bool OpenProcessToken(IntPtr process, uint access, out IntPtr token);
+
+            [DllImport("advapi32.dll", SetLastError = true)]
+            public static extern bool GetTokenInformation(IntPtr token, int infoClass, out IntPtr linked, int length, out int returned);
+
+            [DllImport("advapi32.dll", SetLastError = true)]
+            public static extern bool DuplicateToken(IntPtr token, int level, out IntPtr duplicate);
+
+            [DllImport("advapi32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+            public static extern bool GetFileSecurityW(string name, uint info, byte[] descriptor, uint length, out uint needed);
+
+            [DllImport("advapi32.dll", SetLastError = true)]
+            public static extern bool AccessCheck(byte[] descriptor, IntPtr token, uint desired, ref GenericMapping mapping, byte[] privileges, ref uint privilegesLength, out uint granted, out bool status);
+        }
+
+        /// <summary>
+        /// Null (with the path to share in `finalPath` and the folder still open in `held`, without delete sharing, so it
+        /// cannot be renamed or swapped for a link until the caller closes it after the share) when the folder may be
+        /// shared with Windows Sandbox; otherwise why not.
+        /// </summary>
+        public static string Problem(string path, bool readOnly, string storageRoot, string dataPath, out string finalPath, out IntPtr held)
+        {
+            finalPath = null;
+            held = IntPtr.Zero;
+            if (string.IsNullOrEmpty(storageRoot) || string.IsNullOrEmpty(dataPath))
+            {
+                return "the request must name this tool's storage and data folders (they are never shared)";
+            }
+            string problem = ShareRequest.FolderProblem(path);
+            if (problem != null)
+            {
+                return problem;
+            }
+            string folder = path.TrimEnd('\\');
+            if (IsSubst(folder.Substring(0, 2)))
+            {
+                return "the folder is on a subst drive: give its real path";
+            }
+            string real;
+            problem = Open(folder, out real, out held);
+            if (problem != null)
+            {
+                return problem;
+            }
+            problem = CheckOpened(folder, real, readOnly, storageRoot, dataPath);
+            if (problem != null)
+            {
+                Close(held);
+                held = IntPtr.Zero;
+                return problem;
+            }
+            finalPath = real;
+            return null;
+        }
+
+        private static string CheckOpened(string folder, string real, bool readOnly, string storageRoot, string dataPath)
+        {
+            string problem;
+            if (!string.Equals(real, folder, StringComparison.OrdinalIgnoreCase))
+            {
+                return "the folder's real path is " + real + ": give that one";
+            }
+            problem = DeniedProblem(real, storageRoot, dataPath);
+            if (problem != null)
+            {
+                return problem;
+            }
+            return UserAccessProblem(real, readOnly);
+        }
+
+        public static void Close(IntPtr held)
+        {
+            if (held != IntPtr.Zero && held != InvalidHandle)
+            {
+                NativeMethods.CloseHandle(held);
+            }
+        }
+
+        /// <summary>After the share: the held folder is still at `path` (null), or why not.</summary>
+        public static string MovedProblem(IntPtr held, string path)
+        {
+            string now;
+            string problem = FinalPath(held, out now);
+            if (problem != null)
+            {
+                return problem;
+            }
+            return string.Equals(now, path, StringComparison.OrdinalIgnoreCase) ? null : "the folder moved while it was being shared";
+        }
+
+        private static bool IsSubst(string drive)
+        {
+            StringBuilder target = new StringBuilder(1024);
+            if (NativeMethods.QueryDosDeviceW(drive, target, (uint)target.Capacity) == 0)
+            {
+                return true; // unknown: treated like a subst (fail closed)
+            }
+            return target.ToString().StartsWith("\\??\\", StringComparison.Ordinal);
+        }
+
+        /// <summary>
+        /// Opens the folder itself without following a link and without delete sharing (kept open in `handle`), and
+        /// says the path Windows reports for it.
+        /// </summary>
+        private static string Open(string folder, out string real, out IntPtr handle)
+        {
+            real = null;
+            handle = NativeMethods.CreateFileW(folder, FileReadAttributes, FileShareReadWrite, IntPtr.Zero, OpenExisting, FlagBackupSemantics | FlagOpenReparsePoint, IntPtr.Zero);
+            if (handle == InvalidHandle)
+            {
+                handle = IntPtr.Zero;
+                return "the folder cannot be opened (or something is renaming it): " + new Win32Exception(Marshal.GetLastWin32Error()).Message;
+            }
+            bool keep = false;
+            try
+            {
+                ByHandleFileInformation info;
+                if (!NativeMethods.GetFileInformationByHandle(handle, out info))
+                {
+                    return "the folder cannot be read: " + new Win32Exception(Marshal.GetLastWin32Error()).Message;
+                }
+                if ((info.FileAttributes & AttributeDirectory) == 0 || (info.FileAttributes & AttributeReparsePoint) != 0)
+                {
+                    return "only a plain folder (not a file or a link) can be shared";
+                }
+                string problem = FinalPath(handle, out real);
+                keep = problem == null;
+                return problem;
+            }
+            finally
+            {
+                if (!keep)
+                {
+                    NativeMethods.CloseHandle(handle);
+                    handle = IntPtr.Zero;
+                }
+            }
+        }
+
+        private static string FinalPath(IntPtr handle, out string real)
+        {
+            real = null;
+            StringBuilder sb = new StringBuilder(1024);
+            uint length = NativeMethods.GetFinalPathNameByHandleW(handle, sb, (uint)sb.Capacity, 0);
+            if (length == 0 || length >= sb.Capacity)
+            {
+                return "the folder's real path cannot be read";
+            }
+            string text = sb.ToString();
+            {
+                if (!text.StartsWith("\\\\?\\", StringComparison.Ordinal) || text.StartsWith("\\\\?\\UNC\\", StringComparison.OrdinalIgnoreCase))
+                {
+                    return "only folders on a local drive can be shared";
+                }
+                real = text.Substring(4).TrimEnd('\\');
+                return null;
+            }
+        }
+
+        private static bool Within(string parent, string child)
+        {
+            if (string.IsNullOrEmpty(parent))
+            {
+                return false;
+            }
+            string p = parent.TrimEnd('\\');
+            return string.Equals(p, child, StringComparison.OrdinalIgnoreCase) ||
+                child.StartsWith(p + "\\", StringComparison.OrdinalIgnoreCase);
+        }
+
+        /// <summary>Pure apart from the special folders: the folders that are never shared.</summary>
+        public static string DeniedProblem(string real, string storageRoot, string dataPath)
+        {
+            string[] system = new string[]
+            {
+                Environment.GetFolderPath(Environment.SpecialFolder.Windows),
+                Environment.GetFolderPath(Environment.SpecialFolder.ProgramFiles),
+                Environment.GetFolderPath(Environment.SpecialFolder.ProgramFilesX86),
+                Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData),
+            };
+            foreach (string s in system)
+            {
+                if (Within(s, real) || Within(real, s))
+                {
+                    return "system folders cannot be shared: " + real;
+                }
+            }
+            string profile = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile).TrimEnd('\\');
+            string users = Path.GetDirectoryName(profile);
+            if (Within(users, real) && !(Within(profile, real) && !string.Equals(profile, real, StringComparison.OrdinalIgnoreCase)))
+            {
+                return "only a folder inside your own profile can be shared from the users folder (never the profile itself or another user's)";
+            }
+            foreach (string own in new string[] { storageRoot, dataPath })
+            {
+                if (!string.IsNullOrEmpty(own) && (Within(own, real) || Within(real, own)))
+                {
+                    return "this tool's own storage or data folder cannot be shared: " + real;
+                }
+            }
+            return null;
+        }
+
+        /// <summary>The token of the user who asked: the unelevated half of an elevated token, else this one.</summary>
+        private static IntPtr UserToken()
+        {
+            IntPtr process;
+            if (!NativeMethods.OpenProcessToken(NativeMethods.GetCurrentProcess(), TokenQuery | TokenDuplicate, out process))
+            {
+                throw new Win32Exception(Marshal.GetLastWin32Error());
+            }
+            try
+            {
+                IntPtr linked;
+                int returned;
+                if (NativeMethods.GetTokenInformation(process, TokenLinkedTokenClass, out linked, IntPtr.Size, out returned) && linked != IntPtr.Zero)
+                {
+                    return linked;
+                }
+                IntPtr duplicate;
+                if (!NativeMethods.DuplicateToken(process, SecurityIdentification, out duplicate))
+                {
+                    throw new Win32Exception(Marshal.GetLastWin32Error());
+                }
+                return duplicate;
+            }
+            finally
+            {
+                NativeMethods.CloseHandle(process);
+            }
+        }
+
+        /// <summary>Null when the unelevated user may list (and, for a writable share, change) the folder themselves.</summary>
+        public static string UserAccessProblem(string folder, bool readOnly)
+        {
+            uint needed;
+            NativeMethods.GetFileSecurityW(folder, OwnerGroupDacl, null, 0, out needed);
+            if (needed == 0 || needed > 1024 * 1024)
+            {
+                return "the folder's permissions cannot be read";
+            }
+            byte[] descriptor = new byte[needed];
+            if (!NativeMethods.GetFileSecurityW(folder, OwnerGroupDacl, descriptor, needed, out needed))
+            {
+                return "the folder's permissions cannot be read: " + new Win32Exception(Marshal.GetLastWin32Error()).Message;
+            }
+            IntPtr token = IntPtr.Zero;
+            try
+            {
+                token = UserToken();
+                GenericMapping mapping = new GenericMapping();
+                mapping.GenericRead = FileGenericRead;
+                mapping.GenericWrite = FileGenericWrite;
+                mapping.GenericExecute = FileGenericExecute;
+                mapping.GenericAll = FileAllAccess;
+                uint desired = FileGenericRead | FileTraverse | (readOnly ? 0u : FileGenericWrite);
+                byte[] privileges = new byte[256];
+                uint privilegesLength = (uint)privileges.Length;
+                uint granted;
+                bool allowed;
+                if (!NativeMethods.AccessCheck(descriptor, token, desired, ref mapping, privileges, ref privilegesLength, out granted, out allowed))
+                {
+                    return "the folder's permissions cannot be checked: " + new Win32Exception(Marshal.GetLastWin32Error()).Message;
+                }
+                if (!allowed)
+                {
+                    return readOnly ? "you cannot read this folder yourself, so it cannot be shared" : "you cannot change this folder yourself, so it cannot be shared writable";
+                }
+                return null;
+            }
+            finally
+            {
+                if (token != IntPtr.Zero)
+                {
+                    NativeMethods.CloseHandle(token);
+                }
+            }
+        }
+    }
+}

package/native/csharp/HcsHost/Hcs.cs

@@ -63,7 +63,9 @@ namespace AgentSandbox.HcsHost
 
     public static class Hcs
     {
+        /// <summary>HcsOpenComputeSystem documents no narrower right than GENERIC_ALL for modify.</summary>
         private const uint GenericAll = 0x10000000;
+        private const uint LoadLibrarySearchSystem32 = 0x00000800;
         private const uint QueryMs = 15000;
         private const uint ChangeMs = 180000;
 
@@ -116,7 +118,7 @@ namespace AgentSandbox.HcsHost
             public static extern IntPtr LocalFree(IntPtr mem);
 
             [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
-            public static extern IntPtr LoadLibrary(string fileName);
+            public static extern IntPtr LoadLibraryEx(string fileName, IntPtr file, uint flags);
 
             [DllImport("kernel32.dll", SetLastError = true)]
             public static extern bool FreeLibrary(IntPtr module);
@@ -139,10 +141,10 @@ namespace AgentSandbox.HcsHost
             }
         }
 
-        /// <summary>Whether a DLL (computecore.dll) can be loaded at all on this PC.</summary>
+        /// <summary>Whether a DLL (computecore.dll) can be loaded at all on this PC (from System32 only).</summary>
         public static bool CanLoad(string dll)
         {
-            IntPtr module = NativeMethods.LoadLibrary(dll);
+            IntPtr module = NativeMethods.LoadLibraryEx(dll, IntPtr.Zero, LoadLibrarySearchSystem32);
             if (module == IntPtr.Zero)
             {
                 return false;
@@ -254,6 +256,32 @@ namespace AgentSandbox.HcsHost
             return WithSystem(id, ChangeMs, delegate(IntPtr system, IntPtr op) { return NativeMethods.HcsModifyComputeSystem(system, op, modifySettingRequest, IntPtr.Zero); });
         }
 
+        /// <summary>Opens a compute system and keeps the handle (Close it): checks and changes then use the same system.</summary>
+        public static int Open(string id, out IntPtr system)
+        {
+            return NativeMethods.HcsOpenComputeSystem(id, GenericAll, out system);
+        }
+
+        public static void Close(IntPtr system)
+        {
+            if (system != IntPtr.Zero)
+            {
+                NativeMethods.HcsCloseComputeSystem(system);
+            }
+        }
+
+        /// <summary>The properties of an opened system (Id, SystemType, Owner, State, ...).</summary>
+        public static HcsReply PropertiesOf(IntPtr system)
+        {
+            return Run(delegate(IntPtr op) { return NativeMethods.HcsGetComputeSystemProperties(system, op, "{\"PropertyTypes\":[]}"); }, QueryMs);
+        }
+
+        /// <summary>One ModifySettingRequest on an opened system, waiting at most `waitMs`.</summary>
+        public static HcsReply ModifyOn(IntPtr system, string modifySettingRequest, uint waitMs)
+        {
+            return Run(delegate(IntPtr op) { return NativeMethods.HcsModifyComputeSystem(system, op, modifySettingRequest, IntPtr.Zero); }, waitMs);
+        }
+
         /// <summary>Lets the virtual machine `vmId` open the file (its disk). The file must exist.</summary>
         public static HcsReply GrantVmAccess(string vmId, string filePath)
         {

package/native/csharp/HcsHost/Program.cs

@@ -1,6 +1,8 @@
 // HcsHost.exe <verb> [arguments] --out <response.json>
 // Verbs: check, enumerate, properties <id>, create <request.json>, start <id>, terminate <id>,
-//        grant-vm-access <vmId> <file>, create-vhdx <path> <maxGb>, share <request.json> (prototype).
+//        grant-vm-access <vmId> <file>, create-vhdx <path> <maxGb>, share <request.json> (our own systems),
+//        wsb-share <request.json> --sha256 <hex> (live folders on the running Windows Sandbox, WsbShare.cs),
+//        wsb-rules <enumerate.json> [id] (pure: applies WsbGuard's rules to a recorded list; asks HCS nothing).
 // The answer is one JSON file (see Json.Response); exit code 0 = ok, 1 = failed, 2 = wrong use. A create request is
 // {"id": "...", "document": "<the HCS document as a JSON string>"}. Never attaches a disk to this PC.
 using System;
@@ -23,6 +25,7 @@ namespace AgentSandbox.HcsHost
         public static int Main(string[] args)
         {
             string outFile = null;
+            string sha256 = null;
             List<string> rest = new List<string>();
             for (int i = 0; i < args.Length; i++)
             {
@@ -31,6 +34,11 @@ namespace AgentSandbox.HcsHost
                     outFile = args[i + 1];
                     i++;
                 }
+                else if (args[i] == "--sha256" && i + 1 < args.Length)
+                {
+                    sha256 = args[i + 1];
+                    i++;
+                }
                 else
                 {
                     rest.Add(args[i]);
@@ -40,7 +48,7 @@ namespace AgentSandbox.HcsHost
             int code;
             try
             {
-                code = Dispatch(rest, out response);
+                code = Dispatch(rest, sha256, out response);
             }
             catch (Exception ex)
             {
@@ -73,11 +81,11 @@ namespace AgentSandbox.HcsHost
             return reply.Ok ? ExitOk : ExitFailed;
         }
 
-        private static int Dispatch(List<string> args, out string response)
+        private static int Dispatch(List<string> args, string sha256, out string response)
         {
             if (args.Count == 0)
             {
-                return Usage(out response, "HcsHost <check|enumerate|properties|create|start|terminate|grant-vm-access|create-vhdx> ... --out file");
+                return Usage(out response, "HcsHost <check|enumerate|properties|create|start|terminate|grant-vm-access|create-vhdx|share|wsb-share|wsb-rules> ... --out file");
             }
             string verb = args[0];
             if (verb == "check")
@@ -113,6 +121,22 @@ namespace AgentSandbox.HcsHost
             {
                 return Share(args[1], out response);
             }
+            if (verb == "wsb-share" && args.Count == 2)
+            {
+                if (sha256 == null || !System.Text.RegularExpressions.Regex.IsMatch(sha256, "^[0-9A-Fa-f]{64}$"))
+                {
+                    return Usage(out response, "wsb-share <request.json> --sha256 <its SHA-256>");
+                }
+                Dictionary<string, string> values = new Dictionary<string, string>();
+                string message;
+                bool ok = WsbShare.Run(args[1], sha256, values, out message);
+                response = Json.Response(ok, 0, message, "", values);
+                return ok ? ExitOk : (message.StartsWith("Refused: ") ? ExitUsage : ExitFailed);
+            }
+            if (verb == "wsb-rules" && (args.Count == 2 || args.Count == 3))
+            {
+                return WsbRules(args[1], args.Count == 3 ? args[2] : null, out response);
+            }
             if (verb == "grant-vm-access" && args.Count == 3)
             {
                 if (Refused(Guard.IdProblem(args[1]), out response) || Refused(Guard.DiskProblem(args[2]), out response))
@@ -175,8 +199,8 @@ namespace AgentSandbox.HcsHost
         }
 
         /// <summary>
-        /// PROTOTYPE (docs/design/hcs-live-folders.md): adds or removes a vSMB share on a running system of OURS (id
-        /// prefix and Owner, as for start/terminate). Windows Sandbox's own system is refused like any other.
+        /// Adds or removes a vSMB share on a running system of OURS (id prefix and Owner, as for start/terminate).
+        /// Windows Sandbox's own system is refused like any other: that is wsb-share's, with its own rules.
         /// </summary>
         private static int Share(string requestFile, out string response)
         {
@@ -195,6 +219,30 @@ namespace AgentSandbox.HcsHost
             return FromReply(Hcs.Modify(request.Id, values["request"]), values, out response);
         }
 
+        /// <summary>The test hook for WsbGuard: its rules on a recorded enumerate answer. Never calls HCS.</summary>
+        private static int WsbRules(string file, string id, out string response)
+        {
+            FileInfo info = new FileInfo(file);
+            if (!info.Exists || info.Length > MaxRequestBytes)
+            {
+                return Usage(out response, "wsb-rules <enumerate.json> [id]");
+            }
+            string found;
+            string problem = WsbGuard.Candidate(File.ReadAllText(file, Encoding.UTF8), out found);
+            if (problem == null && id != null)
+            {
+                problem = WsbGuard.IdProblem(id) ?? WsbGuard.MatchProblem(found, id);
+            }
+            Dictionary<string, string> values = new Dictionary<string, string>();
+            values["id"] = found ?? "";
+            if (Refused(problem, out response))
+            {
+                return ExitUsage;
+            }
+            response = Json.Response(true, 0, "ok", "", values);
+            return ExitOk;
+        }
+
         /// <summary>True (with the refusal as the response) when `problem` says why the request is not allowed.</summary>
         private static bool Refused(string problem, out string response)
         {

package/native/csharp/HcsHost/Share.cs

@@ -1,8 +1,9 @@
-// Live folders (PROTOTYPE, not wired into the CLI; docs/design/hcs-live-folders.md): a vSMB share added to or removed
-// from a RUNNING compute system with HcsModifyComputeSystem. The request is built here from checked fields, never
-// passed through: only ResourcePath "VirtualMachine/Devices/VirtualSmb/Shares", only Add or Remove, a share name with
-// this tool's prefix, and fixed options (NoDirectmap always; read-only unless asked; never TakeBackupPrivilege,
-// UseShareRootIdentity, AllowedFiles or any other option that changes whose rights the guest uses).
+// Live folders (docs/design/hcs-live-folders.md): a vSMB share added to or removed from a RUNNING compute system with
+// HcsModifyComputeSystem. The request is built here from checked fields, never passed through: only ResourcePath
+// "VirtualMachine/Devices/VirtualSmb/Shares", only Add or Remove, a share name with this tool's prefix, and fixed
+// options (NoDirectmap always; read-only unless asked; never TakeBackupPrivilege, UseShareRootIdentity, AllowedFiles or
+// any other option that changes whose rights the guest uses). `share` uses it on our own systems, `wsb-share` on the
+// running Windows Sandbox (WsbShare.cs).
 using System;
 using System.Collections.Generic;
 using System.IO;
@@ -25,9 +26,23 @@ namespace AgentSandbox.HcsHost
         public string Name;
         public string Path;
         public bool ReadOnly = true;
+        /// <summary>wsb-share: this tool's storage and data folders, never shared (the data folder holds secrets\).</summary>
+        public string StorageRoot;
+        public string DataPath;
+        /// <summary>wsb-share: the Windows user who asked (must be the one running HcsHost: no other account's prompt).</summary>
+        public string UserSid;
 
         /// <summary>Reads and checks a request file. Null with `problem` set when it is not allowed.</summary>
         public static ShareRequest Read(string file, out string problem)
+        {
+            return Read(file, null, out problem);
+        }
+
+        /// <summary>
+        /// The same, and when `sha256` is given the exact bytes parsed must have that SHA-256 (a file swapped after the
+        /// elevated script checked it is caught here).
+        /// </summary>
+        public static ShareRequest Read(string file, string sha256, out string problem)
         {
             FileInfo info = new FileInfo(file);
             if (!info.Exists || info.Length > MaxRequestBytes)
@@ -35,10 +50,27 @@ namespace AgentSandbox.HcsHost
                 problem = "the request must be a file of at most 64 KB";
                 return null;
             }
+            byte[] bytes = File.ReadAllBytes(file);
+            if (bytes.Length > MaxRequestBytes)
+            {
+                problem = "the request must be a file of at most 64 KB";
+                return null;
+            }
+            if (sha256 != null && !string.Equals(Sha256Hex(bytes), sha256, StringComparison.OrdinalIgnoreCase))
+            {
+                problem = "the request file changed after it was checked";
+                return null;
+            }
             Dictionary<string, object> raw;
             try
             {
-                raw = new JavaScriptSerializer().Deserialize<Dictionary<string, object>>(File.ReadAllText(file, Encoding.UTF8));
+                string text = new UTF8Encoding(false, true).GetString(bytes).TrimStart('\uFEFF');
+                raw = new JavaScriptSerializer().Deserialize<Dictionary<string, object>>(text);
+            }
+            catch (DecoderFallbackException)
+            {
+                problem = "the request is not UTF-8";
+                return null;
             }
             catch (ArgumentException)
             {
@@ -55,6 +87,9 @@ namespace AgentSandbox.HcsHost
             string action = Text(raw, "action");
             r.Name = Text(raw, "name");
             r.Path = Text(raw, "path");
+            r.StorageRoot = Text(raw, "storageRoot");
+            r.DataPath = Text(raw, "dataPath");
+            r.UserSid = Text(raw, "userSid");
             object ro;
             if (raw != null && raw.TryGetValue("readOnly", out ro))
             {
@@ -80,6 +115,14 @@ namespace AgentSandbox.HcsHost
             return problem == null ? r : null;
         }
 
+        public static string Sha256Hex(byte[] bytes)
+        {
+            using (System.Security.Cryptography.SHA256 sha = System.Security.Cryptography.SHA256.Create())
+            {
+                return BitConverter.ToString(sha.ComputeHash(bytes)).Replace("-", "").ToLowerInvariant();
+            }
+        }
+
         private static string Text(Dictionary<string, object> raw, string key)
         {
             object value;
@@ -150,17 +193,27 @@ namespace AgentSandbox.HcsHost
         /// <summary>The ModifySettingRequest (HCS schema; learn.microsoft.com .../hcsmodifycomputesystem).</summary>
         public string ToModifySettingRequest()
         {
+            return Build(Add, Name, Add ? System.IO.Path.GetFullPath(Path.TrimEnd('\\')) : null, ReadOnly);
+        }
+
+        /// <summary>The one place a share request is written: the fixed resource path and options.</summary>
+        public static string Build(bool add, string name, string folder, bool readOnly)
+        {
+            if (name == null || !SafeName.IsMatch(name))
+            {
+                throw new ArgumentException("not one of this tool's share names");
+            }
             StringBuilder sb = new StringBuilder();
             sb.Append("{\"ResourcePath\":").Append(Json.Quote(ResourcePath));
-            sb.Append(",\"RequestType\":").Append(Json.Quote(Add ? "Add" : "Remove"));
-            sb.Append(",\"Settings\":{\"Name\":").Append(Json.Quote(Name));
-            if (Add)
+            sb.Append(",\"RequestType\":").Append(Json.Quote(add ? "Add" : "Remove"));
+            sb.Append(",\"Settings\":{\"Name\":").Append(Json.Quote(name));
+            if (add)
             {
-                sb.Append(",\"Path\":").Append(Json.Quote(System.IO.Path.GetFullPath(Path.TrimEnd('\\'))));
+                sb.Append(",\"Path\":").Append(Json.Quote(folder));
                 // hcsshim's read-only defaults (internal/uvm/vsmb.go DefaultVSMBOptions) plus NoDirectmap: a share that
                 // was never direct-mapped can be removed again while the system runs.
                 sb.Append(",\"Options\":{\"NoDirectmap\":true");
-                if (ReadOnly)
+                if (readOnly)
                 {
                     sb.Append(",\"ReadOnly\":true,\"ShareRead\":true,\"CacheIo\":true,\"PseudoOplocks\":true");
                 }