Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between pages "JAR Signing" and "Adaptor Hooks"

(Difference between pages)
 
 
Line 1: Line 1:
 
== Overview ==
 
== Overview ==
We are working towards signing Eclipse buildsThe goal of signing is to allow users to verify that the content they obtain from eclipse.org and subsequently execute does indeed come from that source. Signing in a nutshell works as follows:
+
Since Eclipse 3.0 the Framework Adaptor API has been available in the Equinox OSGi FrameworkA framework adaptor implementation is called upon by the Equinox OSGi Framework to perform a number of tasks.  A framework adaptor may be used to add functionality to the framework.
  
# Eclipse builds produce content in various forms (zips, update JARS)
+
A single framework adaptor is specified when the framework is launched.  By default in Eclipse 3.0 this is set to the EclipseAdaptor. In order to add new functionality in an adaptor in Eclipse 3.0 and 3.1 it is required that the adaptor implementation either re-implement the complete framework adaptor API or extend one of the existing framework adaptor implementations.  This makes it impossible for two parties to add new functionality to the framework in separate adaptors at the same time because the Equinox OSGi Framework can only be configured to use one adaptor.
# The Eclipse Foundation produces a signature of the build content using its private key (signature = private key + content)
+
# User downloads build content and signatures from eclipse.org or from mirrors
+
# The Eclipse Foundation makes available a [http://en.wikipedia.org/wiki/Public_key_infrastructure public key] for verifying signatures
+
# User consults some trusted authority to verify that the public key does indeed belong to the Eclipse Foundation
+
# Verification is performed on the user's machine (signature + public key = hash of content)
+
  
== Signing ==
+
In Eclipse 3.2 a new hookable adaptor has been included that is used by default as the framework adaptor.  The framework adaptor API has remained unchanged for the most part in Eclipse 3.2.  What has changed is the actual implementation of the adaptor API.  A new implementation of the adaptor API is now included which provides hooks that others can implement to provide functionality to the adaptor implementation.
  
=== What gets signed? ===
+
== Hookable Adaptor ==
 +
The hookable adaptor is implemented in the package org.eclipse.osgi.baseadaptor.  This adaptor implementation provides all of the default behavior required of a FrameworkAdaptor to provide an OSGi R4 compliant Framework.  It also provides many hooks that allow others to insert additional functionality into the framework through what are called framework extension bundles.  See the OSGi Core Specification chapter 3.15 "Extension Bundles" for more information.
  
By default, every JAR pushed to an update site will be signed. This includes JARs nested at arbitrary depth within other JARs. Some JARs may be excluded if there are technical or legal reasons why they cannot be signedIn standalone zip distribtions, all JARed plugins will be signed, and un-JARed plugins will not be signed.
+
Framework extension bundles are fragments of the system bundle (org.eclipse.osgi).  As a fragment they can provide extra classes which the framework can useA framework extension bundle can define a set of hook implementations that are configured with the hookable adaptor (using a hookconfigurators.properties file). 
  
=== How is signing done? ===
+
=== The Base Adaptor ===
 +
The class org.eclipse.osgi.baseadaptor.BaseAdaptor implements the interface org.eclipse.osgi.framework.adaptor.FrameworkAdaptor.  This class is used by default as the adaptor of the framework.  You should avoid extending this class, instead you should use hook implementations to add functionality to the BaseAdaptor.
  
Signing is performed using the JDK's [http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/jarsigner.html jarsigner]. This tool signs JARs by producing a separate signature for every file in the JARThe signatures are put in the MANIFEST.MF file and in a separate signature file in the META-INF directory.  For optimization purposes, the signature of the MANIFEST.MF with all embedded signatures is also computed and placed in the signature file.
+
In some cases it may be impossible to do what you want with the current set of adaptor hooks. In this case you may be forced to extend the BaseAdaptor class to provide your own adaptor implementationIf you find yourself in this situation then you should open a bug against Framework Equinox requesting a new hook method or interface.
  
=== Where is signing done? ===
+
=== The Hook Registry ===
 +
The hook registry is implemented in the class org.eclipse.osgi.baseadaptor.HookRegistry. The hook registry is used to store all the hooks configured in the framework.  When the hook registry is initialized it will discover all the hook configurators installed in the framework and will call on them to add hooks to the registry.  The BaseAdaptor uses the hook registry at runtime to lookup and use the different hooks configured with the registry.
  
A critical part of the security behind signing is that the private keys used to produce the signatures are held in a secure location and never transmitted or accessible via a network. To accomplish this, the signing must be done on a secure machine that has access to the private key. The Eclipse Foundation has set up a machine with a signing scriptThe build will upload content to be signed to this machine, and a script is run to perform the signing.  Access to this machine will be given to trusted parties that want to perform signing.
+
==== Hook Configurators ====
 +
Hook configurators must implement the org.eclipse.osgi.baseadaptor.HookConfigurator interfaceHook configurators can add one or more hook implementations to the hook registry using the various add methods on the registry.
  
=== When is signing done? ===
+
==== Discovering Hook Configurators ====
 +
In order for a hook configurator to be discovered by the hook registry its implementation must be accessable by the framework's classloader.  This implies that hook configurators must be built into the framework itself (org.eclipse.osgi) or be supplied by a framework extension bundle.  Again a framework extension bundle is really just a fragment to Framework (i.e org.eclipse.osgi or the System Bundle).
  
Signing will be done as part of the build process.  Because this adds a significant amount of time to the build process, the releng team is investigating streamlining the build process. The process of producing a signed build is:
+
A hook configurator also must be declared in one of the following ways to indicate to the hook registry which classes should be loaded as hook configurators.
  
# Checkout source from eclipse.org CVS repositories to build machine
+
===== hookconfigurators.properties files =====
# Run build and produce a single ZIP of all plugins in update site form (all plugins in JARs)
+
A hookconfigurators.properties file can be used to declare a list of hook configator classes.  The key hook.configurators is used in a hook configurators properties file to specify a comma separated list of fully qualified hook configurator classes. For example, the Equinox Framework (org.eclipse.osgi) is shipped with a default set of hook configurators specified a hookconfigurators.properties file included in the org.eclipse.osgi.jar:
# Send build output to eclipse.org for signing
+
# Send signed build to update site
+
# Copy zip of signed JARs back to the build machine, and package standalone zips
+
# Copy standalone zips to test machines for automated testing
+
  
Currently the Eclipse project build machine is located remote from the Eclipse Foundation servers. This means the Eclipse source has to be transferred across the Internet, and the build output needs to be transferred back to Foundation machines for signing. These two major network bottlenecks could be removed by also using Eclipse Foundation machines for building.
+
<code>
 +
  hook.configurators=
 +
    org.eclipse.osgi.internal.baseadaptor.BaseHookConfigurator,
 +
    org.eclipse.osgi.internal.baseadaptor.DevClassLoadingHook,
 +
    org.eclipse.core.runtime.internal.adaptor.EclipseStorageHook,
 +
    org.eclipse.core.runtime.internal.adaptor.EclipseLogHook,
 +
    org.eclipse.core.runtime.internal.adaptor.EclipseErrorHandler,
 +
    org.eclipse.core.runtime.internal.adaptor.EclipseAdaptorHook,
 +
    org.eclipse.core.runtime.internal.adaptor.EclipseClassLoadingHook,
 +
    org.eclipse.core.runtime.internal.adaptor.EclipseLazyStarter,
 +
    org.eclipse.core.runtime.internal.stats.StatsManager,
 +
    org.eclipse.osgi.internal.verifier.SignedBundleHook
 +
</code>
  
=== What public key (certificate) do we use? ===
+
Quite a few hook configurators are automatically enabled by default withing the Equinox Framework.  The only hook configurator required for a fully functional OSGi R4 Framework is the org.eclipse.osgi.internal.baseadaptor.BaseHookConfigurator.  All other configurators declared above add extra functionality needed by eclipse and can be disabled.
  
