Signing Eclipse Plugins using Self-signed Certificates

Overview

Signing an eclipse plugin is the process of stamping an eclipse plugin with a certificate, by which the plugin could reveal its authenticity to anyone who installs and executes it. Although, by default, eclipse generates unsigned plugins, starting 3.3, eclipse began verifying the integrity of plugins installed via update sites by checking for an attached digital certificate and issuing a warning when an unsigned content is found. Luckily, eclipse doesn’t prevent you from running the unsigned content. However, if you would like to distribute your eclipse plugins or host them via an update site, it is important that your plugins are signed. This would allow the users to reliably identify you as the publisher of the plugin and make sure that the plugin has not been altered since it was uploaded to the update site. This also avoids the user getting a warning message as below.

Certificates

The signing of a plugin is done using a certificate.  A certificate is a digitally signed statement from an entity (person, company etc.), saying that the public key of some other entity (for example, a Java class file) has a particular value. There are two types of certificates:

• Self-signed certificates: A self signed certificate is what you could create on your own to sign your plugins.  When users install plugins signed with self-signed certificate, they are presented with a dialog similar to the one below. The users could verify the certificate and install the plugins if they feel the source is trustworthy.
  
  

• Certificates signed by a trusted third-party: When a certificate issued by a trusted third-party like Verisign is used, the user will not be presented with the warning/trust dialog and the plugins are installed directly. However, such certificates have high cost implications. If your plugins would be made available on Eclipse.org, they will be signed with the foundation certificate (refer http://wiki.eclipse.org/JAR_Signing for more information). However, the process of signing with such certificates is not in the scope of this article.

JAR Signing

Eclipse doesn’t define a mechanism of its own for signing plugins. Since all eclipse plugins are JARs (well almost), eclipse uses the java mechanism of JAR signing to sign plugins. Also, eclipse doesn’t come with any tooling for JAR signing (until Bugzilla request 11485 is closed). Hence you have to rely on command line tools keytool and  jarsigner (keytool.exe and jarsigner.exe on Windows ) that comes with java to get the job done.

Before you begin, make sure to set the environment variable $JAVA_HOME to the Java location. To identify the location of installed Java, open Eclipse "Help > About" dialog and click on "Configuration Details".  Look for the value  "java.home=<some path>" and copy the entire path. On Windows replace "$JAVA_HOME" with "%JAVA_HOME%".

The commands below are for Mac OSX/Linux and uses “sudo” to make updates.  On Windows leave out “sudo“.

1. Creating a self-signed certificate

This step creates a self-signed certificate with public and private key and stores it in a keystore. A keystore is the location where all keys and certificates are stored. This is simply a file where your digital certificates live. We will use the keystore of Java to store the certificates. This is at $JAVA_HOME/lib/security/cacerts where $JAVA_HOME is the location of your Java installation.

sudo keytool -genkey -dname “cn=<common name>, ou=<organizational unit>, o=<organization>, c=<country>” -alias <alias name> -keystore <keystore location> -storepass <keystore password> -validity <validity of certificate in days>

For example,

sudo keytool -genkey -dname “cn=Nirmal Sasidharan, ou=Pf, o=itemis, c=DE” -alias “nirmal” -keystore $JAVA_HOME/lib/security/cacerts -storepass “changeit” -validity 180

The default Java keystore password is “changeit” unless you have changed it. The command would ask for a password to be created for the alias. Enter a password, confirm it and remember it for the next step and for later.

2. Signing the JARs

To sign the plugin and feature JARs with the certificate created by the step above run the following command.

jarsigner –keystore <keystore location> -storepass <keystore password> -verbose

For example,

jarsigner -keystore $JAVA_HOME/lib/security/cacerts -storepass “changeit” -verbose de.itemis.project.updatesite/plugins/de.itemis.plugin_1.0.0.jar nirmal

When asked for password, enter the password for alias created with the step above. This signs the JAR using the certificate identified by alias.

The command signs one JAR at a time. To do batch signing, you could create a simple shell script (or an equivalent batch file on Windows) as below:

#!/bin/bash

##jarbatchsign.sh

export JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Home

for i in $1/*.jar

do

jarsigner -keystore $JAVA_HOME/lib/security/cacerts -storepass

“changeit” -verbose -keypass $3 $i $2

done

Invoke the script as

./jarbatchsign.sh <path to folder containing jars> <alias name> <password for alias>

For example,

./jarbatchsign.sh de.itemis.project.updatesite/plugins/ nirmal aliaspassword

3. Testing the signed plugins

Delete your own certificate from the keystore before you test the update site with the signed plugins (see “Deleting certificate from keystore” below).

Restart eclipse and install the signed plugins from the update site. If all is well, a trust dialog as described before appears.

Other Useful functions

Listing certificates in keystore

sudo keytool -list -keystore <keystore location> -storepass <keystore password>  -v -alias <alias name>

For example,

sudo keytool -list -keystore $JAVA_HOME/lib/security/cacerts -storepass “changeit” -v -alias nirmal

Deleting certificate from keystore

sudo keytool -delete –keystore <keystore location> -storepass <keystore password>

For example,

sudo keytool -delete -keystore $JAVA_HOME/lib/security/cacerts -storepass “changeit” nirmal

Verifying signed jars

jarsigner -keystore <keystore location> -storepass <keystore password>  -verify -verbose -certs

For example,

jarsigner -keystore $JAVA_HOME/lib/security/cacerts -storepass “changeit” -verify -verbose -certs de.itemis.project.updatesite/plugins/de.itemis.plugin_1.0.0.jar

Disabling security check

You could disable the eclipse certificate check all together using the startup option -Declipse.p2.unsignedPolicy=allow. See Bug 235526.