Signing an MSIX package (sign)

This article is about the usage of command line interface. More information about CLI usage and how to get started can be found here: Command Line Interface (CLI) Reference

Signing consists of two steps:

• Adjusting of the manifest file, so that the package publisher (subject) matches the certificate subject.
• Actual signing, using a specific callout of signtool.exe.

The command uses one of the four syntaxes:

Signing with PFX file:

MSIXHeroCLI.exe sign --file <path-to-pfx-file> [--password <certificate-password>] [--timestamp <timestamp-server-url>] [--increaseVersion Major|Minor|Build|Revision|None] [--noPublisherUpdate] <path1> [<path2> [<path3>...]]

Signing with an installed certificate (by thumprint)

MSIXHeroCLI.exe sign --sha1 <certificate-thumbprint> [--sm] [--timestamp <timestamp-server-url>] [--increaseVersion Major|Minor|Build|Revision|None] [--noPublisherUpdate] <path1> [<path2> [<path3>...]]

Signing with Device Guard

This function requires MSIX Hero 1.5.0 or newer

MSIXHeroCLI.exe sign --dg [--dgv1] [--dgp <publisher-name>] [--timestamp <timestamp-server-url>] [--increaseVersion Major|Minor|Build|Revision|None] <path1> [<path2> [<path3>...]]
MSIXHeroCLI.exe sign --dgf <json-token-file> [--dgp <publisher-name>] [--dgv1] [--timestamp <timestamp-server-url>] [--increaseVersion Major|Minor|Build|Revision|None] [--noPublisherUpdate] <path1> [<path2> [<path3>...]]

Signing with current profile settings

MSIXHeroCLI.exe sign [--increaseVersion Major|Minor|Build|Revision|None] [--noPublisherUpdate] <path1> [<path2> [<path3>...]]

Examples:

MSIXHeroCLI.exe sign --sha1 "a909502dd82ae41433e6f83886b00d4277a32a7b" --increaseVersion Minor "c:\packages\package1.msix"
MSIXHeroCLI.exe sign --sha1 "a909502dd82ae41433e6f83886b00d4277a32a7b" --sm "c:\packages\package1.msix" "c:\packages\package2.msix"
MSIXHeroCLI.exe sign --sha1 "a909502dd82ae41433e6f83886b00d4277a32a7b" --timestamp "http://timestamp.comodoca.com" "c:\packages\package1.msix"
MSIXHeroCLI.exe sign --file "C:\certificates\self-signed.pfx" --password "Start123" --increaseVersion Major "c:\packages\package1.msix"
MSIXHeroCLI.exe sign --file "C:\certificates\self-signed.pfx" --password "Start123" --timestamp "http://timestamp.comodoca.com" "c:\packages\package1.msix" "c:\packages\package2.msix"
MSIXHeroCLI.exe sign --dg --timestamp "http://timestamp.comodoca.com" "c:\packages\package1.msix" "c:\packages\package2.msix"
MSIXHeroCLI.exe sign --dgf c:\temp\auth.json --timestamp "http://timestamp.comodoca.com" "c:\packages\package1.msix" "c:\packages\package2.msix"

You can also use shorter form of arguments. In that case, the command line will be very similar to the one used by SignTool.exe (see link):

MSIXHeroCLI.exe sign --sha1 "a909502dd82ae41433e6f83886b00d4277a32a7b" -i Minor "c:\packages\package1.msix"
MSIXHeroCLI.exe sign --sha1 "a909502dd82ae41433e6f83886b00d4277a32a7b" --sm "c:\packages\package1.msix" "c:\packages\package2.msix"
MSIXHeroCLI.exe sign --sha1 "a909502dd82ae41433e6f83886b00d4277a32a7b" -t "http://timestamp.comodoca.com" "c:\packages\package1.msix"
MSIXHeroCLI.exe sign -f "C:\certificates\self-signed.pfx" -p "Start123" -i Major "c:\packages\package1.msix"
MSIXHeroCLI.exe sign -f "C:\certificates\self-signed.pfx" -p "Start123" -t "http://timestamp.comodoca.com" "c:\packages\package1.msix" "c:\packages\package2.msix"

It is recommended to put the paths to the file(s) being signed at the end. Do not forget to surround them by quotation if the paths contain spaces.

