From 067bc3fb90e579adc6822bff81fc04a0b92fe845 Mon Sep 17 00:00:00 2001 From: Linda Diefendorf Date: Mon, 9 Aug 2021 11:59:09 -0700 Subject: [PATCH 1/4] Update device-guard-signing-portal.md Updating to include v2 cmdlet descriptions --- .../device-guard-signing-portal.md | 125 +++++++++++++++++- 1 file changed, 124 insertions(+), 1 deletion(-) diff --git a/store-for-business/device-guard-signing-portal.md b/store-for-business/device-guard-signing-portal.md index c6c8eeb5e5..64da5a18ce 100644 --- a/store-for-business/device-guard-signing-portal.md +++ b/store-for-business/device-guard-signing-portal.md @@ -43,7 +43,7 @@ ms.date: 07/21/2021 - Windows 10 - Windows 10 Mobile -Device Guard signing is a Device Guard feature that is available in Microsoft Store for Business and Education. It gives admins a single place to sign catalog files and code integrity policies. After admins have created catalog files for unsigned apps and signed the catalog files, they can add the signers to a code integrity policy. You can merge the code integrity policy with your existing policy to include your custom signing certificate. This allows you to trust the catalog files. +Device Guard signing is a Device Guard feature that gives admins a single place to sign catalog files and code integrity policies. After admins have created catalog files for unsigned apps and signed the catalog files, they can add the signers to a code integrity policy. You can merge the code integrity policy with your existing policy to include your custom signing certificate. This allows you to trust the catalog files. Device Guard is a feature set that consists of both hardware and software system integrity hardening features. These features use new virtualization-based security options and the trust-nothing mobile device operating system model. A key feature in this model is called configurable code integrity, which allows your organization to choose exactly which software or trusted software publishers are allowed to run code on your client machines. Also, Device Guard offers organizations a way to sign existing line-of-business (LOB) applications so that they can trust their own code, without the requirement that the application be repackaged. Also, this same method of signing allows organizations to trust individual third-party applications. For more information, see [Device Guard deployment guide](/windows/device-security/device-guard/device-guard-deployment-guide). @@ -54,6 +54,129 @@ Device Guard is a feature set that consists of both hardware and software system | [Add unsigned app to code integrity policy](add-unsigned-app-to-code-integrity-policy.md) | When you want to add an unsigned app to a code integrity policy, you need to start with a code integrity policy created from a reference device. Then, create the catalog files for your unsigned app, sign the catalog files, and then merge the default policy that includes your signing certificate with existing code integrity policies. | | [Sign code integrity policy with Device Guard signing](sign-code-integrity-policy-with-device-guard-signing.md) | Signing code integrity policies prevents policies from being tampered with after they're deployed. You can sign code integrity policies with the Device Guard signing portal. | +## Device Guard Signing Service (v2) PowerShell Commands + +_Note: [.. common ..] are parameters common across all commands that are documented below the command definitions._ + +**Get-DefaultPolicy** Gets the default .xml policy file associated with the current tenant. + +- Usage: + +``` +Get-DefaultPolicy -OutFile filename [-PassThru] [.. common ..] +``` + +- Parameters: + + **OutFile** - string, mandatory - The filename where the default policy file should be persisted to disk. The file name should be an .xml file. If the file already exists, it will be overwritten (note: create the folder first). + + **PassThru** - switch, optional - If present, returns an XmlDocument object returning the default policy file. + +- Command running time: + + The average running time is under 20 seconds but may be up to 3 minutes. + +**Get-RootCertificate** Gets the root certificate for the current tenant. All Authenticode and policy signing certificates will eventually chain up to this root certificate. + +- Usage: + + ``` + Get-RootCertificate -OutFile filename [-PassThru] [.. common ..] + ``` + +- Parameters: + + **OutFile** - string, mandatory - The filename where the root certificate file should be persisted to disk. The file name should be a .cer file. If the file already exists, it will be overwritten (note: create the folder first). + + **PassThru** - switch, optional - If present, returns an X509Certificate2 object returning the default + policy file. + +- Command running time: + + The average running time is under 20 seconds but may be up to 3 minutes. + +**Get-SigningHistory** Gets information for the latest 100 files signed by the current tenant. Results are returned as a collection with elements in reverse chronological order (most recent to least recent). + +- Usage: + + ``` + Get-SigningHistory -OutFile filename [-PassThru] [.. common ..] + ``` + +- Parameters: + + **OutFile** - string, mandatory - The filename where the signing history file should be persisted to disk. The file name should be a .xml file. If the file already exists, it will be overwritten (note: create the folder first). + + **PassThru** - switch, optional - If present, returns XML objects returning the XML file. + +- Command running time: + + The average running time is under 10 seconds. + +**Submit-SigningJob** Submits a file to the service for signing and timestamping. The module supports valid file type for Authenticode signing is Catalog file (.cat). Valid file type for policy signing is binary policy files with the extension (.bin) that have been created via the ConvertFrom-CiPolicy cmdlet. Otherwise, binary policy file may not be deployed properly. + +- Usage: + + ``` + Submit-SigningJob -InFile filename -OutFile filename [-NoTimestamp][- TimeStamperUrl "timestamper url"] [-JobDescription "description"] [.. common ..] + ``` + +- Parameters: + + **InFile** - string, mandatory - The file to be signed. This should be a file of the types described in description above (.cat or .bin). + + **OutFile** - string, mandatory - The output file that should be generated by the signing process. If this file already exists, it will be overwritten. (note: create the folder first) + + **NoTimestamp** - switch, optional - If present, the signing operation will skip timestamping the output file, and it will be signed only. If not present (default) and TimeStamperUrl presents, the output file will be both signed and timestamped. If both NoTimestamp and TimeStamperUrl not present, the signing operation will skip timestamping the output file, and it will be signed only. + + **TimeStamperUrl** - string, optional - If this value is invalid Url (and NoTimestamp not present), the module will throw exception. To understand more about timestamping, refer to [Timestamping](https://docs.microsoft.com/en-us/windows/msix/package/signing-package-overview#timestamping). + + **JobDescription** - string, optional - A short (< 100 chars), human-readable description of this submission. If the script is being called as part of an automated build rocess the agent may wish to pass a version number or changeset number for this field. This information will be provided as part of the results of the Get-SigningHistory command. + +**Submit-SigningV1MigrationPolicy** Submits a file to the service for signing and timestamping. The only valid file type for policy +signing is binary policy files with the extension (.bin) that have been created via the [ConvertFromCiPolicy](https://docs.microsoft.com/en-us/powershell/module/configci/convertfrom-cipolicy?view=windowsserver2019-ps&viewFallbackFrom=win10-ps) cmdlet. Otherwise, binary policy file may not be deployed properly. Note: Only use for V1 migration. + +- Usage: + + ``` + Submit-SigningV1MigrationPolicy -InFile filename -OutFile filename [-NoTimestamp][-TimeStamperUrl "timestamper url"] [-JobDescription "description"] [.. common ..] + ``` + +- Parameters: + + **InFile** - string, mandatory - The file to be signed. This should be a file of the types described in description above (.bin). + + **OutFile** - string, mandatory - The output file that should be generated by the signing process. If this file already exists, it will be overwritten (note: create the folder first). + + **NoTimestamp** - switch, optional - If present, the signing operation will skip timestamping the output file, and it will be signed only. If not present (default) and TimeStamperUrl presents, the output file will be both signed and timestamped. If both NoTimestamp and TimeStamperUrl not present, the signing operation will skip timestamping the output file, and it will be signed only. + + **TimeStamperUrl** - string, optional - If this value is invalid Url (and NoTimestamp not present), the module will throw exception. To understand more about timestamping, refer to [Timestamping](https://docs.microsoft.com/en-us/windows/msix/package/signing-package-overview#timestamping). + + **JobDescription** - string, optional - A short (< 100 chars), human-readable description of this submission. If the script is being called as part of an automated build process the agent may wish to pass a version number or changeset number for this field. This information will be provided as part of the results of the Get-SigningHistory command. + +- Command running time: + + The average running time is under 20 seconds but may be up to 3 minutes. + +**Common parameters [.. common ..]** + +In addition to cmdlet-specific parameters, each cmdlet understands the following common parameters. + +- Usage: + + ``` + ... [-NoPrompt] [-Credential $creds] [-AppId AppId] [-Verbose] + ``` + +- Parameters: + + **NoPrompt** - switch, optional - If present, indicates that the script is running in a headless + environment and that all UI should be suppressed. If UI must be displayed (e.g., for + authentication) when the switch is set, the operation will instead fail. + + **Credential + AppId** - PSCredential - A login credential (username and password) and AppId. + + ## File and size limits When you're uploading files for Device Guard signing, there are a few limits for files and file size: From 1db546b1437fc6ff5c33315c34433ada3ada0505 Mon Sep 17 00:00:00 2001 From: Cern McAtee Date: Mon, 9 Aug 2021 13:16:02 -0700 Subject: [PATCH 2/4] Fixed !NOTES and added codeblock IDs --- .../device-guard-signing-portal.md | 33 ++++++++++--------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/store-for-business/device-guard-signing-portal.md b/store-for-business/device-guard-signing-portal.md index 64da5a18ce..f13413106a 100644 --- a/store-for-business/device-guard-signing-portal.md +++ b/store-for-business/device-guard-signing-portal.md @@ -17,6 +17,11 @@ ms.date: 07/21/2021 # Device Guard signing +**Applies to** + +- Windows 10 +- Windows 10 Mobile + > [!IMPORTANT] > Microsoft Store for Business and Microsoft Store for Education will be retired in the first quarter of 2023. You can continue to use the current capabilities of free apps until that time. For more information about this change, see [Evolving the Microsoft Store for Business and Education](https://aka.ms/windows/msfb_evolution). @@ -37,12 +42,6 @@ ms.date: 07/21/2021 > > For any questions, please contact us at DGSSMigration@microsoft.com. - -**Applies to** - -- Windows 10 -- Windows 10 Mobile - Device Guard signing is a Device Guard feature that gives admins a single place to sign catalog files and code integrity policies. After admins have created catalog files for unsigned apps and signed the catalog files, they can add the signers to a code integrity policy. You can merge the code integrity policy with your existing policy to include your custom signing certificate. This allows you to trust the catalog files. Device Guard is a feature set that consists of both hardware and software system integrity hardening features. These features use new virtualization-based security options and the trust-nothing mobile device operating system model. A key feature in this model is called configurable code integrity, which allows your organization to choose exactly which software or trusted software publishers are allowed to run code on your client machines. Also, Device Guard offers organizations a way to sign existing line-of-business (LOB) applications so that they can trust their own code, without the requirement that the application be repackaged. Also, this same method of signing allows organizations to trust individual third-party applications. For more information, see [Device Guard deployment guide](/windows/device-security/device-guard/device-guard-deployment-guide). @@ -56,16 +55,17 @@ Device Guard is a feature set that consists of both hardware and software system ## Device Guard Signing Service (v2) PowerShell Commands -_Note: [.. common ..] are parameters common across all commands that are documented below the command definitions._ +> [!NOTE] +> [.. common ..] are parameters common across all commands that are documented below the command definitions. **Get-DefaultPolicy** Gets the default .xml policy file associated with the current tenant. - Usage: -``` +```powershell Get-DefaultPolicy -OutFile filename [-PassThru] [.. common ..] ``` - + - Parameters: **OutFile** - string, mandatory - The filename where the default policy file should be persisted to disk. The file name should be an .xml file. If the file already exists, it will be overwritten (note: create the folder first). @@ -80,7 +80,7 @@ Get-DefaultPolicy -OutFile filename [-PassThru] [.. common ..] - Usage: - ``` + ```powershell Get-RootCertificate -OutFile filename [-PassThru] [.. common ..] ``` @@ -99,7 +99,7 @@ Get-DefaultPolicy -OutFile filename [-PassThru] [.. common ..] - Usage: - ``` + ```powershell Get-SigningHistory -OutFile filename [-PassThru] [.. common ..] ``` @@ -117,7 +117,7 @@ Get-DefaultPolicy -OutFile filename [-PassThru] [.. common ..] - Usage: - ``` + ```powershell Submit-SigningJob -InFile filename -OutFile filename [-NoTimestamp][- TimeStamperUrl "timestamper url"] [-JobDescription "description"] [.. common ..] ``` @@ -138,7 +138,7 @@ signing is binary policy files with the extension (.bin) that have been created - Usage: - ``` + ```powershell Submit-SigningV1MigrationPolicy -InFile filename -OutFile filename [-NoTimestamp][-TimeStamperUrl "timestamper url"] [-JobDescription "description"] [.. common ..] ``` @@ -146,7 +146,10 @@ signing is binary policy files with the extension (.bin) that have been created **InFile** - string, mandatory - The file to be signed. This should be a file of the types described in description above (.bin). - **OutFile** - string, mandatory - The output file that should be generated by the signing process. If this file already exists, it will be overwritten (note: create the folder first). + **OutFile** - string, mandatory - The output file that should be generated by the signing process. If this file already exists, it will be overwritten. + + > [!NOTE] + > Create the folder first. **NoTimestamp** - switch, optional - If present, the signing operation will skip timestamping the output file, and it will be signed only. If not present (default) and TimeStamperUrl presents, the output file will be both signed and timestamped. If both NoTimestamp and TimeStamperUrl not present, the signing operation will skip timestamping the output file, and it will be signed only. @@ -164,7 +167,7 @@ In addition to cmdlet-specific parameters, each cmdlet understands the following - Usage: - ``` + ```powershell ... [-NoPrompt] [-Credential $creds] [-AppId AppId] [-Verbose] ``` From a78fbd5a5681f4b083526008ded57c768857c904 Mon Sep 17 00:00:00 2001 From: Gary Moore Date: Mon, 9 Aug 2021 18:11:28 -0700 Subject: [PATCH 3/4] Fixed hard-coded locales and absolute links This corrects links that were absolute, rather than site-relative, and/or that had hard-coded locales, adding in the public repo in commit https://github.com/MicrosoftDocs/windows-itpro-docs/pull/9888/commits/067bc3fb90e579adc6822bff81fc04a0b92fe845 --- store-for-business/device-guard-signing-portal.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/store-for-business/device-guard-signing-portal.md b/store-for-business/device-guard-signing-portal.md index f13413106a..433f0bb68a 100644 --- a/store-for-business/device-guard-signing-portal.md +++ b/store-for-business/device-guard-signing-portal.md @@ -129,12 +129,12 @@ Get-DefaultPolicy -OutFile filename [-PassThru] [.. common ..] **NoTimestamp** - switch, optional - If present, the signing operation will skip timestamping the output file, and it will be signed only. If not present (default) and TimeStamperUrl presents, the output file will be both signed and timestamped. If both NoTimestamp and TimeStamperUrl not present, the signing operation will skip timestamping the output file, and it will be signed only. - **TimeStamperUrl** - string, optional - If this value is invalid Url (and NoTimestamp not present), the module will throw exception. To understand more about timestamping, refer to [Timestamping](https://docs.microsoft.com/en-us/windows/msix/package/signing-package-overview#timestamping). + **TimeStamperUrl** - string, optional - If this value is invalid Url (and NoTimestamp not present), the module will throw exception. To understand more about timestamping, refer to [Timestamping](/windows/msix/package/signing-package-overview#timestamping). **JobDescription** - string, optional - A short (< 100 chars), human-readable description of this submission. If the script is being called as part of an automated build rocess the agent may wish to pass a version number or changeset number for this field. This information will be provided as part of the results of the Get-SigningHistory command. **Submit-SigningV1MigrationPolicy** Submits a file to the service for signing and timestamping. The only valid file type for policy -signing is binary policy files with the extension (.bin) that have been created via the [ConvertFromCiPolicy](https://docs.microsoft.com/en-us/powershell/module/configci/convertfrom-cipolicy?view=windowsserver2019-ps&viewFallbackFrom=win10-ps) cmdlet. Otherwise, binary policy file may not be deployed properly. Note: Only use for V1 migration. +signing is binary policy files with the extension (.bin) that have been created via the [ConvertFromCiPolicy](/powershell/module/configci/convertfrom-cipolicy?view=windowsserver2019-ps&viewFallbackFrom=win10-ps) cmdlet. Otherwise, binary policy file may not be deployed properly. Note: Only use for V1 migration. - Usage: @@ -153,7 +153,7 @@ signing is binary policy files with the extension (.bin) that have been created **NoTimestamp** - switch, optional - If present, the signing operation will skip timestamping the output file, and it will be signed only. If not present (default) and TimeStamperUrl presents, the output file will be both signed and timestamped. If both NoTimestamp and TimeStamperUrl not present, the signing operation will skip timestamping the output file, and it will be signed only. - **TimeStamperUrl** - string, optional - If this value is invalid Url (and NoTimestamp not present), the module will throw exception. To understand more about timestamping, refer to [Timestamping](https://docs.microsoft.com/en-us/windows/msix/package/signing-package-overview#timestamping). + **TimeStamperUrl** - string, optional - If this value is invalid Url (and NoTimestamp not present), the module will throw exception. To understand more about timestamping, refer to [Timestamping](/windows/msix/package/signing-package-overview#timestamping). **JobDescription** - string, optional - A short (< 100 chars), human-readable description of this submission. If the script is being called as part of an automated build process the agent may wish to pass a version number or changeset number for this field. This information will be provided as part of the results of the Get-SigningHistory command. @@ -189,7 +189,7 @@ When you're uploading files for Device Guard signing, there are a few limits for | Maximum size for multiple files (uploaded in a group) | 4 MB | | Maximum number of files per upload | 15 files | - ## File types +## File types Catalog and policy files have required files types. | File | Required file type | @@ -197,7 +197,7 @@ Catalog and policy files have required files types. | catalog files | .cat | | policy files | .bin | - ## Store for Business roles and permissions +## Store for Business roles and permissions Signing code integrity policies and access to Device Guard portal requires the Device Guard signer role. ## Device Guard signing certificates From 9eb9a04e036b1f7995acf044246f19ea6f318564 Mon Sep 17 00:00:00 2001 From: Gary Moore Date: Mon, 9 Aug 2021 18:36:12 -0700 Subject: [PATCH 4/4] Corrected indentation in preview; tidied indentation in source --- .../device-guard-signing-portal.md | 37 +++++++++---------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/store-for-business/device-guard-signing-portal.md b/store-for-business/device-guard-signing-portal.md index 433f0bb68a..3c5210990f 100644 --- a/store-for-business/device-guard-signing-portal.md +++ b/store-for-business/device-guard-signing-portal.md @@ -62,46 +62,45 @@ Device Guard is a feature set that consists of both hardware and software system - Usage: -```powershell -Get-DefaultPolicy -OutFile filename [-PassThru] [.. common ..] -``` + ```powershell + Get-DefaultPolicy -OutFile filename [-PassThru] [.. common ..] + ``` - Parameters: - **OutFile** - string, mandatory - The filename where the default policy file should be persisted to disk. The file name should be an .xml file. If the file already exists, it will be overwritten (note: create the folder first). + **OutFile** - string, mandatory - The filename where the default policy file should be persisted to disk. The file name should be an .xml file. If the file already exists, it will be overwritten (note: create the folder first). - **PassThru** - switch, optional - If present, returns an XmlDocument object returning the default policy file. + **PassThru** - switch, optional - If present, returns an XmlDocument object returning the default policy file. - Command running time: - The average running time is under 20 seconds but may be up to 3 minutes. + The average running time is under 20 seconds but may be up to 3 minutes. **Get-RootCertificate** Gets the root certificate for the current tenant. All Authenticode and policy signing certificates will eventually chain up to this root certificate. - Usage: - ```powershell - Get-RootCertificate -OutFile filename [-PassThru] [.. common ..] - ``` + ```powershell + Get-RootCertificate -OutFile filename [-PassThru] [.. common ..] + ``` - Parameters: - **OutFile** - string, mandatory - The filename where the root certificate file should be persisted to disk. The file name should be a .cer file. If the file already exists, it will be overwritten (note: create the folder first). + **OutFile** - string, mandatory - The filename where the root certificate file should be persisted to disk. The file name should be a .cer file. If the file already exists, it will be overwritten (note: create the folder first). - **PassThru** - switch, optional - If present, returns an X509Certificate2 object returning the default - policy file. + **PassThru** - switch, optional - If present, returns an X509Certificate2 object returning the default policy file. - Command running time: - The average running time is under 20 seconds but may be up to 3 minutes. + The average running time is under 20 seconds but may be up to 3 minutes. **Get-SigningHistory** Gets information for the latest 100 files signed by the current tenant. Results are returned as a collection with elements in reverse chronological order (most recent to least recent). - Usage: - ```powershell - Get-SigningHistory -OutFile filename [-PassThru] [.. common ..] - ``` + ```powershell + Get-SigningHistory -OutFile filename [-PassThru] [.. common ..] + ``` - Parameters: @@ -117,9 +116,9 @@ Get-DefaultPolicy -OutFile filename [-PassThru] [.. common ..] - Usage: - ```powershell - Submit-SigningJob -InFile filename -OutFile filename [-NoTimestamp][- TimeStamperUrl "timestamper url"] [-JobDescription "description"] [.. common ..] - ``` + ```powershell + Submit-SigningJob -InFile filename -OutFile filename [-NoTimestamp][- TimeStamperUrl "timestamper url"] [-JobDescription "description"] [.. common ..] + ``` - Parameters: