This article describes the Eclipse plug-in signature, its application, and the test strategy used by the IBM Lotus Expeditor client provisioning system, which is leveraged to control code access to local or remote Eclipse update sites.
Signature is an indispensable mechanism for Eclipse's security functions. While a plug-in is downloading, the Eclipse user has the opportunity to verify a JAR file's signature, which is posted on the update site. This allows the user to get reliable information about the code he is about to install. This function allows him to identify who published the code and verify that the software has not been altered since the time it was uploaded to the update site. IBM Lotus Expeditor/Lotus Notes® applies this security mechanism using its Update Manager component to deliver a signature check-up for users.
To get the most out of this article, you need an Eclipse development environment and the sample code. If you don't have Eclipse already, download the following:
- Java 2 Standard Edition
- The Java® 2 Standard Edition V5 or greater is available from Sun Microsystems.
- Find Eclipse platform at the Eclipse Foundation. To try another test platform, download IBM Lotus Expeditor V6.1.x, but this is optional
Eclipse plug-ins fall into one of five digital signature categories:
- Unsigned plug-in
- By default, all plug-ins generated by Eclipse are unsigned.
- Signed plug-in
- If an unsigned plug-in is signed, then it can be called a signed plug-in.
- Trusted plug-in
- If a signed plug-in is signed with a trusted signature, this plug-in will be trusted by the Eclipse runtime. Thus, it is a trusted plug-in.
- Untrusted plug-in
- This plug-in is signed with an untrusted signature.
- Expired plug-in
- All signed plug-ins have a period of validity. An expired plug-in is one encapsulated in a JAR file, which is signed, but the certificate used to sign the JAR file has expired.
Figure 1. Plug-in categories
Implementation and test scenario
Find out how to generate a plug-in with unsigned, untrusted, or expired signatures by Eclipse, Keytool, and Jarsigner, then verify them in Eclipse runtime and IBM Lotus Expeditor runtime. Let's begin with an unsigned plug-in.
By default, a plug-in generated by an IDE (such as Eclipse) is an unsigned plug-in. For example, we create an unsigned plug-in using the following steps:
- Click File > New > Projectâ¦> Plug-in Development > Plug-in project, and click Next.
HelloWorldin the project name field, accept other defaults and click Next.
- Click the Next button in the subsequent wizard page for Plug-in Content.
HelloWorldand click the Finish button in the Template wizard page.
- Click File > New > Projectâ¦> Plug-in Development > Feature project, then click Next.
HelloWorld.featurein the Project name field, accept other defaults and click Next.
- Select the
HelloWorldplug-in you just created in the Referenced Plug-ins and Fragments wizard page and click Finish.
- Click File > New > Projectâ¦> Plug-in Development > Update Site project and click Next.
HelloWorld.updatesitein the Project name field, accept other defaults, and click Finish.
- Click the Add Featureâ¦ button, select
HelloWorld.feature, and click OK.
- Click Build to generate the update site file in your local file system.
- Verify the expected update site has been created in your workspace.
Using the above 12 steps, we created a HelloWorld sample plug-in, a HelloWorld feature, and a HelloWorld update site to encapsulate them.
Figure 2. Plug-in categories
Let's verify its identity using the Eclipse Update Manager with the following steps:
- Click Help > Software Update > Find and Install â¦.
- Select Search for new feature to install and click Next.
- Click the New Local Site â¦ button, navigate to the HelloWorld update site and click OK.
- Click Finish.
We will get an "unsigned feature" notification to warn us that the feature is not equipped with a signature and that its provider can not be verified.
Figure 3. Verifying an unsigned plug-in in Eclipse
IBM Lotus Expeditor, a powerful Eclipse-based platform, displays a similar warning message if we perform the same installation steps with the same plug-in. The user can choose to deny or accept such a plug-in by clicking the radio buttons, as shown below.
Figure 4. Test scenario of verifying a unsigned plug-in in IBM Lotus Expeditor
The aim of code integrity is to determine that a plug-in has not been modified before it is installed. To meet this goal, we will use two utilities: Keytool and Jarsigner.
Keytool is command-line tool used to manage keys and certificates. A certificate is a digitally signed statement from an entity (person, company, computer, program, etc.), saying that the public key (and some other information) of some other entity has a particular value. Keytool currently handles X.509 certificates. Elements in a X.509 certificates include Version, Validity Period, Subject Name (Common Name, Organizational Unit, Organization and Country), etc. The keys and certificates are stored in a so-called keystore, which is actually a file. It protects private keys with a password.
Jarsigner is another utility used to sign JAR files and verify such signatures. To verify the existing digital signature in a JAR file, Jarsigner will retrieve the certificate that comes with the subjected JAR file, then check whether the public key of that certificate is trustable based on the specified keystore. We will use the signing and verification functions of Jarsigner in this article.
First, we will use the Keytool to create a keystore, in which there will be a pair of keys (the public key and the private key). Issue the following command.
Listing 1. Create a keystore
keytool -genkey -dname "cn=Li Xing Xing, ou=CDL, o=IBM, c=CN" -alias business -keypass key123 -keystore C:\keystore\mykeystore -storepass store123 -validity 180
This command does the following:
- It creates a keystore file named mykeystore in C:\keystore directory and assigns the password store123 to the keystore. The keystore type is jks by default.
- It generates a public/private key pair for the entity having the Distinguished Name values of "Li Xing Xing" for the common name, "CDL" for the organizational unit, "IBM" for the organization, and "CN" for the country. The password key123 is assigned to the private key. There will be one entry contained in keystore, which is named "business."
- It uses the default DSA key-generation algorithm and creates two keys of 1024 bits, the default length.
- It uses a default signature algorithm, SHA1 with DSA, to create a self-signed certificate valid for 180 days.
Accordingly, a file named mykeystore will be created in the target folder.
Figure 5. Mykeystore generated
After we have created a self-signed certificate, we will sign the feature.jar and plugin.jar file with it by issuing the following Jarsigner commands, as shown in listings 2 and 3. Here, we leveraged the signing function of Jarsigner by the
jarsigner [options] jar-file alias command format. In the options fields, we provided keystore file location, keystore password, and private key password.
Listing 2. Sign feature JAR file
jarsigner -keystore C:\keystore\mykeystore -storepass store123 -keypass key123 C:\workspace\HelloWorld.update\features\HelloWorld.feature_1.0.0.jar business
Listing 3. Sign plug-in JAR file
jarsigner -keystore C:\keystore\mykeystore -storepass store123 -keypass key123 C:\workspace\HelloWorld.update\plugins\HelloWorld.feature_1.0.0.jar business
Because the validity is 180 days, you will get the response that the signer certificate will expire after six months, as shown by the last line echoed in figures 6 and 7.
Figure 6. Response to signing a feature JAR file
Figure 7. Response to signing a plug-in JAR file
You might be curious what happened to your feature JAR and plug-in JAR files by running the above two commands. Open META-INF folders in both HelloWorld.feature_1.0.0.jar and HelloWorld_1.0.0.jar, and you will find two files added — namely BUSINESS.SF and BUSINESS.DSA — as shown in Figure 8.
Figure 8. BUSINESS.DSA and BUSINESS.SF in META-INF
As a matter of fact, the difference between an unsigned and a signed plug-in is these two files: .SF and .DSA. Let's explore the BUSINESS.SF file first. This is the signature file for the JAR file, in which information is represented as name-value pairs followed the RFC822 standard. Each signer is represented by a signature file with extension .SF. The main section entry, x-Digest-Manifest-Main-Attributes (where x is a digest algorithm, such as SHA1), contains the digest value for the main attributes of the manifest. Such embedded data is represented as Base64, a popular technology to encode and transport the 8-bit bytes using the Internet. Table 1 lists the sample content of BUSINESS.SF files in your feature and plug-in JAR files. The version, signature algorithm, JVM, and digest information are provided there.
Table 1. BUSINESS.SF files in feature JAR and plug-in JAR
|Feature JAR||Plug-in JAR|
Created-By: 1.5.0 (IBM Corporation)
Created-By: 1.5.0 (IBM Corporation)
By contrast, BUSINESS.DSA file, a binary file of signature, might be more difficult to understand. This signature block file stores the digital signature of the corresponding signature file. As you found, the BUSINESS.DSA file and BUSINESS.SF files share the same base file name, with different extension names. Actually, .RSA and .PGP are other options for the extension name of a signature binary file, depending on different algorithms to be used. Figure 9 demonstrates the content encapsulated in a BUSINESS.DSA file, with some readable information translated by the word processor (we used UltraEdit). That means you can only crack a few literature strings, such as "CN," "IBM," "Lotus Expeditor," and "Li Xing Xing." But you can't reveal the whole picture. That's the magic of signature.
Figure 9. BUSINESS.DSA content
We can validate the signature in a signed plug-in JAR file with a command of
jarsigner -verify before we install it into any product. Issue the following command against your signed plug-in JAR file and get your response, as shown in Figure 10. The
âcerts options will display verbose output and the certificate during the verification.
Listing 4. Verify signed plug-in JAR file with Jarsigner command
jarsigner -keystore C:\keystore\mykeystore âstorepass store123 âverify âverbose âcerts C:\workspace\HelloWorld.update\plugins\HelloWorld_1.0.0.jar
Figure 10. Verify plug-in signature by Jarsigner command
The basic information and expiration information of the signature in HelloWorld_1.0.0.jar will be listed and verified when you use Jarsigner's command to verify the subject.
Now try to install the update site embedded with the signed plug-in. You will be notified that "You are about to install a signed feature" with details of the self-signed certificate presented, as shown in Figure 11.
Figure 11. Test scenario of verifying a signed plug-in in Eclipse
Users tend to trust a signed plug-in more than an unsigned plug-in. When such a signed plug-in is being installed into IBM Lotus Expeditor, a similar warning dialog will pop up to remind the user that there are three responses to choose.
Figure 12. Test scenario of verifying a signed plug-in in IBM Lotus Expeditor
The certificate details — Version, Issued by, Issued to, and Signature Algorithm — will be listed if you click View Certificate Detailsâ¦, as shown in Figure 13. We think IBM Lotus Expeditor provided more information to advocate the trust of the plug-in from the user.
Figure 13. Certificate details of the signature in a signed plug-in
Signed but expired feature
With the information in Figure 11, we know the self-signed certificate's validity is 02-13-2009. If we change the time in our operating system into 02-14-2009, as shown in Figure 14, the signed plug-in will become an expired plug-in because of its "EXPIRED CERTIFICATE."
Figure 14. Change your system time in your operating system
Now we can use a Jarsigner command to verify the signature to find out the signed, but, unfortunately, expired result. Please pay attention to the last sentence in Figure 15.
Figure 15. Verify a expired signature in a plug-in by a Jarsigner command
When you try to install this plug-in into Eclipse runtime using update manager, Eclipse will tell you that the feature has been signed, but that it's out of date, as shown in Figure 16. That's because Eclipse detected that the current date in the operating system (02-14-2009) has beyond the validity scope (02-13-2009). Consequently, "EXPIRED CERTIFICATE" is highlighted, which alerts the user to possible risks. However, the user may still accept and install the plug-in by clicking the Install or Install All button, even though the plug-in's validity has expired. That's the user's choice.
Figure 16. Test scenario of verifying an expired plug-in in Eclipse
Figure 17 demonstrates the similar notification of an expired certificate for a plug-in, which will be thrown out when you install such a plug-in into IBM Lotus Expeditor.
Figure 17. Test scenario of verifying expired plug-in in IBM Lotus Expeditor
The Eclipse IDE and IBM Lotus Expeditor effectively apply signature security mechanisms in their provisioning subsystems by enhancing the code security level when it's deployed to end users' desktops. This article explored the essentials of the plug-in signature mechanism, including its categories, creation, and verification strategies. The sample plug-ins (unsigned, signed, and expired) introduced by this article could be moved to another Eclipsed-based product that requires security verification.
- Lesson: Signing Code and Granting It Permissions demonstrates how to use utilities to sign your JAR files.
- Lesson: Generating and Verifying Signatures introduces the basic concepts of digital signature by API programming.
- Keytool — Key and Certificate Management Tool gives a detailed description on the usage of keytool
- Jarsigner — JAR Signing and Verification Tool shows how to leverage the Jarsigner utility to sign and verify signatures.
- The Eclipse Foundation article "PDE Does Plug-ins" offers a description of how to develop applications in Eclipse's PDE.
- Gain a brief understanding of IBM Lotus Expeditor V6.1.x, an Eclipse-based product, at the IBM Lotus Expeditor V6.1.x Infocenter.
- Don't miss "Brand your Eclipse RCP applications" and "Understanding Eclipse's new bundle-management mechanism."
- Check out the "Recommended Eclipse reading list."
- Browse all the Eclipse content on developerWorks.
- New to Eclipse? Read the developerWorks article "Get started with Eclipse Platform" to learn its origin and architecture, and how to extend Eclipse with plug-ins.
- Expand your Eclipse skills by checking out IBM developerWorks' Eclipse project resources.
- To listen to interesting interviews and discussions for software developers, check out check out developerWorks podcasts.
- Stay current with developerWorks' Technical events and webcasts.
- Watch and learn about IBM and open source technologies and product functions with the no-cost developerWorks On demand demos.
- Check out upcoming conferences, trade shows, webcasts, and other Events around the world that are of interest to IBM open source developers.
- Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products.
Get products and technologies
- Learn and download IBM Lotus Expeditor V6.1.x to finish the test scenarios in the article from IBM Lotus Expeditor: Desktop integration framework to accelerate customer care.
- Check out the latest Eclipse technology downloads at IBM alphaWorks.
- Download Eclipse Platform and other projects from the Eclipse Foundation.
- The Java 2 Standard Edition V5 or greater is available from Sun Microsystems.
- Download IBM product evaluation versions, and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
- Innovate your next open source development project with IBM trial software, available for download or on DVD.
- The Eclipse Platform newsgroups should be your first stop to discuss questions regarding Eclipse. (Selecting this will launch your default Usenet news reader application and open eclipse.platform.)
- The Eclipse newsgroups has many resources for people interested in using and extending Eclipse.
- Participate in developerWorks blogs and get involved in the developerWorks community.