Skip to main content

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.

Suggerimento

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

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.

Nota

The 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

Nota

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>

Nota

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

Nota

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

Nota

The verify command is only available in .NET Framework 4.7 and later versions.