bundles/org.eclipse.platform.doc.isv/reference/misc/bundle_security.html - gerrit/platform/eclipse.platform.common - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><HTML>
 <head>

 <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2008. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
 <meta http-equiv="Content-Language" content="en-us">
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 <link REL="STYLESHEET" HREF="../../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
 <title>Security: Protecting against malicious code</title>
 </head>
 <BODY BGCOLOR="#ffffff">

 <h1>Protecting against malicious code</h1>

 <h2>Overview</h2>

 <p>The Eclipse platform faces a problem common to any program that can be extended by executable code: the potential that the extension code may be malicious. To address this concern, Eclipse embraces and extends the facilities built into the Java runtime in order to do two things:

 <ol>
 <li>Authenticate the source of executable code in bundles</li>
 <li>Authorize the installation and runtime behaviour of code</li>
 </ol>

 <h2>Authenticating code packaged in a bundle</h2>

 <p>The first step towards protecting the platform from malicious code is 'authentication', or proving the identity of the person who is distributing the code in a bundle. This is facilitated by the use of a Public Key Infrastructure (PKI), where users are issued public certificates and private keys that uniquely identify them. Another common and well know use of certificates is the SSL protocol by which secured web sites are accessed.

 <p>The mechanism by which the authentication step is enabled is through the use of 'digital signatures' created by the code distributor, using a private key and a process called 'signing'. When consuming code and validating the identity of the code signer, the digital signatures are input  along with the signers public key - to an inverse process called verifying.

 <p>In the Java platform, digital signatures are built into the Jar packaging format. A signed jar contains additional files alongside the META-INF\MANIFEST.MF that contain the information required to verify the signature  specifically a signature file (&lt;SIGNERNAME&gt;.SF) containing cryptographic digests of the resources contained in the Jar, and a block file (&lt;SIGNERNAME&gt;.RSA or &lt;SIGNERNAME&gt;.DSA) containing the signature data and associated certificates.

 <p>Using this information, one can verify that specific resources in a Jar file have not been tampered with and also establish the identity of the signer. The runtime then determines the trustedness of the signer, the default behaviour being to check for the presence of the signer certificate (or one of its ancestor certificates) in the JREs cacerts file.

 <p>For more general information on PKI, Certificates, Digests, and Signatures:
 <ul>
 <li><a href="http://en.wikipedia.org/wiki/Public_key">http://en.wikipedia.org/wiki/Public_key</a></li>
 <li><a href="http://en.wikipedia.org/wiki/Digital_signature">http://en.wikipedia.org/wiki/Digital_signature</a></li>
 <li><a href="http://en.wikipedia.org/wiki/Hash_algorithm">http://en.wikipedia.org/wiki/Hash_algorithm</a></li>
 </ul>

 <p>For more specific information on signing in the Java platform:
 <ul>
 <li><a href="http://java.sun.com/docs/books/tutorial/deployment/jar/signindex.html">http://java.sun.com/docs/books/tutorial/deployment/jar/signindex.html</a></li>
 <li><a href="http://www.ibm.com/developerworks/library/j-jar/index.html">http://www.ibm.com/developerworks/library/j-jar/index.html</a></li>
 <li><a href="http://www.onjava.com/pub/a/onjava/2001/04/12/signing_jar.html?page=1">http://www.onjava.com/pub/a/onjava/2001/04/12/signing_jar.html?page=1</a></li>
 </ul>

 <h2>Signing code packaged in a bundle</h2>

 <p>In order to sign a bundle, an Eclipse developer has a handful of options:

 <ol>
 <li>The Java command line tool, 'jarsigner'</li>

 <p>Jarsigner is a tool that ships with the Java SDK, and can be used to generate signatures on Jar files. For more information see the SDK documentation at:
 <p>
 <a href="http://java.sun.com/j2se/1.3/docs/tooldocs/win32/jarsigner.html">http://java.sun.com/j2se/1.3/docs/tooldocs/win32/jarsigner.html</a>
 <p>
 <li>A custom ant task, <signjar></li>

 <p>The build tool, ANT, has a built-in task for automating the signing of code. For more information, see the related Ant documentation at:
 <p>
 <a href="http://ant.apache.org/manual/CoreTasks/signjar.html">http://ant.apache.org/manual/CoreTasks/signjar.html</a>
 <p>
 <li>The Eclipse 'export deployable plug-ins and fragments functionality</li>

 <p>Eclipse ships with the ability to export Eclipse plug-ins  and sign them at the same time. When exporting deployable plug-ins and fragments, there is a JAR Signing tab available. In the tab, the exporter can specify a KeyStore (a password-protected key storage) containing a private key to use for the signing.

 </ol>

 <h2>Verifying signed code packaged in a bundle</h2>

 <p>As with generation of signed bundles, verification of signed code can be done by an Eclipse developer in several ways:

 <ol>
 <li>The command line, 'jarsigner'</li>

 <p>The Jarsigner tool is also capable of verifying signatures when passed a verify option. For more information, consult the Java SDK documentation.
 <p>

 <li>Programmatically via the core Java APIs.</li>

 <p>There are several APIs in the Java API which allow access to limited details about signed Jars. For example, the java.util.JarFile API can be passed a parameter which enables verification of signatures. Several consumers of this API, including the URLClassLoader, pass this parameter to cause verification to occur. Unfortunately, little detail beyond the success or failure of verification is available through the core APIs.
 <p>

 <li>Programmatically via the Equinox 'signedcontent' APIs</li>

 <p>In 3.4, several interfaces for inspecting the signer details of a bundle have been introduced into the org.eclipse.osgi bundle. Starting with the SignedContentFactory, a developer can programmatically inspect the entries in a bundle to see signers, timestamps and whether a code signer is trusted or not. For more information see the javadoc for the org.eclipse.osgi.signedcontent package of the org.eclipse.osgi bundle.

 </ol>

 <h1>Authorization of signed code</h1>

 <p>Once the signer(s) of code packaged in a bundle is established via authentication, the next step to perform is 'authorization'. Authorization is the process by which the system decides whether a piece of code should be able to perform a specified action. Although the Java runtime supports a fine grained runtime permission model, Eclipse also supports two additional enforcement points with respect to signed code packaged in bundles. This gives Eclipse platform deployers a range of security solutions that allow tradeoffs to be made between flexibility and complexity versus manageability and performance. In Eclipse 3.4, authorization based on signatures can be performed:

 <ol>
 <li>When code is installed by the provisioning system</li>

 <p>For several releases, Eclipse has had the ability to check signatures as bundles are provisioned into the system. As the provisioning system encounters bundles, it automatically performs authentication of the code signer and will prompt if a signer is not trusted according to the system configuration. The end user will be presented with a list of untrusted signers, and choosing to trust will allow the bundles to be installed into the platform.
 <p>

 <li>When code is loaded by the runtime</li>

 <p>New to 3.4 is the ability to check the signature of code as it is loaded into the Equinox runtime. The benefit to this feature beyond checking signatures is the ability to dynamically remove trust and disable code should an exploit become known. In order to enable verification at load time, the following VM argument must be passed:
 <pre>
 	-Dosgi.signedcontent.support=authority
 </pre>

 </ol>

 <p>Full manageable support for the Java permissions architecture, often referred to as running with a SecurityManager installed is currently a work in progress. Significant work is required in tooling and usability to make a Java permission enabled installation feasible in a production environment. Updates available at:

 <ul>
 <li><a href="http://www.eclipse.org/equinox/security">http://www.eclipse.org/equinox/security</a></li>
 </ul>


 </BODY></HTML>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><HTML>
	<head>

	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2008. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
	<meta http-equiv="Content-Language" content="en-us">
	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
	<link REL="STYLESHEET" HREF="../../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
	<title>Security: Protecting against malicious code</title>
	</head>
	<BODY BGCOLOR="#ffffff">

	<h1>Protecting against malicious code</h1>

	<h2>Overview</h2>

	<p>The Eclipse platform faces a problem common to any program that can be extended by executable code: the potential that the extension code may be malicious. To address this concern, Eclipse embraces and extends the facilities built into the Java runtime in order to do two things:

	<ol>
	<li>Authenticate the source of executable code in bundles</li>
	<li>Authorize the installation and runtime behaviour of code</li>
	</ol>

	<h2>Authenticating code packaged in a bundle</h2>

	<p>The first step towards protecting the platform from malicious code is 'authentication', or proving the identity of the person who is distributing the code in a bundle. This is facilitated by the use of a Public Key Infrastructure (PKI), where users are issued public certificates and private keys that uniquely identify them. Another common and well know use of certificates is the SSL protocol by which secured web sites are accessed.

	<p>The mechanism by which the authentication step is enabled is through the use of 'digital signatures' created by the code distributor, using a private key and a process called 'signing'. When consuming code and validating the identity of the code signer, the digital signatures are input along with the signers public key - to an inverse process called verifying.

	<p>In the Java platform, digital signatures are built into the Jar packaging format. A signed jar contains additional files alongside the META-INF\MANIFEST.MF that contain the information required to verify the signature specifically a signature file (<SIGNERNAME>.SF) containing cryptographic digests of the resources contained in the Jar, and a block file (<SIGNERNAME>.RSA or <SIGNERNAME>.DSA) containing the signature data and associated certificates.

	<p>Using this information, one can verify that specific resources in a Jar file have not been tampered with and also establish the identity of the signer. The runtime then determines the trustedness of the signer, the default behaviour being to check for the presence of the signer certificate (or one of its ancestor certificates) in the JREs cacerts file.

	<p>For more general information on PKI, Certificates, Digests, and Signatures:
	<ul>
	<li><a href="http://en.wikipedia.org/wiki/Public_key">http://en.wikipedia.org/wiki/Public_key</a></li>
	<li><a href="http://en.wikipedia.org/wiki/Digital_signature">http://en.wikipedia.org/wiki/Digital_signature</a></li>
	<li><a href="http://en.wikipedia.org/wiki/Hash_algorithm">http://en.wikipedia.org/wiki/Hash_algorithm</a></li>
	</ul>

	<p>For more specific information on signing in the Java platform:
	<ul>
	<li><a href="http://java.sun.com/docs/books/tutorial/deployment/jar/signindex.html">http://java.sun.com/docs/books/tutorial/deployment/jar/signindex.html</a></li>
	<li><a href="http://www.ibm.com/developerworks/library/j-jar/index.html">http://www.ibm.com/developerworks/library/j-jar/index.html</a></li>
	<li><a href="http://www.onjava.com/pub/a/onjava/2001/04/12/signing_jar.html?page=1">http://www.onjava.com/pub/a/onjava/2001/04/12/signing_jar.html?page=1</a></li>
	</ul>

	<h2>Signing code packaged in a bundle</h2>

	<p>In order to sign a bundle, an Eclipse developer has a handful of options:

	<ol>
	<li>The Java command line tool, 'jarsigner'</li>

	<p>Jarsigner is a tool that ships with the Java SDK, and can be used to generate signatures on Jar files. For more information see the SDK documentation at:
	<p>
	<a href="http://java.sun.com/j2se/1.3/docs/tooldocs/win32/jarsigner.html">http://java.sun.com/j2se/1.3/docs/tooldocs/win32/jarsigner.html</a>
	<p>
	<li>A custom ant task, <signjar></li>

	<p>The build tool, ANT, has a built-in task for automating the signing of code. For more information, see the related Ant documentation at:
	<p>
	<a href="http://ant.apache.org/manual/CoreTasks/signjar.html">http://ant.apache.org/manual/CoreTasks/signjar.html</a>
	<p>
	<li>The Eclipse 'export deployable plug-ins and fragments functionality</li>

	<p>Eclipse ships with the ability to export Eclipse plug-ins and sign them at the same time. When exporting deployable plug-ins and fragments, there is a JAR Signing tab available. In the tab, the exporter can specify a KeyStore (a password-protected key storage) containing a private key to use for the signing.

	</ol>

	<h2>Verifying signed code packaged in a bundle</h2>

	<p>As with generation of signed bundles, verification of signed code can be done by an Eclipse developer in several ways:

	<ol>
	<li>The command line, 'jarsigner'</li>

	<p>The Jarsigner tool is also capable of verifying signatures when passed a verify option. For more information, consult the Java SDK documentation.
	<p>

	<li>Programmatically via the core Java APIs.</li>

	<p>There are several APIs in the Java API which allow access to limited details about signed Jars. For example, the java.util.JarFile API can be passed a parameter which enables verification of signatures. Several consumers of this API, including the URLClassLoader, pass this parameter to cause verification to occur. Unfortunately, little detail beyond the success or failure of verification is available through the core APIs.
	<p>

	<li>Programmatically via the Equinox 'signedcontent' APIs</li>

	<p>In 3.4, several interfaces for inspecting the signer details of a bundle have been introduced into the org.eclipse.osgi bundle. Starting with the SignedContentFactory, a developer can programmatically inspect the entries in a bundle to see signers, timestamps and whether a code signer is trusted or not. For more information see the javadoc for the org.eclipse.osgi.signedcontent package of the org.eclipse.osgi bundle.

	</ol>

	<h1>Authorization of signed code</h1>

	<p>Once the signer(s) of code packaged in a bundle is established via authentication, the next step to perform is 'authorization'. Authorization is the process by which the system decides whether a piece of code should be able to perform a specified action. Although the Java runtime supports a fine grained runtime permission model, Eclipse also supports two additional enforcement points with respect to signed code packaged in bundles. This gives Eclipse platform deployers a range of security solutions that allow tradeoffs to be made between flexibility and complexity versus manageability and performance. In Eclipse 3.4, authorization based on signatures can be performed:

	<ol>
	<li>When code is installed by the provisioning system</li>

	<p>For several releases, Eclipse has had the ability to check signatures as bundles are provisioned into the system. As the provisioning system encounters bundles, it automatically performs authentication of the code signer and will prompt if a signer is not trusted according to the system configuration. The end user will be presented with a list of untrusted signers, and choosing to trust will allow the bundles to be installed into the platform.
	<p>

	<li>When code is loaded by the runtime</li>

	<p>New to 3.4 is the ability to check the signature of code as it is loaded into the Equinox runtime. The benefit to this feature beyond checking signatures is the ability to dynamically remove trust and disable code should an exploit become known. In order to enable verification at load time, the following VM argument must be passed:
	<pre>
	-Dosgi.signedcontent.support=authority
	</pre>

	</ol>

	<p>Full manageable support for the Java permissions architecture, often referred to as running with a SecurityManager installed is currently a work in progress. Significant work is required in tooling and usability to make a Java permission enabled installation feasible in a production environment. Updates available at:

	<ul>
	<li><a href="http://www.eclipse.org/equinox/security">http://www.eclipse.org/equinox/security</a></li>
	</ul>



	</BODY></HTML>