Skip to content

Commit 8feadc3

Browse files
TacoTechSharmaTacoTechSharma
committed
added dgss migration fixes
1 parent 81ac62a commit 8feadc3

File tree

1 file changed

+197
-0
lines changed

1 file changed

+197
-0
lines changed

‎articles/trusted-signing/how-to-device-guard-signing-service-migration.md

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
---
2+
title: Device Guard Signing Service migration to Trusted Signing
3+
description: Learn how to migrate from Device Guard Signing Service (DGSSv2) to Trusted Signing for code integrity policy
4+
author: mehasharma
5+
ms.author: mesharm
6+
ms.service: trusted-signing
7+
ms.topic: how-to
8+
ms.date: 08/19/2024
9+
ms.custom: template-how-to-pattern, devx-track-azurepowershell
10+
---
11+
12+
13+
# Device Guard Signing Service (DGSSv2) Migration to Trusted Signing for code integrity policy
14+
15+
Device Guard Signing Service is being deprecated at the beginning of December 2024. All existing DGSSv2 customers who plan to continue using the service must transition to Trusted Signing.
16+
The root that issues the code signing and CI policy signing certificates remains the same between DGSSv2 and Trusted Signing. Since Trusted Signing is an Azure service, you now need to have Azure Tenant Id and Subscription Id to access signing, and a new dedicated EKU for signing. Steps you need to take include:
17+
18+
- Get an Azure account
19+
- Set up access to signing control (controlled through Azure portal and Azure identities)
20+
- Choose a pricing tier (Trusted Signing is a paid service – learn more about pricing [here](https://azure.microsoft.com/pricing/details/trusted-signing/))
21+
- Follow the steps dependent on your migration scenarios
22+
23+
This guide outlines the steps needed to migrate to Trusted Signing. **Read the entirety of this document and note these steps must be followed carefully; missing a step may cause damage to the OS image.**
24+
25+
## Migration Scenarios
26+
27+
- Scenario 1: Signed CI Policy Migration & Deployment
28+
- You have an existing CI policy signed with DGSSv2 and now wish to migrate it to Trusted Signing.
29+
- Scenario 2: Unsigned to Signed CI Policy Migration & Deployment
30+
- You have an existing unsigned CI policy and now wish to migrate it to Trusted Signing with a signed CI policy.
31+
- Scenario 3: Unsigned to Unsigned CI Policy Migration & Deployment
32+
- You have an existing unsigned CI policy and now wish to migrate it to Trusted Signing, maintaining it as an unsigned CI policy.
33+
- Scenario 4: No Existing CI Policy
34+
- You currently don't have a CI policy deployed in your environment and want to migrate to Trusted Signing.
35+
36+
37+
## Prerequisites
38+
- We strongly encourage creating a restoration image(s) before proceeding with the migration steps.
39+
- If you had previously deployed a CI policy in your environment (scenarios #1 and #2 above), you must have access to the existing policy xml file.
40+
- We strongly encourage you to do the steps below on one machine before attempting to deploy to your broader environment.
41+
42+
43+
> [!IMPORTANT]
44+
> Migration isn't possible without creating a Trusted Signing account, Private Trust identity validation, and Private Trust CI policy signing certificate profile using these steps: [Quickstart: Set up Trusted Signing | Microsoft Learn](https://learn.microsoft.com/azure/trusted-signing/quickstart?tabs=registerrp-portal%2Caccount-portal%2Ccertificateprofile-portal%2Cdeleteresources-portal).
45+
46+
47+
## Scenario 1: Signed CI Policy Migration & Deployment
48+
49+
The migration of the signed CI policy is applicable only to customers who have already implemented a DGSSv2 signed CI policy in their environment. To ensure a smooth transition and deployment, carefully follow the next two steps:
50+
51+
### Step 1: Remove the deployed signed CI policy from a single machine
52+
53+
> [!Note]
54+
> By following the actions of step 1, your machine isn't protected by CI until you have deployed a new one. The deployment of a new policy is covered by step 2
55+
56+
1. Confirm with your system administrator to verify you have a DGSSv2 signed policy deployed, or use below manual way:
57+
- Go to `C:\Windows\System32\CodeIntegrity`, if there's a `SiPolicy.p7b` file, which indicates you have a CI policy deployed.
58+
- Open the file. If it shows a certificate, it means the CI policy is signed.
59+
- If you see the error `“This file is invalid for use as the following: PKCS #7”`, the CI policy is unsigned.
60+
2. Under the Rules section of the current CI Policy XML file, add the following rule:
61+
```
62+
<Rule>
63+
<Option>Enabled:Unsigned System Integrity Policy</Option>
64+
</Rule>
65+
```
66+
67+
3. Convert the policy xml to .bin file using this PowerShell: ConvertFrom-CIPolicy
68+
69+
Sample:
70+
```
71+
ConvertFrom-CIPolicy -XmlFilePath <xmlCIPolicyFilePath> -BinaryFilePath <binaryCIPolicyFilePath>
72+
73+
```
74+
4. Sign the generated policy .bin file with Trusted Signing using the following instructions: [Sign a CI policy | Microsoft Learn](https://learn.microsoft.com/azure/trusted-signing/how-to-sign-ci-policy).
75+
5. Deploy this signed policy .bin file. For more information, refer to [Deploy Windows Defender Application Control polices](https://docs.microsoft.com/windows/security/threat-protection/windows-defender-application-control/deploy-windows-defender-application-control-policies-using-group-policy).
76+
6. Reboot the machine and confirm the Code Integrity event 3099 shows that the policy is activated.
77+
- Open Event Viewer (Select Start, type Event Viewer) &rarr; Applications and Services Logs &rarr; Microsoft &rarr; Windows &rarr; CodeIntegrity &rarr; Operational
78+
- Filter by event Id 3099
79+
>[!NOTE]
80+
> If you don't see event 3099, DON'T proceed to step 7. Restart from No.1 and make sure your CI policy file is well formed and successfully signed.
81+
- Well formed: Compare the xml with the [default CI policy xml](https://learn.microsoft.com/windows/security/application-security/application-control/windows-defender-application-control/design/example-wdac-base-policies) to verify the format.
82+
- Successfully signed: To verify, use SignTool; refer to this [link](https://docs.microsoft.com/windows/win32/seccrypto/using-signtool-to-verify-a-file-signature).
83+
84+
7. Run the command to delete this CI policy: `del SiPolicy.p7b` from both folders: C:\Windows\System32\CodeIntegrity and S:\EFI\Microsoft\Boot.
85+
1. If there's no S: drive, run the command:  
86+
`mountvol.exe s: /s`.
87+
2. If your machine already has an S: drive, mount the EFI partition to a different letter, such as X.
88+
3. If there's no EFI partition in the machine, ignore the EFI deletion step (if there's no /s option for the command mountvol.exe).
89+
8. Reboot the machine once deletion is completed.
90+
9. Reboot the machine twice more, to ensure the CI policy is properly removed, before moving on or deploying this change to other machines.
91+
92+
### Step 2: Deploy and Test the new CI policy on the same machine.
93+
1. Continue to the steps outlined in Scenario 2.
94+
95+
## Scenario 2: Unsigned to Signed CI Policy Migration & Deployment
96+
97+
### Step 1: Determine your new EKUs
98+
99+
1. Since Trusted Signing is a new service it has different EKUs than DGSSv2. Therefore, you need to get the new EKUs added to your policy. You need to get your EKU from the Trusted Signing account to add to your CI policy’s EKU section. The two ways to do so are:
100+
1. Using the steps in [Sign a CI policy | Microsoft Learn](https://learn.microsoft.com/azure/trusted-signing/how-to-sign-ci-policy) run the command Get-AzCodeSigningCustomerEkuto get the customer EKU.
101+
2. Within your Trusted Signing account, select “Certificate Profiles”, then select your Private Trust certificate profile. You'll see information on the profile like the screenshot below. The ‘Enhanced key usage’ listed is your customer EKU.
102+
103+
:::image type="content" source="media/trusted-signing-select-eku.png" alt-text="Screenshot that shows eku." lightbox="media/trusted-signing-select-eku.png":::
104+
105+
2. Now that you have the customer EKU. You'll need to generate a function EKU. To do so pass the customer EKU into the code below. The output is your function EKU.
106+
```
107+
private string CalculateEkuValue(string CustomerEku)
108+
{
109+
     var ekuOid = CryptoConfig.EncodeOID(CustomerEku);
110+
     var ekuBit = BitConverter.ToString(ekuOid).Replace("-", "");
111+
112+
     var ekuArray = ekuBit.ToCharArray();
113+
     ekuArray[1] = '1';
114+
115+
     return new string(ekuArray);
116+
}
117+
```
118+
119+
### Step 2: Deploy and Test the new CI policy.
120+
121+
1. Now that you have your two EKUs, it is time to edit your CI policy. If you have an existing CI policy, you can proceed to the next section. To create a new one go to: [Policy creation for common WDAC usage scenarios - Windows Security | Microsoft Learn](https://learn.microsoft.com/windows/security/application-security/application-control/windows-defender-application-control/design/common-wdac-use-cases).
122+
2. Add the new EKU in the EKU section of your policy, using the two EKU values from Step 1.
123+
```
124+
<EKU ID="ID_EKU_ACS" FriendlyName="ACS EKU -Customer EKU" Value="function EKU"/>
125+
```
126+
127+
3. Verify these signers are present/added in the CI policy:
128+
129+
```
130+
<Signer ID="ID_SIGNER_ACS_CODE" Name="Your Account Name Code Signing Certificate">
131+
132+
<CertRoot Value="28D3FAEF436A9D7644F01BEFFBF9E143AE6FB7A00B125F86CC9594A078980904B0597DF0F6BDD15E65E80F4D74E6D606" Type="TBS"/>
133+
134+
<CertEKU ID="ID_EKU_ACS"/>
135+
136+
</Signer>
137+
138+
<Signer ID="ID_SIGNER_ACS_POLICY" Name="Your Account Name CI Policy Signing Certificate">
139+
140+
<CertRoot Type="TBS" Value="FC9C3E96720126881A6CEA067B5EA11ED0ABFC77835F720EDCFF4660C9A59669"/>
141+
142+
<CertEKU ID="ID_EKU_ACS"/>
143+
144+
</Signer>
145+
```
146+
147+
**Your Account Name Code Signing Certificate** is your Trusted Signing account name. Note that this field isn't verified in the CI policy, but we recommend you putting your Trusted signing account name in the field. To find your account name on the Azure portal navigate to [Azure portal](https://portal.azure.com/), search “Trusted Signing” in the top search bar and select your account that comes up in the search results. The screenshot below shows the account name outlined in red.
148+
149+
:::image type="content" source="media/trusted-signing-account-overview.png" alt-text="Screenshot that shows account overview." lightbox="media/trusted-signing-account-overview.png":::
150+
151+
4. Convert the .xml to .bin policy file using the following command: ConvertFrom-CIPolicy
152+
153+
Sample:
154+
```
155+
ConvertFrom-CIPolicy -XmlFilePath <xmlCIPolicyFilePath> -BinaryFilePath <binaryCIPolicyFilePath>
156+
```
157+
158+
5. If you would like to sign this policy, following these instructions [Sign a CI policy | Microsoft Learn](https://learn.microsoft.com/azure/trusted-signing/how-to-sign-ci-policy)to sign the policy using Trusted Signing.
159+
160+
6. Deploy this signed policy .bin file; refer to this [link](https://docs.microsoft.com/windows/security/threat-protection/windows-defender-application-control/windows-defender-application-control-deployment-guide) for instructions.
161+
162+
7. Reboot the machine and confirm that Code Integrity event 3099 is showing, which means the new CI policy is activated.
163+
1. **Note**: If you don't see event 3099, DON'T proceed to step 8. Restart from No.1 and make sure your CI policy file is well formed and successfully signed.
164+
1. Well formed: Compare the xml with the default CI policy xml to verify the format.
165+
2. Successfully signed: To verify, use SignTool; refer to this [link](https://docs.microsoft.com/windows/win32/seccrypto/using-signtool-to-verify-a-file-signature).
166+
8. Reboot the machine again to ensure a successful boot.
167+
9. Reboot the machine twice more, to ensure the CI policy is properly enabled, before moving on or deploying this change to other machines.
168+
169+
170+
### Step 3: Perform testing to validate that the new policy does not break any expected scenarios.
171+
172+
1. Verify that any files signed with Trusted Signing still behave as expected.
173+
2. Sign a catalog file with Trusted Signing and make sure it can run on your test machine with the Trusted Signing (new) CI policy.
174+
1. To sign catalog files with Trusted Signing, refer to the steps in:
175+
1. [Quickstart: Set up Trusted Signing | Microsoft Learn](https://learn.microsoft.com/azure/trusted-signing/quickstart?tabs=registerrp-portal%2Caccount-portal%2Ccertificateprofile-portal%2Cdeleteresources-portal) to set up a Private Trust certificate profile.
176+
2. [Set up signing integrations to use Trusted Signing | Microsoft Learn](https://learn.microsoft.com/azure/trusted-signing/how-to-signing-integrations) to sign the files using Private Trust in the Trusted Signing service.
177+
178+
2. To sign MSIX packages with Trusted Signing, refer to instructions on how to sign MSIX packages with [MSIX Packaging Tool](https://learn.microsoft.com/windows/msix/packaging-tool/tool-overview) or SignTool - directly through Trusted Signing.
179+
1. To sign with Trusted Signing in the MSIX Packaging Tool you need to join the MSIX Insiders program.
180+
181+
3. After confirming the CI policy is activated on this machine and all scenarios work as expected, repeat steps on the rest of the desired machines in your environment.
182+
183+
## Scenario 3: Unsigned to Unsigned CI Policy Migration & Deployment
184+
185+
You need to add the Trusted Signing EKUs to your existing CI policy by following the steps in Scenario 2 to locate and update the EKUs.
186+
187+
## Scenario 4: No Existing CI Policy
188+
189+
If isolation is desired, deploy a new CI policy by following steps outlined in Scenario 2.
190+
191+
192+
## Related Content
193+
194+
1. [Understand Windows Defender Application Control (WDAC) policy rules and file rules](https://docs.microsoft.com/windows/security/threat-protection/windows-defender-application-control/select-types-of-rules-to-create).
195+
2. [Deploy catalog files to support Windows Defender Application Control (Windows 10) - Windows security](https://docs.microsoft.com/windows/security/threat-protection/windows-defender-application-control/deploy-catalog-files-to-support-windows-defender-application-control#:~:text=%20Deploy%20catalog%20files%20to%20support%20Windows%20Defender,signing%20certificate%20to%20a%20Windows%20Defender...%20More%20).
196+
3. [Example Windows Defender Application Control (WDAC) base policies (Windows 10) - Windows security | Microsoft Docs](https://docs.microsoft.com/windows/security/threat-protection/windows-defender-application-control/example-wdac-base-policies)
197+
4. [Use multiple Windows Defender Application Control Policies (Windows 10)](https://docs.microsoft.com/windows/security/threat-protection/windows-defender-application-control/deploy-multiple-windows-defender-application-control-policies#deploying-multiple-policies-locally)

0 commit comments

Comments
 (0)