From 067bc3fb90e579adc6822bff81fc04a0b92fe845 Mon Sep 17 00:00:00 2001 From: Linda Diefendorf Date: Mon, 9 Aug 2021 11:59:09 -0700 Subject: [PATCH] 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: