Signing custom or third-party features and plug-ins for install and update

Eclipse plug-ins can be created and used to extend Notes® client functionality. Features and plug-ins are provisioned with the client software.

About this task

To simplify installation or deployment, sign your features and plug-ins.

CAUTION: The Notes® installer requires that all features and plug-ins in the install kit be signed and timestamped.

Sign new features and plug-ins in preparation for install and update using a code signing certificate obtained from a certification authority. When signed and properly resident in the install kit, the features can be installed if the code signing certificate is included in the kit keystore. If the code signing certificate is not a trusted file, you can modify the install signature verification policy to allow for installing signed but untrusted content.

Note: Features and plug-ins being installed as part of Notes® install or upgrade must be signed. Features and plug-ins being deployed to an existing Notes® install, for example using a widget, should be signed by a trusted certifier.

Administrative trust defaults can be pushed to clients using Domino® policy settings in the Administrative trust defaults section on the security policy document's Keys and Certificates tab. Use this policy option to specify your specific administrative trust defaults for use during either Notes® install or upgrade or client plug-in deployment to an existing Notes® installation.

Note: Time stamping certificates can be added to signed plug-ins to ensure the long-term validity of plug-in signatures. You can use security policy settings to ignore the expiration dates of time stamping certificates that are valid at the time of plug-in signing. With this approach, users are not hindered during use or installation of signed plug-ins when time stamping certificates expire. See the related topics for information on creating a security policy settings document.

Signing your custom or third-party features and plug-ins accomplishes the following:

  • Allows you to dictate the policy settings to determine what kind of signed/unsigned content can be downloaded from an allowed Eclipse update site
  • Enables you to install the feature as part of Notes® installation or upgrade
  • Avoids users being prompted to trust deployed features or plug-ins
  • Allows you to modify the default policy used by the signature verification code at install and update time by using a Domino® administrative policy or by setting preferences in the PLUGIN_CUSTOMIZATION.INI file in the install kit
  • Based on administrator settings, allows users to make trust decisions based on the certificate details

When you install new custom or third-party features and plug-ins for Notes® installation, you can add your own certificates to a keystore so that the signed features are trusted during install and update from the install kit. You can sign features and plug-ins either using the JarSigner tool included in the Java™ Development Kit (JDK) or a third-party tool, such as the Plugin Development Environment (PDE) in Eclipse. Certificates can be obtained from many of the well known certificate authorities (CA).

Features are checked for trust during install and update provisioning. If Notes® is already installed, features are checked during runtime provisioning.

  • Install and update provisioning

    The Notes® installer installs and initially provisions new or updated features from the install kit's update site UPDATESITE.ZIP. During this initial provisioning, trust is based on the Java™ keystore file in the Notes® install kit's deploy directory. There is no user interface for trust prompting during Notes® install; all install features must be signed by a trusted signer.

    Note: When you run a Notes® client kit installation, the Java™ key store is copied to notes\framework\rcp\deploy\.keystore.JCEKS.IBM_J9_VM.install This keystore contains the IBM® code signing certificate used during install.

    The items in the Notes® install kit's update site zip file (updateSite.zip) must be signed, including custom or third-party feature and plug-in JAR files. The provisioning process seeks to verify the signature. This allows administrators and users to control and validate the signed code being downloaded to the client.

  • Runtime provisioning

    If Notes® is running, provisioning can be initiated manually by the user or programmatically based on a scheduled criteria or other provisioning mechanism, such as that used by the widget provisioning process. During runtime provisioning, a combination of the Notes® keystore and the user's personal name and address book (NAB) determines trust for the features and plug-ins being deployed.

    Note: When you run a Notes® client kit installation, the Java™ key store is copied to notes\framework\rcp\deploy\.keystore.JCEKS.IBM_J9_VM.install (on the Mac OS X platform, this is .keystore.JCEKS.Java_HotSpot_Client_VM.install). This keystore contains the IBM® code signing certificate used during install. However, during runtime provisioning, Notes® uses an additional trust store in the user's Contacts application (names.nsf). The Advanced/Certificate view of the user's Contacts application contains certificates that are used during runtime provisioning to determine trust. Trust certificates can be copied to the Advanced/Certificate view of the Contacts application using the Administrative trust defaults section of security policy or while the user is provisioning he can select Install this plug-in and add the signer to my list of trusted signers. Ideally, you should configure trust settings such that users never receive trust prompts. Push trust certificates to the user's Contacts application using policy, or the alternative deploy.nsf if you would prefer not to use policy, so that deployed features and plug-ins are installed without trust prompts.
    Note: See the related topics for information on customizing an install kit for trust defaults.

    If you have digitally signed the features to install or update, the provisioning system does the following:

    • Displays errors about untrusted content as a post-install summary
    • Provides a consistent user interface for handling trusted and untrusted content during runtime provisioning based on policy settings
    • Makes trust decisions based on managed policy settings so that you can override default settings and manage policy settings from a server

If you are signing features and plug-ins that you'll deploy to users in some way other than in the Notes® install kit, consider the following:

  • Use the Domino® Administrator to set the default signature verification policies to be used by the Notes® client using the Security Settings > Signed Plugin page.
    Note: Domino® policy takes precedent over settings in the install kit's deploy\plugin_customization.ini file. Domino® policy does not affect the initial install.
  • If you are using a deploy.nsf on the Notes® client to set trust, Notes® will read that application at startup to determine trust settings for the session. However, if you have used the Keys and Certificates tab on the Security policy dialog to push administrative trust defaults, those settings are used and the user's deploy.nsf is ignored.
  • Deploy or make available to users, the install kit, including the keystore that you updated in the install kit's deploy directory.

