├── CBSInternals.md
├── GeneralOverview.md
├── ImageDeployment.md
└── README.md


/CBSInternals.md:
--------------------------------------------------------------------------------
  1 | # CBS Internals
  2 | 
  3 | ## Introduction
  4 | 
  5 | The last chapter introduced the servicing stack, which is the collection of parts that carry out Windows servicing. In this chapter, we will explore the servicing stack in greater depth, covering what exactly it is, how it works, and how a developer can interact with it.
  6 | 
  7 | ## WinSxS
  8 | 
  9 | The servicing stack is located in and operates on the WinSxS folder, located in `%SystemRoot%\WinSxS`. This folder has the following structure:
 10 | 
 11 |  - `Backups`, contains copies of manifests and files for critical system components
 12 |  - `Catalogs`, contains signed catalogs containing the hash of each manifest
 13 |  - `FileMaps`, contains `cdf-ms` files which hold data on the location of system files
 14 |  - `Manifests`, contains manifests for components and deployments, with the `.manifest` extension
 15 |  - `InstallTemp` and `Temp`, used for temporary files during servicing
 16 |  - `Fusion` and `FusionDiff`, (Windows 11) used to store SxS components for app libraries, similar to legacy SxS
 17 |  - Component folders
 18 | 
 19 | ### Component Naming Scheme
 20 | 
 21 | Component folders in WinSxS use names, known as key forms, based on the `assemblyIdentity` tag in the component manifest. The naming scheme is as follows:
 22 | 
 23 | `<processorArchitecture>_<name>_<publicKeyToken>_<version>_<language>_<pseudokey>`
 24 | 
 25 | All values except `pseudokey` correspond to an attribute of the `assemblyIdentity` tag with the same name. The `pseudokey` value is a hash based on all available attributes of this tag, an implementation of its calculation can be found in the open-source project [haveSxS](https://github.com/asdcorp/haveSxS). To generate the final name, each attribute value is converted to lowercase, then certain attributes are truncated to fit an appropriate length. The table of lengths for each truncatable attribute is given below:
 26 | 
 27 | |Attribute|Length|
 28 | |-|-|
 29 | |`language`|16|
 30 | |`name`|40|
 31 | |`version`|8|
 32 | 
 33 | If an attribute value exceeds the prescribed length, truncation is done by computing `k = (length / 2) - 1`, then setting the value to `<first k characters>..<last k characters>`. As an example, the `name` value `Microsoft-Windows-NetworkDiagnosticsFrameworkCore` exceeds the length limit of `40`, so the first and last `(40 / 2) - 1 = 19` characters would be used, truncating to `microsoft-windows-n..osticsframeworkcore`.
 34 | 
 35 | ## Servicing Stack
 36 | 
 37 | The servicing stack is composed of a series of binaries located in the `Microsoft-Windows-ServicingStack` component folder. These binaries by themselves do not constitute any processes or services, instead services or tools that want to manage packages use the APIs exposed by these binaries.
 38 | 
 39 | The most important binaries that are part of the servicing stack are:
 40 |  - `CbsCore.dll`, implements the CBS/Trusted Installer (TI) API, responsible for package installation and dependency management
 41 |  - `wcp.dll`, implements the Component Servicing Infrastructure (CSI), responsible for component/deployment installation
 42 |  - `smiengine.dll` and `smipi.dll`, implement the Service Management Infrastructure (SMI), responsible for simple file and registry modifications
 43 |  - `poqexec.exe`, responsible for carrying out individual file and registry operations during online setup
 44 |  - `wdscore.dll`, implements the Panther Engine, responsible for Windows image deployment and CBS logging
 45 |  - `TurboStack.dll`, (introduced in Windows 10 1809), implements multithreaded servicing operations, required in Windows 11
 46 |  - `mspatcha.dll`, implements PA19 delta compression
 47 |  - `msdelta.dll`, implements PA30 delta compression
 48 | 
 49 | In practice, a typical program interacting with CBS only needs to load `CbsCore.dll` for the CBS API and `wdscore.dll` for logging.
 50 | 
 51 | ## CBS API
 52 | 
 53 | Although most of the servicing stack is comprised of DLLs which export useful APIs, the vast majority of them are wrapped by the CBS API, found in `CbsCore.dll`. The CBS API primarily uses the Component Object Model (COM). Although this API is mostly undocumented, methods to interact with it have been figured out through reverse engineering.
 54 | 
 55 | To begin interacting with the API, the function `CbsCoreInitialize` must be initialized. Its function definition is as follows:
 56 | 
 57 | ```c++
 58 | typedef int (__stdcall FUNC_INT*)(int);
 59 | typedef void (FUNC_VOID*)(void);
 60 | 
 61 | HRESULT WINAPI CbsCoreInitialize(
 62 |     IMalloc* pMalloc,
 63 |     FUNC_INT* TiLockProcess,
 64 |     FUNC_VOID* TiUnlockProcess,
 65 |     FUNC_VOID* InstanceCreated,
 66 |     FUNC_VOID* InstanceDestroyed,
 67 |     FUNC_VOID* Unknown,
 68 |     FUNC_VOID* RequireShutdownProcessing,
 69 |     IClassFactory** ppClassFactory
 70 | );
 71 | ```
 72 | 
 73 | Functions of type `FUNC_INT` must return `1` on success. It is enough to stub these functions for successful interaction with the CBS API. Please note that successful initialization requires administrator privileges, though it is recommended that a CBS API client run as TrustedInstaller. A reference implementation of code to obtain TI privileges can be found in the [superUser](https://github.com/mspaintmsi/superUser) project.
 74 | 
 75 | Once the API is initialized, a session must be created to contain package operations. This is done like so:
 76 | 
 77 | ```c++
 78 | pClassFactory->CreateInstance(NULL, __uuidof(ICbsSession), &pSession);
 79 | oSession->Initialize(CbsSessionOption::OPTION, L"Client Name", bootDrive, winDir);
 80 | ```
 81 | 
 82 | The list of `CbsSessionOption` values to replace `OPTION` can be found [here](https://github.com/WitherOrNot/cbsexploder/blob/319344c0641e6d280e6a592e6f61e07a22d8ff47/cbsexploder/CbsApi.h#L79). For offline servicing of a disk image or mounted disk, `bootDrive` must specify the path of the Windows installation, and `winDir` must specify the associated `Windows` directory. For online servicing of the local system, both of these values must be `NULL` instead. This function also mounts the `COMPONENTS` registry hive, located at `\Windows\System32\config\COMPONENTS`.
 83 | 
 84 | To load a package, the `CreatePackage` function must be used, like so:
 85 | 
 86 | ```c++
 87 | pSession->CreatePackage(0, CbsPackageType::PACKAGE_TYPE, packagePath, sandboxPath, &pPackage);
 88 | ```
 89 | 
 90 | The list of available values for `PACKAGE_TYPE` can be found [here](https://github.com/WitherOrNot/cbsexploder/blob/319344c0641e6d280e6a592e6f61e07a22d8ff47/cbsexploder/CbsApi.h#L40). If specifying a cabinet file as a package, `sandboxPath` must point to a valid directory to allow for decompression. For expanded packages, the value `ExpandedWithMum` should be used, and `sandboxPath` can be left as `NULL`.
 91 | 
 92 | The package's current and applicable state can be checked before operations with `EvaluateApplicability`:
 93 | 
 94 | ```c++
 95 | pPackage->EvaluateApplicability(0, &applicableState, &currentState);
 96 | ```
 97 | 
 98 | The possible values for the current and applicable states can be found [here](https://github.com/WitherOrNot/cbsexploder/blob/319344c0641e6d280e6a592e6f61e07a22d8ff47/cbsexploder/CbsApi.h#L11). If the applicable state is not `Installed`, then a dependency for the package is missing and must be installed in a prior session.
 99 | 
100 | Finally, to queue and execute package operations, `InitiateChanges` and `FinalizeEx` are used:
101 | 
102 | ```c++
103 | pPackage1->InitiateChanges(0, CbsState::STATE1, pUIHandler);
104 | pPackage2->InitiateChanges(0, CbsState::STATE2, pUIHandler);
105 | ...
106 | pSession->FinalizeEx(0, &requiredAction);
107 | ```
108 | 
109 | The possible values for package states are the same as those for the current and applicable states. `pUIHandler` references an implementation of `ICbsUIHandler`, whose reference implementation can be found [here](https://github.com/WitherOrNot/cbsexploder/blob/319344c0641e6d280e6a592e6f61e07a22d8ff47/cbsexploder/uihandler.cpp). As shown, multiple operations for multiple packages can be queued at once before being executed by `FinalizeEx`. The value of `requiredAction` is set to `1` if a reboot is required and `0` otherwise.
110 | 
111 | Once a session successfully finalizes, a list of all operations that occurred in the session is appended to `\Windows\servicing\Sessions\sessions.xml` and saved by itself to `\Windows\servicing\Sessions\<SessID>.xml`, with `<SessID>` replaced with the session ID.
112 | 
113 | Additional examples of CBS API usage can be found in the projects [CbsExploder](https://github.com/WitherOrNot/cbsexploder) and [CallCbsCore](https://github.com/seven-mile/CallCbsCore).
114 | 
115 | ## Package Management
116 | 
117 | Upon calling `FinalizeEx`, the Trusted Installer begins the process of package installation, which is done in the following stages:
118 | 1. Planning
119 | 2. Resolving
120 | 3. Pre-Staging
121 | 4. Staging
122 | 5. Installing
123 | 
124 | ### Planning
125 | 
126 | In this stage, the dependency tree of the package is resolved, and the presence of manifests for all dependency packages is checked. If any dependency is missing, the installation fails.
127 | 
128 | ### Resolving
129 | 
130 | In this stage, the dependency tree is crawled to create a list of all deployments to be installed, then this list is passed to CSI for processing.
131 | 
132 | ### Pre-Staging
133 | 
134 | In this stage, the component data is added to the registry in `COMPONENTS\DerivedData\Components`. A key named for the key form of the component is created and populated with the following values:
135 |  - `S256H`, the SHA256 hash of the uncompressed manifest
136 |  - `identity`, containing expanded assembly identity data
137 |  - `c!<keyform>`, with `<keyform>` replaced with the component key form
138 | 
139 | The package catalogs are then copied to `\Windows\WinSxS\Catalogs` and `\Windows\System32\CatRoot\{F750E6C3-38EE-11D1-85E5-00C04FC295EE}`. In the `Catalogs` directory, the catalog filename is changed to the SHA256 hash of the catalog file.
140 | 
141 | ### Staging
142 | 
143 | In this stage, the component files are copied to `\Windows\WinSxS` in folders named after the component key form. The corresponding registry key for each component is updated to add values named `f!<filename>`, with `<filename>` replaced with the name of each file in the component. The `CF` value of this key is also set to mark the component as staged, as well as which compression is used for the manifest. Finally, deployments are pinned by creating a key for each deployment in `COMPONENTS\CanonicalData\Deployments` named after its key form. This key is populated with the following values:
144 | 
145 |  - `appid`, containing expanded deployment assembly identity data
146 |  - `CatalogThumbprint`, containing the SHA256 hash of the uncompressed deployment manifest
147 |  - `p!<packagekeyform>`, with `<packagekeyform>` replaced with a keyform for the package
148 |  - `s!<packagekeyform>`, set to signal that the deployment is staged
149 | 
150 | At this stage, a valid CBS state has been reached, and the session may end depending on whether the package was requested to be staged or installed. Packages that are staged may resume the install process upon a future request to install the package.
151 | 
152 | ### Installing
153 | 
154 | This stage is handled by 2 main parts of the servicing stack: Primitive Installers and Advanced Installers.
155 | 
156 | #### Primitive Installers
157 | 
158 | Primitive installers generate filesystem and registry contents based on data specified in component manifests. Files are projected from the WinSxS folder to the external filesystem using [hard links](https://learn.microsoft.com/en-us/windows/win32/fileio/hard-links-and-junctions), which allow the same file data to be referenced by multiple paths. As a side effect, file size measurements double-count sizes for files hardlinked to 2 locations, causing system files to appear to use more disk space than they actually use. Registry data is applied through standard registry writes. Permissions are also set based on SDDL-encoded permission data in manifests.
159 | 
160 | #### Advanced Installers
161 | 
162 | Advanced installers provide higher-level setup capabilities, allowing for operations like creation of services, scheduled tasks, and installed program entries without needing to manually specify all of the of the registry and file manipulations involved. This is through CSI and CMI, which use DLLs from servicing stack components to carry out the installation process. CSI also loads Advanced Installers to execute the Midground Installer, which provides more generic Advanced Installer capabilities for items like services, disk volumes, and networking for categories of components rather than individual components.
163 | 
164 | #### Installation Finalization
165 | 
166 | Once a component is installed, if its manifest contains a `migration` tag, signalling that the component stores user-modifiable data to be kept during upgrades, the manifest filename is stored in `\Windows\WinSxS\migration.xml`. An associated key for the component is also created under `SOFTWARE\Microsoft\Windows\CurrentVersion\SideBySide\Winners`.
167 | 
168 | Once a package is installed, the relevant deployment keys in `COMPONENTS\CanonicalData\Deployments` are updated to add the value `i!<packagekeyform>` similar to in staging, indicating that the deployment is installed.
169 | 
170 | ### Session Finalization
171 | 
172 | The following operations occur after both staging and installation.
173 | 
174 | If any operations are marked as pending, meaning they must be completed in a future session, the list of pending operations is written to `\Windows\WinSxS\pending.xml`. If any errors are raised during driver installation or operations on critical components, the value `Unserviceable` is set in `SOFTWARE\Microsoft\Windows\CurrentVersion\Component Based Servicing`. This causes future sessions to immediately exit with an error upon attempting servicing operations.
175 | 
176 | Finally, packages are committed to the package store by copying the package manifests and catalogs to `\Windows\servicing\Packages`, and the keys under `SOFTWARE\Microsoft\Windows\CurrentVersion\Component Based Servicing` are updated as follows:
177 | 
178 |  - `Packages`, a key named for each package's identity string is created. If the package is a dependency of another package, the depending packages are listed as values in the sub-key `Owners`
179 |  - `PackageIndex`, a key named as the package's identity string is created, except the version is set to `0.0.0.0`. A value is created under this key with the identity string of the latest version of the package
180 |  - `SessionsPending`, a key named as the session ID is added
181 |  - `PackagesPending`, identical to `Packages` but for packages that will be installed in pending operations
182 |  - `PackageDetect`, `UpdateDetect`, `ComponentDetect`, respective keys added for dependencies that are marked as detectable in their manifests
183 | 
184 | ## Sources
185 | 
186 |  - [haveSxS - asdcorp](https://github.com/asdcorp/haveSxS)
187 |  - [CallCbsCore - seven-mile](https://github.com/seven-mile/CallCbsCore)
188 |  - [How to address disk space issues that are caused by a large Windows component store (WinSxS) directory - Microsoft Learn](https://learn.microsoft.com/en-us/troubleshoot/windows-client/installing-updates-features-roles/address-disk-space-issues-caused-by-winsxs)
189 | 


--------------------------------------------------------------------------------
/GeneralOverview.md:
--------------------------------------------------------------------------------
  1 | # General Overview
  2 | 
  3 | ## Introduction
  4 | 
  5 | Component-Based Servicing (CBS) is a subsystem of Windows that underlies many important capabilities, including image deployment, Features on Demand, system updates, and system corruption repair.
  6 | 
  7 | Despite its overarching reach and importance, even most advanced Windows users are unaware of CBS, how it works, and all the things it is involved in. This is partially by design, as Microsoft has released little official information as to how CBS works, and much of its functionality is locked away behind undocumented APIs. As such, the most comprehensive sources of information on CBS are scattered between various online chatrooms and obscure forums, making them hard to find and vulnerable to being lost. Thus, I have decided to compile these sources, along with my own findings, into a organized series of writeups.
  8 | 
  9 | Due to the limited scope and availability of this information, these writeups will cover desktop Windows versions 7 through 11, with a focus on 8 through 10. Additionally, most of these writeups will center around the theme of image deployment, since it is (in my opinion) the most interesting thing that CBS is used for.
 10 | 
 11 | ## Side-by-Side Assembly
 12 | 
 13 | In order to understand CBS, we must begin with its predecessor, the Side-by-Side (SxS) assembly system.
 14 | 
 15 | SxS is a subsystem introduced in Windows 98 Second Edition and Windows 2000 which allows multiple versions and variants of software libraries to coexist on a system, providing a way for programs to select a specific version on demand. It also provides security and integrity-checking features that prevent these libraries from being maliciously modified or corrupted.
 16 | 
 17 | To accomplish this, libraries, known as assemblies, are accompanied by an associated XML file, known as a manifest, which describes their contents and associations with other assemblies. An example manifest is given below:
 18 | 
 19 | ```xml
 20 | <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 21 | <assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
 22 |     <assemblyIdentity version="5.2.2.3" processorArchitecture="x86" name="Microsoft.Windows.Networking.RtcDll" type="win32" publicKeyToken="6595b64144ccf1df"/>
 23 |     <description>RTC Core DLL</description>
 24 |     <dependency>
 25 |         <dependentAssembly>
 26 |             <assemblyIdentity type="win32" name="Microsoft.Windows.Networking.DxmRtp" version="5.2.2.3" processorArchitecture="x86" publicKeyToken="6595b64144ccf1df" language="*"/>
 27 |         </dependentAssembly>
 28 |     </dependency>
 29 |     <dependency optional="yes">
 30 |         <dependentAssembly>
 31 |             <assemblyIdentity type="win32" name="Microsoft.Windows.Networking.RtcRes" version="5.2.2.3" processorArchitecture="x86" publicKeyToken="6595b64144ccf1df" language="*"/>
 32 |         </dependentAssembly>
 33 |     </dependency>
 34 |     <file name="rtcdll.dll" hash="e0391579b3315433346a80ba86d0876f4dd669d9" hashalg="SHA1">
 35 |         <comClass description="RTCClient Class" clsid="{7a42ea29-a2b7-40c4-b091-f6f024aa89be}" threadingModel="Apartment"/>
 36 |         <typelib tlbid="{cd260094-de10-4aee-ac73-ef87f6e12683}" version="1.1" helpdir=""/>
 37 |     </file>
 38 | </assembly>
 39 | ```
 40 | 
 41 | As shown, manifests are able to describe assembly dependencies, file integrity information, and installation information in a readable format. To prevent corruption or malicious modification of these manifests, they are stored alongside signed catalog files containing their hashes.
 42 | 
 43 | Additionally, to provide the SxS functionality, manifests specify an `assemblyIdentity` tag that uniquely identifies a particular assembly, specifying its name, version, architecture, signing key, and runtime. This information is then specified by programs in their own manifests (usually located within the binary) to load a particular version of a library. The information in this tag is also used in the manifest naming system, which will be covered in a later chapter.
 44 | 
 45 | ## Windows Componentization
 46 | 
 47 | The fundamental idea behind CBS is to extend the SxS system to not only store program libraries, but the parts that make up Windows itself.
 48 | 
 49 | Storing the OS this way provides immediate benefits, such as providing simpler methods for system updates and system file corruption detection. It also centralizes and organizes the storage of system files, making them easier to manage for Microsoft and system administrators. Due to these benefits, Microsoft introduced CBS with Windows Vista, and it has served as the primary method of managing system files ever since.
 50 | 
 51 | CBS, like SxS, works in terms of assemblies, with only difference being that assemblies are now used to hold system data rather than program libraries. The 3 primary kinds of CBS assemblies are:
 52 |  - Components, which group a set of related files, registry keys, and other items
 53 |  - Deployments, which group a set of related components
 54 |  - Packages, which group a set of related components, deployments, and sub-packages
 55 | 
 56 | ### Components
 57 | 
 58 | Components are the most fundamental unit of Windows servicing. They tend to house only a small set of files, and they can also contain extended metadata related to registry changes, permissions, and other installation information that is needed to correctly set up these files. Components may also specify other components as dependencies.
 59 | 
 60 | Example manifest:
 61 | 
 62 | ```xml
 63 | <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 64 | <assembly xmlns="urn:schemas-microsoft-com:asm.v3" manifestVersion="1.0" copyright="Copyright (c) Microsoft Corporation. All Rights Reserved.">
 65 |   <assemblyIdentity name="Microsoft-Windows-VolumeActivation-EventQuery" version="6.2.8250.0" processorArchitecture="amd64" language="neutral" buildType="release" publicKeyToken="31bf3856ad364e35" versionScope="nonSxS" />
 66 |   <file name="VolumeActivation.Events.xml" destinationPath="$(runtime.programData)\Microsoft\Event Viewer\Views\ServerRoles\" sourceName="VolumeActivation.Events.xml" sourcePath=".\" importPath="$(build.nttree)\">
 67 |     <securityDescriptor name="WRP_FILE_DEFAULT_SDDL" />
 68 |     <asmv2:hash xmlns:asmv2="urn:schemas-microsoft-com:asm.v2">
 69 |       <dsig:Transforms xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
 70 |         <dsig:Transform Algorithm="urn:schemas-microsoft-com:HashTransforms.Identity" />
 71 |       </dsig:Transforms>
 72 |       <dsig:DigestMethod xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" Algorithm="http://www.w3.org/2000/09/xmldsig#sha256" />
 73 |       <dsig:DigestValue xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">UZq+KgtzhkSi0GBqhcE16sHbVjSqibRrRdWaG/KUsmc=</dsig:DigestValue>
 74 |     </asmv2:hash>
 75 |   </file>
 76 |   <trustInfo>
 77 |     <security>
 78 |       <accessControl>
 79 |         <securityDescriptorDefinitions>
 80 |           <securityDescriptorDefinition name="WRP_FILE_DEFAULT_SDDL" sddl="O:S-1-5-80-956008885-3418522649-1831038044-1853292631-2271478464G:S-1-5-80-956008885-3418522649-1831038044-1853292631-2271478464D:P(A;;FA;;;S-1-5-80-956008885-3418522649-1831038044-1853292631-2271478464)(A;;GRGX;;;BA)(A;;GRGX;;;SY)(A;;GRGX;;;BU)(A;;GRGX;;;S-1-15-2-1)S:(AU;FASA;0x000D0116;;;WD)" operationHint="replace" description="Default SDDL for Windows Resource Protected file" />
 81 |         </securityDescriptorDefinitions>
 82 |       </accessControl>
 83 |     </security>
 84 |   </trustInfo>
 85 | </assembly>
 86 | ```
 87 | 
 88 | ### Deployments
 89 | 
 90 | Deployments are used to categorize a set of components that must be installed together. Deployments must contain the `deployment` tag, and they reference the contained components as dependencies.
 91 | 
 92 | Example manifest:
 93 | 
 94 | ```xml
 95 | <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 96 | <assembly xmlns="urn:schemas-microsoft-com:asm.v3" manifestVersion="1.0" copyright="Copyright (c) Microsoft Corporation. All Rights Reserved.">
 97 |   <assemblyIdentity name="Microsoft-Hyper-V-Management-Client-Interop-Deployment" version="6.2.8250.0" processorArchitecture="amd64" language="neutral" buildType="release" publicKeyToken="31bf3856ad364e35" versionScope="nonSxS" />
 98 |   <dependency discoverable="no">
 99 |     <dependentAssembly dependencyType="install">
100 |       <assemblyIdentity name="Microsoft.Virtualization.Client.RdpClientAxHost" version="6.2.8250.0" processorArchitecture="msil" language="neutral" buildType="release" publicKeyToken="31bf3856ad364e35" versionScope="nonSxS" />
101 |     </dependentAssembly>
102 |   </dependency>
103 |   <dependency discoverable="no">
104 |     <dependentAssembly dependencyType="install">
105 |       <assemblyIdentity name="Microsoft.Virtualization.Client.RdpClientInterop" version="6.2.8250.0" processorArchitecture="msil" language="neutral" buildType="release" publicKeyToken="31bf3856ad364e35" versionScope="nonSxS" />
106 |     </dependentAssembly>
107 |   </dependency>
108 |   <deployment xmlns="urn:schemas-microsoft-com:asm.v3" />
109 | </assembly>
110 | ```
111 | 
112 | ### Packages
113 | 
114 | Packages are used to group a set of components, deployments, and packages to deliver a single feature set. Packages must contain the `package` tag, and each included deployment or sub-package is contained within an `update` tag. During servicing, Windows may either install all the updates in a package or select particular updates as needed. Packages may also specify parent packages with the `parent` tag. If a given package's parent is not available during installation, the given package's installation will fail. Additionally, the package release type is specified by the `releaseType` attribute of the `package` tag. This value affects how CBS chooses to handle requests to install or uninstall packages.
115 | 
116 | Example manifest:
117 | 
118 | ```xml
119 | <?xml version="1.0" encoding="utf-8" standalone="yes"?>
120 | <assembly xmlns="urn:schemas-microsoft-com:asm.v3" copyright="Copyright (c) Microsoft Corporation. All Rights Reserved." manifestVersion="1.0">
121 |   <assemblyIdentity buildType="release" language="en-US" name="Microsoft-Windows-BusinessScanning-Feature-Package-admin" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" version="6.2.8250.0"/>
122 |   <package identifier="Microsoft-Windows-BusinessScanning-Feature-Package-admin LP" releaseType="Language Pack">
123 |     <parent disposition="detect" integrate="separate">
124 |       <assemblyIdentity buildType="release" language="neutral" name="Microsoft-Windows-BusinessScanning-Feature-Package-admin" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" version="6.2.8250.0"/>
125 |     </parent>
126 |     <update description="Wraps admin components depot contributing to Microsoft-Windows-BusinessScanning-Feature-Package-admin" displayName="Microsoft-Windows-BusinessScanning-Feature-Package-admin" name="Microsoft-Windows-BusinessScanning-Feature-Package-admin">
127 |       <component>
128 |         <assemblyIdentity buildType="release" language="en-US" name="Microsoft-Windows-BusinessScanning-Feature-Package-admin-deployment-LanguagePack" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" version="6.2.8250.0" versionScope="nonSxS"/>
129 |       </component>
130 |     </update>
131 |   </package>
132 | </assembly>
133 | ```
134 | 
135 | ## Servicing Stack
136 | 
137 | Each type of assembly is processed by the parts that carry out the CBS process, which are collectively known as the servicing stack. In order of highest to lowest level, the servicing stack consists of the following:
138 | 
139 |  - Trusted Installer (TI), responsible for managing packages
140 |  - Component Servicing Infrastructure (CSI), responsible for managing deployments and components
141 |  - Component Management Infrastructure (CMI), responsible for high level component installation
142 |  - Driver Management and Install (DMI), responsible for driver installation
143 |  - Systems Management Infrastructure (SMI), responsible for low level component installation
144 |  - Kernel Transaction Manager (KTM), responsible for managing individual operations
145 | 
146 | The next chapter will explore each of these parts in detail, as well as how a developer can interact with them.
147 | 
148 | ## Sources
149 | 
150 |  - [Understanding Component-Based Servicing - Microsoft Community Hub](https://techcommunity.microsoft.com/t5/ask-the-performance-team/understanding-component-based-servicing/ba-p/373012)
151 |  - [Side-by-side assembly - Wikipedia](https://en.wikipedia.org/wiki/Side-by-side_assembly)
152 | 


--------------------------------------------------------------------------------
/ImageDeployment.md:
--------------------------------------------------------------------------------
  1 | # Image Deployment
  2 | 
  3 | ## Introduction
  4 | 
  5 | Beginning with Windows Vista, all Windows client and server SKUs were built from a unified codebase to prevent feature lag. This poses a problem as to how to construct installable Windows images for every edition that contain the correct files and licenses, as well as allowing offline edition upgrades. Luckily, CBS is well-equipped to solve this problem, which is why it plays an essential role in the construction of Windows installation images.
  6 | 
  7 | ## Foundation Image
  8 | 
  9 | The first step in constructing a Windows image is the creation of a foundation image. Prior to Windows 8, these foundation images appear to have been generated during postbuild and populated with all the files that are common between SKUs. Although it remains unclear how foundation images were created for Windows 8 and 8.1, the construction of foundation images for Windows 10 and 11 is well understood. Additionally, testing has found that foundation images generated for Windows 10 can be used to deploy Windows 8 and 8.1 images.
 10 | 
 11 | To create a foundation image, the exported functions `CreateNewWindows` and `CreateNewOfflineStore` from `wcp.dll` are used. These have the following declarations:
 12 | 
 13 | ```c++
 14 | HRESULT WINAPI CreateNewWindows(
 15 |     DWORD dwFlags,
 16 |     LPCWSTR pszSystemDrive,
 17 |     POFFLINE_STORE_CREATION_PARAMETERS pParameters,
 18 |     PVOID* ppvKeys,
 19 |     DWORD* pdwDisposition
 20 | );
 21 | 
 22 | HRESULT WINAPI CreateNewOfflineStore(
 23 |     DWORD dwFlags,
 24 |     PCOFFLINE_STORE_CREATION_PARAMETERS pParameters,
 25 |     REFIID riid,
 26 |     IUnknown** ppStore,
 27 |     DWORD* pdwDisposition
 28 | );
 29 | ```
 30 | 
 31 | First, `CreateNewWindows` is called like so:
 32 | 
 33 | ```c++
 34 | OFFLINE_STORE_CREATION_PARAMETERS pParameters = { sizeof(OFFLINE_STORE_CREATION_PARAMETERS) };
 35 | pParameters.pszHostSystemDrivePath = L"<Path to Offline Image Root>";
 36 | pParameters.ulProcessorArchitecture = ARCHITECTURE;
 37 | void* regKeys;
 38 | DWORD disposition;
 39 | CreateNewWindows(0, L"X:\\", &pParameters, &regKeys, &disposition);
 40 | ```
 41 | 
 42 | Possible values of `ARCHITECTURE` can be found [here](https://learn.microsoft.com/en-us/uwp/api/windows.system.processorarchitecture). The architecture value reflects the processor architecture of the offline image.
 43 | 
 44 | Once the image is created, the `COMPONENTS` hive is then populated by `CreateNewOfflineStore` like so:
 45 | 
 46 | ```c++
 47 | ICSIStore* store;
 48 | CreateNewOfflineStore(0, &pParameters, __uuidof(ICSIStore), (IUnknown**)&store, &disposition);
 49 | ```
 50 | 
 51 | Upon successful completion, the image is ready to be serviced offline by CBS. An implementation of this foundation image generation can be found in [SxSFounder](https://github.com/WitherOrNot/sxsfounder).
 52 | 
 53 | ## Package Types
 54 | 
 55 | Generally, Windows images are composed of the following types of primary packages:
 56 |  - Foundation Packages
 57 |  - Edition Packages
 58 |  - Language Packs
 59 |  - Features on Demand
 60 | 
 61 | ### Foundation Packages
 62 | 
 63 | Foundation packages contain the minimum possible set of components needed for an image to be serviceable using its own servicing stack. This typically includes the core servicing stack, advanced installer DLLs, components for DISM, and core windows APIs. Once these components are present, CBS will prefer using the offline servicing stack for offline operations.
 64 | 
 65 | ### Edition Packages
 66 | 
 67 | Edition packages contain all non-localized components for a particular Windows edition, including the foundation package as a dependency.
 68 | 
 69 | ### Language Packs
 70 | 
 71 | Language packs (LPs) contain all localized components for all Windows editions of either the Client or Server variety. If an edition package is installed without a language pack, the system will crash with the stop code `MUI_NO_VALID_SYSTEM_LANGUAGE`. This may also occur if the installed language packs do not match the allowed system languages specified in the system product policy.
 72 | 
 73 | ### Features on Demand
 74 | 
 75 | Features on Demand (FoD), a system introduced in Windows 8, allow for system features to be added after image deployment. Modern Windows versions usually come preinstalled with a few FoDs and allow others to be installable over Windows Update.
 76 | 
 77 | ## Staged Image Deployment
 78 | 
 79 | Staged images are the most common form of Windows installation image, where each edition is installed directly to a separate sub-image.
 80 | 
 81 | Prior to Windows 10 1903, this installation was done with DISM. From late Windows 10 onwards, this installation was done with CBSS, an internal fork of Vista's PkgMgr. Thanks to leaks from internal test updates, CBSS is [publicly available](https://archive.org/download/windows-10.0-kb-9999999-x-64).
 82 | 
 83 | Since it is unclear from available data whether the DISM API or command-line tool was used, DISM commands will be used to represent operations done with DISM for convenience.
 84 | 
 85 | ### Pre-Servicing
 86 | 
 87 | For Windows 7 up through early Windows 10, certain modifications to the foundation image need to be made prior to servicing.
 88 | 
 89 | First, non-package legacy catalogs must be copied to `\Windows\System32\CatRoot\{F750E6C3-38EE-11D1-85E5-00C04FC295EE}`, so that they are included in the catalog database. Without these catalogs present, older Windows versions may fail to boot due to system files lacking an available signature.
 90 | 
 91 | Then, for Windows 8 through Windows 10 1511, [fingerprinting data](https://betawiki.net/wiki/Leak_prevention_in_Microsoft_Windows) must be added to the registry at `HKLM\SYSTEM\WPA\478C035F-04BC-48C7-B324-2462D786DAD7-5P-9` and to the filesystem at `\Windows\System32\config\FP`. Without this data present, Windows may fail to boot or crash during usage with the stop code `KERNEL_SECURITY_CHECK_FAILURE` or `CRITICAL_STRUCTURE_CORRUPTION`.
 92 | 
 93 | ### DISM Installation
 94 | 
 95 | To install with DISM, the environment variable `WINDOWS_WCP_INSKUASSEMBLY` must be set to `1`, and the foundation package must be deployed to the image without being committed as an installed package. Then, the edition packages are added using a DISM unattend file:
 96 | 
 97 | ```
 98 | dism /image:<Offline Image Path> /apply-unattend:<Path to Unattend file>
 99 | ```
100 | 
101 | The contents of the unattend file specify to install the target edition and stage all editions that it can upgrade to. Example:
102 | 
103 | ```xml
104 | <?xml version="1.0" encoding="utf-8"?>
105 | <unattend xmlns="urn:schemas-microsoft-com:unattend">
106 |     <servicing>
107 |         <package action="install">
108 |             <assemblyIdentity name="Microsoft-Windows-CoreEdition" version="10.0.22000.1" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" />
109 |             <source location="packages\Microsoft-Windows-CoreEdition~31bf3856ad364e35~amd64~~10.0.22000.1.mum" />
110 |         </package>
111 |         <package action="stage">
112 |             <assemblyIdentity name="Microsoft-Windows-ProfessionalEdition" version="10.0.22000.1" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" />
113 |             <source location="packages\Microsoft-Windows-ProfessionalEdition~31bf3856ad364e35~amd64~~10.0.22000.1.mum" />
114 |         </package>
115 |         ...
116 |     </servicing>
117 | </unattend>
118 | ```
119 | 
120 | ### CBSS Installation
121 | 
122 | To install with publicly available CBSS, the environment variable `PKGMGR_RUNNING_IN_OFFLINE_STACK_ALREADY` must be set to `1`. Modern CBSS is run with an undocumented `/ls` flag, which is presumed to have an equivalent effect. Once set, installation is done using a CBSS batch file:
123 | 
124 | ```
125 | cbss [/ls] /o:<Offline Image Windows Directory> /b:<Path to Batch File>
126 | ```
127 | 
128 | The contents of the batch file are similar to a DISM unattend file, also specifying installation of the target edition and staging all available upgrades. Example:
129 | 
130 | ```
131 | /ip /m:packages\Microsoft-Windows-CoreEdition~31bf3856ad364e35~amd64~~10.0.22000.1.mum
132 | /sp /m:packages\Microsoft-Windows-ProfessionalEdition~31bf3856ad364e35~amd64~~10.0.22000.1.mum
133 | ...
134 | ```
135 | 
136 | ### Language Pack Installation
137 | 
138 | Once the edition package is installed, all future installations are done with DISM. Language pack installation is done using DISM package installation:
139 | 
140 | ```
141 | dism /image:<Offline Image Path> /add-package /packagepath:<Language Pack Path> 
142 | ```
143 | 
144 | ### Edition-Specific Unattend
145 | 
146 | Edition-specific settings are then applied from an unattend file. This unattend file is installed by default to `\Windows\servicing\Editions\<Edition Shortname>.xml` and copied after Edition Package installation to `\Windows\<Edition Shortname>.xml`. It is then installed using DISM unattend installation:
147 | 
148 | ```
149 | dism /image:<Offline Image Path> /apply-unattend:<Path to Offline Image>\Windows\<Edition Shortname>.xml
150 | ```
151 | 
152 | ### Locale Settings
153 | 
154 | The image's system language is then set:
155 | 
156 | ```
157 | dism /image:<Offline Image Path> /set-allintl:<Language Code>
158 | ```
159 | 
160 | This updates the offline image's registry values in the following locations:
161 |  - `SYSTEM\ControlSet001\Control\Nls\CodePage`
162 |  - `SYSTEM\ControlSet001\Control\Nls\Locale`
163 |  - `SYSTEM\ControlSet001\Control\Nls\Language`
164 |  - `SYSTEM\ControlSet001\Control\CommonGlobUserSettings\Control Panel\International`
165 | 
166 | ### Sysprep
167 | 
168 | In newer Windows versions, the Sysprep generalization state must be added after servicing. This is done by creating the file `\Windows\Setup\State\State.ini` with the following contents:
169 | 
170 | ```
171 | [State]
172 | ImageState=IMAGE_STATE_GENERALIZE_RESEAL_TO_OOBE
173 | ```
174 | 
175 | The following registry modifications must also be made:
176 |  - `SOFTWARE\Microsoft\Windows\CurrentVersion\Setup\State!ImageState` set to `IMAGE_STATE_GENERALIZE_RESEAL_TO_OOBE` (`REG_SZ`)
177 |  - `SOFTWARE\Microsoft\Windows\CurrentVersion\Setup\ImageServicingData!ImageState` set to `IMAGE_STATE_GENERALIZE_RESEAL_TO_OOBE` (`REG_SZ`)
178 |  - `SYSTEM\Setup\Status\SysprepStatus!GeneralizationState` set to `4` (`REG_DWORD`)
179 | 
180 | The open-source project [explodeSxS](https://github.com/asdcorp/explodeSxS) provides an implementation of the staged image deployment process.
181 | 
182 | ## Unstaged Image Deployment
183 | 
184 | Rarely, some versions of Windows are shipped unstaged, meaning that no particular edition package is installed in the installation image and the foundation package is deployed without being marked as installed. Instead, the full list of editions built at compile time are available to choose from during initial setup, either in an interactive menu or by entering an appropriate product key. Then, setup will manually install the edition package and language pack during offline image deployment. Some examples of known unstaged builds are checked builds of Windows 7, [Windows 10 build 14357.1000](https://betawiki.net/wiki/Windows_10_build_14357.1000), and [Windows Server 2016 build 10586 (th2_srv1_nano_dev2)](https://betawiki.net/wiki/Windows_Server_2016_build_10586_(th2_srv1_nano_dev2)).
185 | 
186 | ### Packages Directory
187 | 
188 | The packages directory, located at `\packages` is structured similarly to the `WinSxS` directory, except that the only sub-directories present are for component folders, and all manifests for packages, components, and deployments are stored at the root of the folder. Additionally, the following files must be present at the root of the folder:
189 |  - The package manifests and associated catalogs for all available editions must be named after their editions' shortname (ex. `Professional.mum`, `Professional.cat`, etc.)
190 |  - The edition unattend file must also be named after the edition shortname (ex. `Professional.xml`)
191 |  - The appropriate edition matrix and upgrade matrix, named `EditionMatrix.xml` and `UpgradeMatrix.xml` respectively
192 |  - `pkeyconfig.xrm-ms` containing product key information for the available editions
193 |  - `pidgenx.dll`
194 | 
195 | Note that only files related to the dependencies of edition packages are present in the packages directory.
196 | 
197 | ### WIM Metadata
198 | 
199 | For setup to be configured for installing an unstaged image, the appropriate metadata must be set in `install.wim`:
200 |  - `FLAGS` must be set to `Windows Foundation`
201 |  - `DESCRIPTION` must end with the string `EDITIONS:` followed by a comma-separated list of available editions (ex. `EDITIONS:CORE,PROFESSIONAL,ENTERPRISE`)
202 | 
203 | These values can be set using [wimlib](https://wimlib.net).
204 | 
205 | ### Language Packs
206 | 
207 | Since language packs are not installed in the image, they are instead packaged into cabinet files and stored in the setup ISO. Prior to cabinet compression, the package manifest for the language pack must be named `update.mum`, and the associated catalog file must be named `update.cat`. Then, the language pack is saved in `langpacks/<language code>/lp.cab` in the setup ISO.
208 | 
209 | To support installation of language packs from the ISO, the file `sources\lang.ini` must be updated in both the ISO and in `sources\boot.wim` within the ISO. In this file, under the section `[Available Languages]` the flag for each language must be set to `1`. Example contents:
210 | 
211 | ```
212 | [Available UI Languages] 
213 | en-US = 1 
214 | qps-ploc = 1 
215 |  
216 | [Fallback Languages] 
217 | en-US = en-us 
218 | qps-ploc = en-us 
219 | ```
220 | 
221 | Note that if an appropriate EULA file is not available for a chosen edition and language, it cannot be installed with Windows Setup.
222 | 
223 | ## Sources
224 | 
225 |  - [stageSxS - asdcorp](https://github.com/asdcorp/stageSxS)
226 |  - [Leak prevention in Microsoft Windows - BetaWiki](https://betawiki.net/wiki/Leak_prevention_in_Microsoft_Windows)
227 |  - [Windows 10 build 14357.1000 - BetaWiki](https://betawiki.net/wiki/Windows_10_build_14357.1000)
228 |  - [Windows Server 2016 build 10586 (th2_srv1_nano_dev2) - BetaWiki](https://betawiki.net/wiki/Windows_Server_2016_build_10586_(th2_srv1_nano_dev2))
229 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # CBS Docs
 2 | 
 3 | By WitherOrNot
 4 | 
 5 | ## About
 6 | 
 7 | This repo contains documentation on the Component-Based Servicing (CBS) subsystem of Windows. Information provided in this repository is obtained by reverse-engineering due to lack of official documentation and may contain inaccuracies. If any inaccuracies are found, please raise an issue or create a pull request. 
 8 | 
 9 | ## Chapters
10 | 
11 | For convenience, this documentation has been split into multiple chapters, covering different aspects of CBS.
12 | 1. [General Overview](./GeneralOverview.md)
13 | 2. [CBS Internals](./CBSInternals.md)
14 | 3. [Image Deployment](./ImageDeployment.md)
15 | 


--------------------------------------------------------------------------------