How to troubleshoot app package signature errors

An app deployment failure can be caused by a failure to validate the digital signature of the app package. Learn how to recognize these failures, and what to do about them.

When you deploy a packaged Windows app, Windows always attempts to validate the digital signature on the app package. Failures during signature validation block deployment of the package. But why the package didn't validate might not be obvious. In particular, if you sign your packages with private certificates for local testing, you often must manage the trust for those certificates as well. An incorrect certificate trust configuration can lead to signature validation failures.

What you need to know

Technologies

• Packaging, deployment, and query of Windows apps
• Certificate Trust Verification

Prerequisites

• Windows Event Log to diagnose installation failures.
• Certutil tasks for managing certificates for certificate store manipulation during troubleshooting

Instructions

Step 1: Examine event logs for diagnostic information

Depending on how you attempted to deploy your app, you might not have received a meaningful error code for the deployment failure. In this case, you can usually get the error code directly from the event logs.

To get the error code from the event logs

1. Run eventvwr.msc.

2. Go to Event Viewer (Local) > Applications and Services Logs > Microsoft > Windows.

3. The first log to check is AppxPackagingOM > Microsoft-Windows-AppxPackaging/Operational.

4. Deployment-related errors are recorded in AppXDeployment-Server > Microsoft-Windows-AppXDeploymentServer/Operational.

   For deployment errors, search for the most recent error event 404. This error event provides you with the error code and a description of why the deployment failed. If an error event 465 preceded the 404 event, there was a problem opening the package.

If the 465 error didn't occur, see general Troubleshooting packaging, deployment, and query of Windows apps. Otherwise, refer to this table for common error codes that can show up in the error string for error event 465:

Step 2: Determine the certificate chain used to sign the app package

To figure out the certificates that the local computer must trust, you can examine the certificate chain for the digital signature on the app package.

To determine the certificate chain

1. In File Explorer, right-click on the app package and select Properties.
2. In the Properties dialog, select the Digital Signatures tab, which also displays whether the signature can be validated.
3. In the Signature list, select the signature and then click the Details button.
4. In the Digital Signature Details dialog, click the View Certificate button.
5. In the Certificate dialog, select the Certification Path tab.

The top certificate in the chain is the root certificate and the bottom certificate is the signing certificate. If only a single certificate is in the chain, the signing certificate is also its own root certificate. You can determine the serial number for each certificate that you then use with Certutil:

To determine the serial number for each certificate

1. In the Certification path pane, select the certificate and then click View Certificate.
2. In the Certificate dialog, select the Details tab, which displays the serial number and other useful properties of the certificate.

Step 3: Determine the certificates trusted by the local machine

To be able to deploy an app package, it must not only be trusted in the user’s context but also the local computer context. As a result, the digital signature can appear valid when viewed in the Digital Signatures tab from the previous step but still fail validation during deployment of the app package.

To determine if the certificate chain used to sign the app package is specifically trusted by the local computer

1. Run this command:

   CertUtil.exe -store Root rootCertSerialNumber
   

2. Run this command:

   CertUtil.exe -store TrustedPeople signingCertSerialNumber
   

If you don't specify the certificate serial number, Certutil lists all certificates that are trusted by the local computer for that store.

The package may fail to install due to certificate chaining errors, even if the signing certificate is not self-signed and the root certificate is in the root store of the local computer. In this case, there might be an issue with trust for the intermediate certificate authorities. For more info about this issue, see Working with Certificates.

Remarks

If you determined that the package couldn't be deployed because the signing certificate isn't trusted, don't install the package unless you know where it originated and you trust it.

If you want to manually trust the app for install (for example, to install your own test-signed app package), you can manually add the certificate to the local computer certificate trust from the app package.

To manually add the certificate to the local computer certificate trust

1. In File Explorer, right-click on the app package, and in the pop-up context menu select Properties.
2. In the Properties dialog, select the Digital Signatures tab.
3. In the Signature list, select the signature and then click the Details button.
4. In the Digital Signature Details dialog, click the View Certificate button.
5. In the Certificate dialog, click the Install Certificate… button.
6. In the Certificate Import Wizard, select Local Machine and then click Next. You will need to grant administrator privileges to continue.
7. Select Place all certificates in the following store and browse to the Trusted People store.
8. Click Next, then click Finish to complete the wizard.

After this manual addition, you can see that the certificate is now trusted in the Certificate dialog.

You can remove the certificate after you no longer need it.

To remove the certificate

1. Run Cmd.exe as administrator.

2. In the administrator command prompt, run this command:

   Certutil -store TrustedPeople
   

3. Look for the serial number of the certificate that you installed. This number is the certID.

4. Run this command:

   Certutil -delStore TrustedPeople certID
   

We recommend that you avoid manually adding root certificates to the local machine Trusted Root Certification Authorities Certificate Store. Having several applications that are signed with certificates that chain to the same root certificate, such as line of business applications, can be more efficient than installing individual certificates to the Trusted People store. The Trusted People store contains certificates that are considered trusted by default and so aren't verified by higher authorities or certificate trust lists or chains. For considerations around adding certificates to the Trusted Root Certification Authorities certificate store, see Code-Signing Best Practices.

Security Considerations

By adding a certificate to local machine certificate stores, you affect the certificate trust of all users on the computer. We recommend that you install any code signing certificates that you want for testing app packages to the Trusted People certificate store. Promptly remove those certificates when they are no longer necessary, to prevent them from being used to compromise system trust. If you create your own test certificates for signing app packages, we also recommend that you restrict the privileges that are associated with the test certificate. For info about creating test certificates for signing app packages, see How to create an app package signing certificate.

Related topics

Samples

Create app package sample

Concepts

Troubleshooting packaging, deployment, and query of Windows apps

Certutil tasks for managing certificates