The Eclipse Foundation [https://bugs.eclipse.org/bugs/show_bug.cgi?id=130943 has purchased] a signing certificate from Verisign.  Content made available on Eclipse.org will be signed with the foundation certificate.  Note this doesn't preclude other parties from later signing the JARs with their own certificates.
+
Extension bundles may provide their own hookconfigurators.properties file to specify additional hook configurators. The hook registry will discover all hookconfigurator.properties files on its classpath and will merge all declared configurator classes into one list.
  
=== Where are the signatures stored? ===
+
===== osgi.hook.configurators property =====
 +
The osgi.hook.configurators configuration property is used to specify the list of hook configurators.  If this property is set then the list of configurators specified will be the only configurators used.  If this property is set then the hookconfigurators.properties files will not be processed for additional configurators.  This property can be used in a config.ini to lock down the set of configurators to a specific set.
  
The signatures are stored in the JAR file, both in the MANIFEST.MF, and in a separate signature file (currently Eclipse_.sf).
+
===== osgi.hook.configurators.include property =====
 +
The osgi.hook.configurators.include configuration property is used to add additional hook configurators.  This is helpful for configuring optional hook configurators.  Hooks that should be enabled by default should be included in a hookconfigurators.properties file. This property is ignored if the osgi.hook.configurators is set.
  
== Verification ==
+
===== osgi.hook.configurators.exclude property =====
 +
The osgi.hook.configurators.include configuration property is used to exclude any hook configurators.  This is helpful for disabling hook configurators that are specified in hook configurator properties files.  This property is ignored if the osgi.hook.configurators is set.
  
=== When does verification happen? ===
+
== Hook interfaces ==
  
Verification can happen any time.  The common times to perform verification are:
+
=== Adaptor Hook ===
* During update.  Minimally, verification happens at the time the client obtains the signed content.  The Eclipse update mechanism will perform verification of any update JARs that are signed, and will prompt the user for confirmation if the certificate used for signing is not trusted. 
+
* At load-time.  It is sometimes desirable to perform verification at load time when classes are loaded from a JAR.  The default Java class loader performs this verification automatically for any signed JAR on the classpath.  The Eclipse class loader can also be configured to perform load-time verification, but it is optional.
+
* Manual user verification.  The Eclipse about dialog will be augmented to show what plugins are signed.  From this dialog the user should be able to manually perform verification of signed content if desired.
+
  
== Miscellaneous links ==
+
=== Bundle File Factory Hook ===
  
=== Eclipse Bugzilla reports ===
+
=== Bundle File Wrapper Factory Hook ===
  
{|
+
=== Bundle Watcher Hook ===
|-
+
! Done || Description
+
|-
+
|
+
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=43889 OSGi Bundle signing bug report]
+
|-
+
|
+
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=78208 Runtime signing support]
+
|-
+
|
+
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=94461 Signing indicator in About dialog]
+
|-
+
| [[Image:check.gif]]
+
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=130943 Purchasing signing certificates]
+
|-
+
|
+
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=132046 Signing script to signal completion]
+
|-
+
|
+
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=132048 Starting signing immediately after signing script is called]
+
|-
+
| [[Image:check.gif]]
+
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=134264 Bug for installing Java 1.5 on signing server]
+
|-
+
|
+
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=135044 Bug for installing Improved signing/packing application on signing server]
+
|-
+
|
+
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=130383 Bug for using OSGi verification during update]
+
|}
+
  
=== Other signing links ===
+
=== Class Loading Hook ===
  
