Sign Manifest files with Mage using KSP library
mage.exe (Manifest Generation and Editing Tool) is a command-line tool used to sign manifests and create deployment manifests for ClickOnce applications. The mage.exe tool is part of the .NET Framework SDK and is also available in Visual Studio Command Prompt.
Tip
When you sign a manifest file using mage, two signature units are consumed. This is because two hash signatures are created for different types of content within the manifest:
The first hash signature is generated for the manifest file itself.
The second hash signature is generated for the files referenced within the manifest.
This double-signing process ensures the integrity of both the manifest file and its referenced files, safeguarding against any tampering attempts.
Follow these instructions to sign directly using Mage and securely reference your private key stored in DigiCert® KeyLocker via our KSP library. Alternatively, integrate Mage with Signing Manager Controller (SMCTL) for simplified signing.
Prerequisites
Download and configure Windows clients installer
Mage commands and parameters
Command options supported by Mage:
Shortcut | Parameter | Description |
|---|---|---|
-s | -sign | Sign a file using a keypair or a certificate. |
-v | -verify | Verify that the manifest is signed correctly. This parameter cannot be combined with other commands. OpmerkingThe verify command is only available in .NET Framework 4.7 and later versions. |
-a | -Algorithm | Specifies "sha256RSA" or "sha1RSA as the algorithm to generate dependency digests with. |
-cf | -CertFile | Provide the path to the certificate you want to sign with. |
-ch | -CertHash | Provide the certificate hash or certificate fingerprint. |
-kc | -KeyContainer | Provide the keypair alias. |
-csp | -CryptoProvider | Specify “DigiCert Signing Manager KSP”. |
-ti | -TimestampUri | Specify http://timestamp.digicert.com |
Opmerking
When specifying a file you want to sign:
Provide only the name of the manifest file if the file is in the same location as where you are running terminal.
Provide the path to the manifest file you want to sign if the file is in a different location than where you are running terminal
Sign
You can use one of the following methods to sign binaries with Mage:
Downloaded certificate and keypair alias
Certificate fingerprint
Sign a file using a certificate and keypair
To sign, run:
mage -sign <file_name> -CertFile <file_name> -KeyContainer <keypair_alias> -CryptoProvider “DigiCert Signing Manager KSP” -a sha256RSA -TimestampUri http://timestamp.digicert.com
Command sample:
mage -sign example.exe.manifest -CertFile C:\Users\Name\Desktop\example.crt -KeyContainer key1 -CryptoProvider "DigiCert Signing Manager KSP" -a sha256RSA -TimestampUri http://timestamp.digicert.com
Sign a file using the certificate fingerprint
Sync certificates (Windows only)
Before attempting to sign with Signtool, Mage, and NuGet using the certificate fingerprint, run this command to sync your certificates to the Windows certificate store.
To sync the default certificate associated with the specified keypair alias:
smctl windows certsync --keypair-alias=<keypair alias>
Opmerking
For more information refer to the Windows command manual.
To sign, run:
mage -sign <file_name> -CertHash <hash_or_cert_fingerprint> -TimestampUri http://timestamp.digicert.com
Command sample:
mage -sign example.exe.manifest -CertHash f39dbe6bcfaa43ca39585aa40ab0a19bf29991cb -TimestampUri http://timestamp.digicert.com
Opmerking
You must be connected to the Internet when signing a manifest that specifies a -TimestampUri value.
Verify signature
To verify the signed file, run:
mage -verify <file_name>
Command sample:
mage -verify example.exe.manifest
Opmerking
The verify command is only available in .NET Framework 4.7 and later versions.