For more information, see Pushing certifier and trust settings using policy or a client install kit.

Signing and adding new features to the kit

About this task

Use this procedure to sign the new custom or third-party feature and plug-in JAR files and add the feature to the Notes® install kit.

This procedure assumes that you have built or the obtained JAR files for new custom or third-party features and plug-ins for use in an Eclipse update site. Use the JRE's JarSigner tool, Eclipse, or other third-party tool. See the Lotus® Expeditor wiki for information about creating valid features and plug-ins.

Procedure

  1. Set the JAVA_HOME directory environment variable, on the machine(s) on which you'll be installing Notes®, to point to the JDK folder under which the keytool resides. In the following sample command line, the needed bin\keytool would be resident in the indicated JAVA_HOME variable's directory.
    set JAVA_HOME=C:\sign-plugin\abx\java\jdk1.5.0_05
  2. Create a keystore, and generate the public/private key pair EclipseFeaturesAlias as well as a self-signed certificate associated with the private key of the pair. A sample command line is shown:
    %JAVA_HOME%\bin\keytool -genkey -dname "cn=Bob, ou=Sales, o=foo, c=US" -alias EclipseFeaturesAlias -keypass privatekeypassword -keystore C:\sign-plugin\abx\mykeystore -storepass keystorepassword -keyalg "RSA" -validity 360
  3. Display the certificate/key pair. A sample command line is shown:
    %JAVA_HOME%\bin\keytool -list -v -alias EclipseFeaturesAlias -keystore C:\sign-plugin\abx\mykeystore -storepass keystorepassword
  4. For the feature you'll be adding to the install kit, sign its updatesite JAR files (in the features folder and in the plugins folder) using the self-signed certificate/key pair. Sample command lines for signing JAR files in the features folder and plugins folder are shown:
    %JAVA_HOME%\bin\jarsigner -verbose -keystore C:\sign-plugin\abx\mykeystore -storepass keystorepassword -keypass privatekeypassword C:\sign-plugin\abx\mytestUpdatesite\features\com.ibm.sign.demo.feature_1.0.0.jar EclipseFeaturesAlias 
    %JAVA_HOME%\bin\jarsigner -verbose -keystore C:\sign-plugin\abx\mykeystore-storepass keystorepassword -keypass privatekeypassword C:\sign-plugin\abx\mytestUpdatesite\plugins\com.ibm.sign.demo_1.0.0.jar EclipseFeaturesAlias
  5. Update the install manifest (deploy\install.xml) in the Notes® install kit. A snippet is shown (see Customizing the Notes® install manifest for new or third-party Eclipse features for description of installfeature settings). 
    <?xml version="1.0" encoding="ISO-8859-1"?> 
    <ibm-portal-composite> 
    <domain-object name="com.ibm.rcp.installmanifest"> 
    <object-data>
        <install version="8.0.0.20081211.1925">
    <!-- add this sample installfeature snippet to the end of the manifest,before the </install> line --> 
    <installfeature default="false" description="My hello world feature"id="test" name="Test" required="false" show="true" version="1.0.0">
            <requirements>
                             <feature download-size="222"
    id="com.ibm.sign.demo.feature" match="perfect" shared="true" size="199"url="jar:${installer.root}/updateSite.zip!/" version="1.0.0"/>
             </requirements>
     </installfeature>
     <!-- end of addition -->
        </install>
    </object-data>
    </domain-object>
    </ibm-portal-composite>
    Note: This step is also described in the following topics: Customizing the Notes® install kit to add or remove Eclipse features and Adding new features to the Notes® install kit using a supplied tool.
  6. Add the signed feature to the Notes® install kit.
    1. Extract the Notes® install kit's updatesite.zip to c:\updatesite. This yields a features folder, plugins folder, and site.xml file.
    2. Copy your signed features and plugins JAR files to the unzipped updatesite's features and plugins folders respectively.
    3. Update the unzipped updatesite's site.xml file to reflect the new feature. A sample entry is shown:
      <feature url="features/com.ibm.sign.demo.feature_1.0.0.jar"id="com.ibm.sign.demo.feature" version="1.0.0"/>
    4. Compress the modified updatesite folder.
    5. Copy the modified updatesite.zip file to the Notes® install kit, to replace the original, supplied updatesite.zip with the one you have just modified.
  7. Export a trust certificate that can authenticate your public key. A sample command line is shown:
    %JAVA_HOME%\bin\keytool -export -alias EclipseFeaturesAlias -file EclipseFeaturesAlias.cer -keystore C:\sign-plugin\abx\mykeystore -storepass keystorepassword
  8. Add the exported trust certificate to the Notes® install kit keystore to enable trust for your public key at install. A sample command line is shown: 
    %JAVA_HOME%\bin\keytool.exe -import -keystore C:\sign-plugin\abx\AllClient.msi.w32\deploy\.keystore.JCEKS.IBM_J9_VM.install -storetype JCEKS -alias EclipseFeaturesAlias -file EclipseFeaturesAlias.cer -storepass ""
  9. List the entries in the Notes® install kit keystore. A sample command line is shown:
    %JAVA_HOME%\bin\keytool.exe -list -v -keystore C:\sign-plugin\abx\AllClient.msi.w32\deploy\.keystore.JCEKS.IBM_J9_VM.install -storetype JCEKS -alias EclipseFeaturesAlias -storepass ""