ProGuide Digitally signed add ins and configurations - Esri/arcgis-pro-sdk GitHub Wiki
Language: C#
Subject: Framework
Contributor: ArcGIS Pro SDK Team <[email protected]>
Organization: Esri, http://www.esri.com
Date: 10/06/2024
ArcGIS Pro: 3.4
Visual Studio: 2022
ArcGIS Pro add-in, configurations, and plug-in archive files can be digitally signed to improve security in cases where they are published and shared among users. With digitally signed add-in/configuration/plug-in files, you can confirm the source of the file and verify that the original file contents were not modified after the signature was applied. However, the presence of a digital signature does not signify that the archive is free of program errors.
Once the archive has been digitally signed, modifying or removing any of its contents, regardless of type, breaks the digital signature. Broken file signatures are prominently indicated in the user interface when installing add-in/configuration/plug-in files, and when reviewing add-ins via the Pro Add-In Manager.
Every digital signature is linked to a standard ITU X.509 digital certificate that is used to apply the signature during the signing process. By default, signing with a digital certificate only ensures the installer that the content of the signed archive file didn't change since it was signed, but the installer can't be sure of the real identity of the publisher. To be sure of the publisher’s identity, the add-in author must use a trusted digital certificate issued by a Commercial Certification Authority (such as DigiCert, Thawte, or Geotrust). These types of certificates provide a trustworthy signature. Signed add-in/configuration/plug-in archive files published by Esri fall into this category.
Important Note regarding FIPS 140 Level 2, Common Criteria EAL 4+ June 1, 2023
If you are using a trusted Digital Certificate issued by a Commercial Certification Authority on or after 06/01/23 to sign your add-ins, please note that there are changes to the code signing process. As of June 1, 2023, industry standards changed to require private keys for standard code signing certificates to be stored on Hardware Security Modules (HSMs) (or cloud HSMs) certified as FIPS 140 Level 2, Common Criteria EAL 4+, or equivalent. This change strengthens private key protection for code signing certificates and aligns it with EV (Extended Validation) code signing certificate private key protection.
In order to sign an addin using certificates stored on an HSM refer to: Code signing using certificates stored in a windows certificate store
Unless otherwise indicated, and to avoid unnecessary repetition, the term "add-in" shall be used in the remainder of the document to collectively refer to either add-in, configuration, or plug-in archive files.
- Signed add-ins in the enterprise
- Configure security policies for add-ins using the ArcGIS Pro installation program
- Configure security policies for add-ins using ArcGIS Pro
- Installing add-ins and with digital signatures
- Applying digital signatures to an add-in
- Integrate code signing of addins into your Visual Studio build process
To keep an enterprise network secure from unauthorized use, system administrators have the ability to restrict files (executables, scripts, and so on) that can be deployed throughout the enterprise to include limiting the type of add-ins that are used in ArcGIS Pro. To configure Pro add-in security restrictions, ArcGIS Pro uses a set of Windows registry entries that can only be controlled by an administrator. The following restrictions can be enforced starting with the least secure option:
- Load all add-ins regardless of whether they have digital signatures.
- Only load and use add-ins that are digitally signed by a trusted certificate authority.
- Only load and use add-ins that have been published by Esri.
- Only load add-ins from the administrator folders and all add-ins published by Esri.
- Do not load or execute add-ins in this application.
- Load add-ins only from the administrator folders
Organizations will sometimes need to deploy policies within their network to load only certain type of add-ins. This can be done by executing the ArcGIS Pro installation program with a command line switch. Note: You need admin rights to perform this task.
Refer to this link to run Pro installation program with the appropriate command line switches in order to configure the add-in deployment security policies.
The Add-In Manager dialog box—accessible from ArcGIS Pro, by clicking Project > Add-In Manager—displays a list of all the add-in files currently installed on the user’s machine (configurations and plug-ins are not shown).
Along with other add-in file information, the digital signature status displays in the area indicated in the following screen capture:
The signature status is determined as shown in the following table and applies to all add-ins, configuration, and plug-ins equally:
| Status | Description |
|---|---|
| None | The selected add-in file does not contain any digital signatures. |
| Un-trusted | The digital signature applied to the add-in file is not from a trusted source. |
| Invalid | The digital signature has been invalidated due to manipulation of the add-in file contents, or the certificate has expired. |
| Authenticated | The file is digitally signed with a signature that is valid and from a trusted source. |
On the Options tab of the Add-In Manager dialog box, users can view and change options concerning how add-in file security is handled. The options, ranging from most secure to least secure, are as follows:
- Load only Esri provided add-ins (most secure)
- Require add-ins to be digitally signed by a trusted publisher
- Load all add-ins without restrictions (least secure)
Users without administrator privileges cannot modify these settings in a way that makes the system less secure than the settings an administrator has already established on the machine. Options that are not available to non-administrators are disabled on this tab.
Although add-ins can be installed by copying them to an appropriate well-known folder, doing so without first verifying the source and contents of the file is not recommended. Double-clicking an add-in file link (or configuration or plug-in) from within a web browser, an email client, or Windows Explorer automatically opens the Esri ArcGIS Add-in Installation Utility dialog box.
This dialog box displays pertinent add-in information, such as its name, date, author, version, and description. If the add-in file is digitally signed, signature information also displays in this dialog box. If any of the presented information is unsatisfactory, the installation process can be cancelled by the user and the add-in file will not be installed.
Add-in files can be signed with more than one digital signature, depending on the internal policies of the authoring organization. Within the digital signature area of the Esri ArcGIS Add-in Installation Utility dialog box, the signer, date stamp, and validity of the selected signature display with information on whether the associated certificate is from a trusted source. Detailed information on the selected signature’s certificate can be displayed by clicking the Show Certificate button.
A secure add-in file must have at least one digital signature that is valid and trusted. An invalid signature indicates that the contents of the file have been modified in some way since the signature was applied.
The utility, ArcGISSignAddIn.exe, is provided in the ArcGIS Pro installation folder and can be used to sign add-ins. ArcGISSignAddIn.exe can also be used to view or remove existing digital signatures.
To use this utility to code sign your add-ins, you must have a standard ITU X.509 digital certificate stored using the following two options:
- Windows Certificate Stores. Windows stores certificates locally on the computer in a storage location called the certificate store. A certificate store often has numerous certificates, possibly issued from a number of different certification authorities (CAs).
- Starting on June 1, 2023, a digital certificate issued by a Commercial Certification Authority (such as DigiCert, Thawte, or Geotrust) will be stored on a Hardware Security Module, HSM or cloud HSM, certified as FIPS 140 Level 2, Common Criteria EAL 4+ compliant, or equivalent. Certificates are typically imported into the "Current user certificate store" from an HSM.
- Personal Information Exchange (.pfx) file*.
The following two sections walk through the process of using the ArcGISSignAddIn.exe to code sign your add-in referencing a digital certificate stored in the Windows Certificate Store (to include from an HSM certified as FIPS 140 Level 2) or a Personal Information Exchange (.pfx) file*.
*Once the validity of your certificate stored in your pfx expires, you will need to switch to a certificate stored on an HSM certified as FIPS 140 Level 2, Common Criteria EAL 4+, or equivalent.
ArcGISSignAddIn.exe can be used to sign your add-in with a code signing certificate stored in your Windows Certification Store. This includes certificates you create yourself for personal use and certificates issued by a reputable third-party certificate authority (CA).
Starting on June 1, 2023, trusted digital certificates issued by a Commercial Certification Authority (such as DigiCert, Thawte, or Geotrust) will require private keys for standard code signing certificates to be stored on hardware certified as FIPS 140 Level 2, Common Criteria EAL 4+, or equivalent. Digital certificates issued by commercial certification authorities on HSMs or cloud HSMs can be imported into your computer's certificate store (the imported certificate will not contain the private key, that remains on the HSM). For example, if you have a certificate issued by DigiCert, you can use the DigiCert Certificate Utility to import a certificate from the HSM into your windows computer's certificate store. Imported digital certificates from HSMs are typically visible in the Current User section of your machine's Windows Certificate Sore. At this point, you will be able to run ArcGISSignAddIn.exe to sign your add-in. ArcGISSignAddIn.exe can be run in "UI Mode" or in "Command line Mode" to sign your add-ins using this certificate (or any other valid certificate in the computer's certificate store).
ArcGISSignAddIn.exe: UI Mode
Double click the ArcGISSignAddIn.exe from the bin folder of your ArcGIS Pro installation location. This launches the wizard that will guide you through the process of code signing your add-in.
- Select the .esriAddinX file that you want to sign. Click Next.
- Pick the certificate you want to use from the Windows Certificate store*
- You may be prompted for a password to complete the signing process (if a login credential has not been cached)
- Click Finish.
*If you are using a certificate imported from an HSM, the HSM must be connected to the physical machine on which the signing is being performed to provide the necessary private key to complete the signing process. A cloud based HSM will perform in a similar fashion via a secure connection. To disable any password prompt, please refer to the instructions provided by your Digital Certificate vendor on how to cache user/pwd credentials**.
ArcGISSignAddIn.exe: Command line Mode
Use the ArcGISSignAddIn.exe /n command line parameter. Pass in the "Issued To" value of your certificate as seen in the Windows Certificate Store as the /n command line parameter value. This value can also be a substring of the entire "Issued To" value, however, if multiple certificates share the same substring value chosen, then ArcGISSignAddIn.exe will use the first certificate in the store with a substring that matches the passed-in value. The "Issued To" value of your certificate can be found by viewing your certificate in the Certificate Manager Tool (certmgr.exe). You can reference any certificate stored on your Windows Certificate Store, including a certificate imported from your Hardware Security Module (HSM).
In the example below, the Issued To value of the certificate to be used for signing is "Environmental Systems Research Institute, Inc" in the Windows Certificate Store.
In the code snippet below, the Issued To value passed in to the /n command line is the substring "Environmental" .
"C:\Program Files\ArcGIS\Pro\bin\ArcGISSignAddIn.exe" <Full-Path-To-EsriAddinX-File>\AcmeAddin.esriAddinX /n:"Environmental"
Same as when using ArcGISSignAddin.exe interactively, via its UI, you may be prompted to enter a password when you sign your add-in especially if the certificate was imported from an HSM. Also, same as in the interactive process, the HSM must be connected to the physical machine on which the signing is being performed to provide the necessary private key to complete the signing process and/or a cloud-based HSM would likewise need a secure connection to the machine. To disable the password prompt, please refer to the instructions provided by your Digital Certificate vendor for caching user/pwd credentials**.
If you are using a code signing certificate issued before June 1, 2023, you can continue to use the Personal Information Exchange (.pfx) Files to sign your add-in or configuration file*. You can also use a .pfx file for self-signed certificates.
To use a .pfx file to sign your addin, ArcGISSignAddIn.exe should be run from the command line. You cannot code sign your addin with a .pfx file using the UI mode of ArcGISSignAddin.exe.
Use the /c command line parameter for ArcGISSignAddin.exe. Pass in the full path to your .pfx as the value to this argument. Refer to the code snippet below for an example.
"C:\Program Files\ArcGIS\Pro\bin\ArcGISSignAddIn.exe" <Full-Path-To-EsriAddinX-File>\AcmeAddin.esriAddinX /c:C:\DigitalSignatures\my.pfx /p:*** /s"
Important:
*Please note that the use of the Personal Information Exchange file generated from Digital Certificates issued by Commercial Certification Authorities is now deprecated for code signing purposes. Once the validity of your certificate stored in your pfx expires, you will need to use certificates stored on HSMs certified as FIPS 140 Level 2, Common Criteria EAL 4+, or equivalent. Refer to the Code signing using certificates stored in a windows certificate store section above in order to switch your code signing mechanism to this approach.
** Thales SafeNet Authentication Client
If your vendor does not directly support configuring your HSM for unattended access, you may be able to use the Thales SafeNet Authentication client software (please refer to their "Configure the USB dongle for unattended access" section).
On the SafeNet Authentication client software, go to Client Settings > Advanced tab. Check the “Enabled single logon” checkbox and “Enable single logon for PKCS#11” checkbox. Select “Never” in the “Automatic logoff after token inactivity (in minutes)” drop-down box.
The steps below explain how ArcGISSignAddIn.exe can be integrated into your Visual Studio ArcGIS Pro add-in project to sign your add-in during the post build process (substitute configuration or plug-in for "add-ins"):
Step 1
Open your ArcGIS Pro add-in project in Visual Studio. Right-click the project context menu and choose Edit Project.
Step 2
Add the following lines of code to the bottom of the project file before the closing project tag </Project>.
- The command line used in the snippet references a certificate stored in the Windows Certificate sore. The value passed to the command line is the Digital Certificate's "Issued To" value as seen in the Windows Certificate Store.
- Confirm that the path to ArcGIS Pro's bin folder matches your installation location.
- The signing process may prompt for a password or similar login credential, especially if you are using a certificate imported from an HSM. To disable the password prompt, please refer to the instructions provided by your Digital Certificate vendor for caching user/pwd credentials.
Note: In the code snippet below, note that if you are signing an add-in, the file passed to ArcGISSignAddIn.exe should be <Add-inName>.esriAddinX. If you are signing a configuration, the file passed to ArcGISSignAddIn.exe should be .proConfigX. If you are signing a plug-in, the file passed to ArcGISSignAddin.exe should be .esriPlugin.
...
<Import Project="C:\Program Files\ArcGIS\Pro\bin\Esri.ProApp.SDK.Desktop.targets"
Condition="Exists('C:\Program Files\ArcGIS\Pro\bin\Esri.ProApp.SDK.Desktop.targets') AND
!Exists('Esri.ArcGISPro.Extensions.targets')" />
<Target Name="SignAddIn" AfterTargets="PackageArcGISContents">
<!--Replace substring/certificate name shown in the sample command below with the name/substring for your certificate.
Use the necessary user/password or relevant credential associated with your certificate as needed. Ensure any required
HSM is connected to the machine. Confirm that the path to ArcGIS Pro bin folder matches your installation location.-->
<Exec Command=""C:\Program Files\ArcGIS\Pro\bin\ArcGISSignAddIn.exe" $(TargetDir)$(TargetName).esriAddInX /n:"Acme,Inc." /s" />
</Target>
</Project>
Step 3
Click the Save button to save the project file. Your add-in will now be digitally signed whenever you build your project.
Note: Same as when signing addins with ArcGISSignAddin.exe interactively via UI or command line, if you are using a certificate imported from an HSM, the HSM must be connected to the physical machine and/or the cloud based HSM must have a secure connection. To disable the password prompt, please refer to the instructions provided by your Digital Certificate vendor for caching user/pwd credentials**.
Note: Assuming that you still have a valid .pfx file (that hasn't expired yet), you can still continue to use a .pfx file to sign your addinn via ArcGISSignAddIn.exe and the "/c" command line parameter option as shown below:
...
<Import Project="C:\Program Files\ArcGIS\Pro\bin\Esri.ProApp.SDK.Desktop.targets"
Condition="Exists('C:\Program Files\ArcGIS\Pro\bin\Esri.ProApp.SDK.Desktop.targets') AND
!Exists('Esri.ArcGISPro.Extensions.targets')" />
<Target Name="SignAddIn" AfterTargets="PackageArcGISContents">
<!--Replace the path in the sample command below to your pfx file on disk and use the
password that has been assigned to the pfx file. Confirm that the path to ArcGIS
Pro bin folder matches your installation location.-->
<Exec Command=""C:\Program Files\ArcGIS\Pro\bin\ArcGISSignAddIn.exe"
$(TargetDir)$(TargetName).esriAddInX /c:C:\DigitalSignatures\my.pfx /p:*** /s" />
</Target>
</Project>