* [https://www.verisign.com/products-services/security-services/code-signing/digital-ids-code-signing/index.html Verisign code signing products]
+
=== Class Loading Stats Hook ===
* [http://java.sun.com/j2se/1.5.0/docs/guide/security/time-of-signing.html Sun docs on timestamps in signatures]
+
 
* [http://opentsa.org/ Web site of open source time stamp protocol implementation]
+
=== Storage Hook ===
* [http://www.digistamp.com/ Time stamping service]
+
 
 +
== Bundle Files ==
 +
 
 +
== Class Loaders ==
 +
 
 +
== Examples ==

Revision as of 11:48, 22 April 2006

Overview

Since Eclipse 3.0 the Framework Adaptor API has been available in the Equinox OSGi Framework. A framework adaptor implementation is called upon by the Equinox OSGi Framework to perform a number of tasks. A framework adaptor may be used to add functionality to the framework.

A single framework adaptor is specified when the framework is launched. By default in Eclipse 3.0 this is set to the EclipseAdaptor. In order to add new functionality in an adaptor in Eclipse 3.0 and 3.1 it is required that the adaptor implementation either re-implement the complete framework adaptor API or extend one of the existing framework adaptor implementations. This makes it impossible for two parties to add new functionality to the framework in separate adaptors at the same time because the Equinox OSGi Framework can only be configured to use one adaptor.

In Eclipse 3.2 a new hookable adaptor has been included that is used by default as the framework adaptor. The framework adaptor API has remained unchanged for the most part in Eclipse 3.2. What has changed is the actual implementation of the adaptor API. A new implementation of the adaptor API is now included which provides hooks that others can implement to provide functionality to the adaptor implementation.

Hookable Adaptor

The hookable adaptor is implemented in the package org.eclipse.osgi.baseadaptor. This adaptor implementation provides all of the default behavior required of a FrameworkAdaptor to provide an OSGi R4 compliant Framework. It also provides many hooks that allow others to insert additional functionality into the framework through what are called framework extension bundles. See the OSGi Core Specification chapter 3.15 "Extension Bundles" for more information.

Framework extension bundles are fragments of the system bundle (org.eclipse.osgi). As a fragment they can provide extra classes which the framework can use. A framework extension bundle can define a set of hook implementations that are configured with the hookable adaptor (using a hookconfigurators.properties file).

The Base Adaptor

The class org.eclipse.osgi.baseadaptor.BaseAdaptor implements the interface org.eclipse.osgi.framework.adaptor.FrameworkAdaptor. This class is used by default as the adaptor of the framework. You should avoid extending this class, instead you should use hook implementations to add functionality to the BaseAdaptor.

In some cases it may be impossible to do what you want with the current set of adaptor hooks. In this case you may be forced to extend the BaseAdaptor class to provide your own adaptor implementation. If you find yourself in this situation then you should open a bug against Framework Equinox requesting a new hook method or interface.

The Hook Registry

The hook registry is implemented in the class org.eclipse.osgi.baseadaptor.HookRegistry. The hook registry is used to store all the hooks configured in the framework. When the hook registry is initialized it will discover all the hook configurators installed in the framework and will call on them to add hooks to the registry. The BaseAdaptor uses the hook registry at runtime to lookup and use the different hooks configured with the registry.

Hook Configurators

Hook configurators must implement the org.eclipse.osgi.baseadaptor.HookConfigurator interface. Hook configurators can add one or more hook implementations to the hook registry using the various add methods on the registry.

Discovering Hook Configurators

In order for a hook configurator to be discovered by the hook registry its implementation must be accessable by the framework's classloader. This implies that hook configurators must be built into the framework itself (org.eclipse.osgi) or be supplied by a framework extension bundle. Again a framework extension bundle is really just a fragment to Framework (i.e org.eclipse.osgi or the System Bundle).

A hook configurator also must be declared in one of the following ways to indicate to the hook registry which classes should be loaded as hook configurators.

hookconfigurators.properties files

A hookconfigurators.properties file can be used to declare a list of hook configator classes. The key hook.configurators is used in a hook configurators properties file to specify a comma separated list of fully qualified hook configurator classes. For example, the Equinox Framework (org.eclipse.osgi) is shipped with a default set of hook configurators specified a hookconfigurators.properties file included in the org.eclipse.osgi.jar:

hook.configurators= 
   org.eclipse.osgi.internal.baseadaptor.BaseHookConfigurator,
   org.eclipse.osgi.internal.baseadaptor.DevClassLoadingHook,
   org.eclipse.core.runtime.internal.adaptor.EclipseStorageHook,
   org.eclipse.core.runtime.internal.adaptor.EclipseLogHook,
   org.eclipse.core.runtime.internal.adaptor.EclipseErrorHandler,
   org.eclipse.core.runtime.internal.adaptor.EclipseAdaptorHook,
   org.eclipse.core.runtime.internal.adaptor.EclipseClassLoadingHook,
   org.eclipse.core.runtime.internal.adaptor.EclipseLazyStarter,
   org.eclipse.core.runtime.internal.stats.StatsManager,
   org.eclipse.osgi.internal.verifier.SignedBundleHook

Quite a few hook configurators are automatically enabled by default withing the Equinox Framework. The only hook configurator required for a fully functional OSGi R4 Framework is the org.eclipse.osgi.internal.baseadaptor.BaseHookConfigurator. All other configurators declared above add extra functionality needed by eclipse and can be disabled.

Extension bundles may provide their own hookconfigurators.properties file to specify additional hook configurators. The hook registry will discover all hookconfigurator.properties files on its classpath and will merge all declared configurator classes into one list.

osgi.hook.configurators property

The osgi.hook.configurators configuration property is used to specify the list of hook configurators. If this property is set then the list of configurators specified will be the only configurators used. If this property is set then the hookconfigurators.properties files will not be processed for additional configurators. This property can be used in a config.ini to lock down the set of configurators to a specific set.

osgi.hook.configurators.include property

The osgi.hook.configurators.include configuration property is used to add additional hook configurators. This is helpful for configuring optional hook configurators. Hooks that should be enabled by default should be included in a hookconfigurators.properties file. This property is ignored if the osgi.hook.configurators is set.

osgi.hook.configurators.exclude property

The osgi.hook.configurators.include configuration property is used to exclude any hook configurators. This is helpful for disabling hook configurators that are specified in hook configurator properties files. This property is ignored if the osgi.hook.configurators is set.

Hook interfaces

Adaptor Hook

Bundle File Factory Hook

Bundle File Wrapper Factory Hook

Bundle Watcher Hook

Class Loading Hook

Class Loading Stats Hook

Storage Hook

Bundle Files

Class Loaders

Examples

Back to the top