Note: Syntax for this command uses a limited subset of features and commands of signtool.exe. For example, you can use -f, -p, -t and --sha1 to specify the PFX path, password, timestamp URL and certificate thumbprint respectively. The additional value of MSIX Hero in comparison to signtool.exe is that the package manifest is adjusted automatically.

The following parameters are optional:

• --sm (as in StoreMachine)
  Specifies that a machine store, instead of a user store, is used. This is a boolean switch, it does not have to be followed by any value. If omitted, the certificate will be looked up in the machine store. This switch makes only sense when combined with --sha1 value.
• --sha1 <thumbprint>
  Selects the certificate based on its thumbprint value. May not be combined with –file.
• --file <pfx-file>
  The full path to PFX file used for signing. May not be combined with --sha1.
• --password <password>
  Specifies the password for the selected PFX file. May not be combined with --sha1, requires that –file switch is used.
• --timestamp <timestamp-url>
  The timestamp URL. Ensures that the package will be still signed, even if the original certificate is expired.
• --increaseVersion Major|Minor|Build|Revision|None
  Specifies, that the package version should be automatically increased by one when signing. By providing the value, you may choose which component should be increased. The default value (used when no switch is present) is None which means that the package version will stay the same after signing.
• --noPublisherUpdate
  Prevents MSIX Hero from updating the publisher name. By default, the publisher name is taken from the certificate subject – both of them must be the same for the signing to succeed. If you want to control the publisher name on your own or have a granular error reporting in case of mismatches, use this switch. In case of a mismatch, an error will be reported.
• --dg (as in Device Guard)
  Specifies that Device Guard Signing is to be used. The login will be performed interactively, that is in a pop-window that will be spawned after executing the command. This option should not be used for silent, unattended signing, because it will wait for a dialog to be confirmed by the user. This switch must not be combined with –dgf.
• --dgf <file-path> (as in Device Guard File)
  Specifies that Device Guard Signing is to be used. The JSON file path must contain valid access and refresh token, which you should create on your own using the technique outlined here: https://docs.microsoft.com/en-us/windows/msix/package/signing-package-device-guard-signing#get-an-azure-ad-access-token. This switch must not be combined with –dg.
• --dgv1 (as in Device Guard V1)
  Specifies that the DGSS v1 API will be used. Usage of V1 is not recommended because the API is obsolete and will be deprecated soon. This switch must be used together with –dg or –dgf.
• --dgp <publisher-name> (as in Device Guard Publisher)
  Specifies the name (publisher name) used for signing. If this parameter is omitted, MSIX Hero will determine the name for you. This option is recommended if you know the name, because signing without this switch requires an extra round trip to AzureAD and making a test signing. If this switch is used, you should make sure that the value matches the actual certificate subject, otherwise an error will be returned. This switch must be used together with –dg or –dgf. This switch has no effect if --noPublisherUpdate is used.

The result of execution is a signed MSIX package. Depending on the selected certificate, the package may have a new identity due to a changed Publisher value (which should match the subject of the certificate). The program returns the following exit codes:

Exit code	Meaning
0	The signing succeeded.
1	Unspecified error.
2-10	Invalid parameters or other command-line related errors.
<any other>	Internal exit code from signtool.exe.

Best practises

• If possible you should consider using a certificate installed in the Store (using the --sha1 switch) or Device Guard, both of them require no password specification and prevent leaking of private keys. PFX option on the other hand is usually great for tests and labs.
• Usually, it is much easier to have MSIX Hero preconfigured for signing (by starting it once and going to Settings, where the default certificate can be selected). This way, the command line for signing is much easier, because effectively the only required switch is the file name to be signed.

Notes

• The original publisher name (defined in AppxManifest.xml) will be changed to the subject of the certificate file used for the signing. This is usually desirable for testing, but take into account that it also breaks the package identity and ability to update older versions if the certificate subject has changed or another certificate has been used in subsequent signing. In MSIX Hero 1.5.0 or newer, you can use command line switch --noPublisherUpdate to prevent this behavior from happening. In this case, an error will be returned if the publisher name and the certificate subject do not match.
• Using Device Guard in interactive mode spawns a window, where the required credentials must be provided. Your login credentials are not stored anywhere. The whole communication, authentication and authorization is delegated to the Microsoft Authentication Library. Once the interactive signing is finished no traces are left behind.