ace-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r815449 - in /websites/staging/ace/trunk/content: ./ dev-doc/design/index.html dev-doc/design/using-client-certificates.html
Date Wed, 02 May 2012 15:18:53 GMT
Author: buildbot
Date: Wed May  2 15:18:52 2012
New Revision: 815449

Log:
Staging update by buildbot for ace

Added:
    websites/staging/ace/trunk/content/dev-doc/design/using-client-certificates.html
Modified:
    websites/staging/ace/trunk/content/   (props changed)
    websites/staging/ace/trunk/content/dev-doc/design/index.html

Propchange: websites/staging/ace/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed May  2 15:18:52 2012
@@ -1 +1 @@
-1330759
+1333075

Modified: websites/staging/ace/trunk/content/dev-doc/design/index.html
==============================================================================
--- websites/staging/ace/trunk/content/dev-doc/design/index.html (original)
+++ websites/staging/ace/trunk/content/dev-doc/design/index.html Wed May  2 15:18:52 2012
@@ -156,6 +156,7 @@
 <ul>
 <li><a href="ace-deployment-strategies.html">Customizing Deployment Strategies</a></li>
 <li><a href="ace-authentication.html">Configuring ACE authentication</a></li>
+<li><a href="using-client-certificates.html">Using client certificates authentication</a></li>
 </ul>
 <h2 id="miscellaneous">Miscellaneous</h2>
 <ul>

Added: websites/staging/ace/trunk/content/dev-doc/design/using-client-certificates.html
==============================================================================
--- websites/staging/ace/trunk/content/dev-doc/design/using-client-certificates.html (added)
+++ websites/staging/ace/trunk/content/dev-doc/design/using-client-certificates.html Wed May
 2 15:18:52 2012
@@ -0,0 +1,288 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+  <head>
+    <title>Using client certificate authentication</title>
+
+    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+    <meta property="og:image" content="http://www.apache.org/images/asf_logo.gif" />
+
+    <link rel="stylesheet/less" type="text/css" href="/lib/bootstrap.less">
+    <link href="/css/prettify.css" rel="stylesheet">
+	<link href="/css/code.css" rel="stylesheet" media="screen">
+    <script src="/js/less-1.2.1.min.js" type="text/javascript"></script>
+    <script src="http://code.jquery.com/jquery-1.7.min.js"></script>
+    <script src="/js/prettify.js"></script>
+    
+    <script src="/js/bootstrap-alert.js"></script>
+    <script src="/js/bootstrap-dropdown.js"></script>
+    <script src="/js/bootstrap-tooltip.js"></script>
+    <script src="/js/bootstrap-alerts.js"></script>
+    <script src="/js/bootstrap-modal.js"></script>
+    <script src="/js/bootstrap-transition.js"></script>
+    <script src="/js/bootstrap-button.js"></script>
+    <script src="/js/bootstrap-popover.js"></script>
+    <script src="/js/bootstrap-twipsy.js"></script>
+    <script src="/js/bootstrap-buttons.js"></script>
+    <script src="/js/bootstrap-scrollspy.js"></script>
+    <script src="/js/bootstrap-typeahead.js"></script>
+    <script src="/js/bootstrap-carousel.js"></script>
+    <script src="/js/bootstrap-tab.js"></script>
+    <script src="/js/bootstrap-collapse.js"></script>
+    <script src="/js/bootstrap-tabs.js"></script>
+    
+    
+    
+    <script>
+    $(function () { prettyPrint() })
+    $().dropdown()
+    </script>
+  </head>
+
+  <body style="padding-top: 50px;">
+    <div class="navbar navbar-fixed-top">
+      <div class="navbar-inner">
+        <div class="container">
+          <a class="brand" href="/index.html">Apache ACE</a>
+          <ul class="nav">
+  <li class="dropdown">
+    <a href="#" class="dropdown-toggle" data-toggle="dropdown">News <b class="caret"></b></a>
+    <ul class="dropdown-menu">
+      <li>
+        <a href="/news.html">News</a>
+      </li>
+      <li>
+        <a href="/on-the-web.html">On the web</a>
+      </li>
+    </ul>
+  </li>
+  <li>
+    <a href="/downloads.html">Downloads</a>
+  </li>
+  <li class="dropdown">
+    <a href="#" class="dropdown-toggle" data-toggle="dropdown">User Documentation <b
class="caret"></b></a>
+    <ul class="dropdown-menu">
+      <li>
+        <a href="/user-doc/introduction.html">Introduction</a>
+      </li>
+      <li>
+        <a href="/user-doc/getting-started.html">Getting Started</a>
+      </li>
+      <li>
+        <a href="/user-doc/features.html">Features</a>
+      </li>
+      <li>
+        <a href="/user-doc/faq.html">FAQ</a>
+      </li>
+      <li>
+        <a href="/user-doc/support.html">Support</a>
+      </li>
+    </ul>
+  </li>
+  <li class="dropdown">
+    <a href="#" class="dropdown-toggle" data-toggle="dropdown">Developer Documentation
<b class="caret"></b></a>
+    <ul class="dropdown-menu">
+      <li>
+        <a href="/dev-doc/requirements/">Requirements</a>
+      </li>
+      <li>
+        <a href="/dev-doc/architecture.html">Architecture</a>
+      </li>
+      <li>
+        <a href="/dev-doc/analysis/">Analysis</a>
+      </li>
+      <li>
+        <a href="/dev-doc/design/">Design</a>
+      </li>
+      <li>
+        <a href="/dev-doc/coding-standards.html">Coding Standards</a>
+      </li>
+    </ul>
+  </li>
+  <li class="dropdown">
+    <a href="#" class="dropdown-toggle" data-toggle="dropdown">Get Involved <b class="caret"></b></a>
+    <ul class="dropdown-menu">
+      <li>
+        <a href="/get-involved/mailing-lists.html">Mailing Lists</a>
+      </li>
+      <li>
+        <a href="/get-involved/issue-tracking.html">Issue Tracking</a>
+      </li>
+      <li>
+        <a href="/get-involved/source-code.html">Source Code</a>
+      </li>
+      <li>
+        <a href="/get-involved/project-team.html">Project Team</a>
+      </li>
+    </ul>
+  </li>
+  <li class="dropdown">
+    <a href="#" class="dropdown-toggle" data-toggle="dropdown">Wiki <b class="caret"></b></a>
+    <ul class="dropdown-menu">
+      <li>
+        <a href="https://cwiki.apache.org/confluence/display/ACE/Board+Reports">Board
Reports <i class="icon-share-alt"></i></a>
+      </li>
+      <li>
+        <a href="https://cwiki.apache.org/confluence/display/ACE/Index">Homepage <i
class="icon-share-alt"></i></a>
+      </li>
+    </ul>
+  </li>
+  <li class="dropdown">
+    <a href="#" class="dropdown-toggle" data-toggle="dropdown">Apache <b class="caret"></b></a>
+    <ul class="dropdown-menu">
+      <li>
+        <a href="http://www.apache.org/licenses/">Licenses <i class="icon-share-alt"></i></a>
+      </li>
+      <li>
+        <a href="http://www.apache.org/security/">Security <i class="icon-share-alt"></i></a>
+      </li>
+      <li>
+        <a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship <i
class="icon-share-alt"></i></a>
+      </li>
+      <li>
+        <a href="http://www.apache.org/foundation/thanks.html">Thanks <i class="icon-share-alt"></i></a>
+      </li>
+    </ul>
+  </li>
+</ul>
+
+        </div>
+      </div>
+    </div>
+    <div class="container">
+      <p><a href="/"><i class='icon-home'></i> Home</a>&nbsp;&raquo&nbsp;<a
href="/dev-doc/">Dev-doc</a>&nbsp;&raquo&nbsp;<a href="/dev-doc/design/">Design</a></p>
+      <h1>Using client certificate authentication</h1>
+      <div class="clear"></div>
+      <div id="content"><p><em>Using two-way SSL as authentication mechanism
in ACE</em></p>
+<p>Revision 0.9, last updated: May 2nd, 2012.</p>
+<div class="toc">
+<ul>
+<li><a href="#introduction">Introduction</a></li>
+<li><a href="#outline">Outline</a></li>
+<li><a href="#configuring-two-way-ssl-authentication">Configuring two-way SSL
authentication</a><ul>
+<li><a href="#using-multiple-different-keystores">Using multiple different keystores</a></li>
+</ul>
+</li>
+<li><a href="#faq">FAQ</a></li>
+<li><a href="#references">References</a></li>
+<li><a href="#notes">Notes</a></li>
+</ul>
+</div>
+<h2 id="introduction">Introduction</h2>
+<p>One-way SSL authentication is used to let a client verify the identity of the server
it is communicating with. The server itself does not verify the identity of the client. In
two-way SSL authentication, a client first verifies the identity of the server after which
the server identifies the client. This way, the identity of both the client and server can
be established allowing a trust relation can be created.<br />
+This article describes how to configure the ACE server and the management agent(s) in such
way that they use two-way SSL authentication. The remainder of this article assumes the reader
has basic knowledge of the principles behind ACE, and has basic knowledge about creating and
using certificates. For this article, the latest code of ACE (0.8.1-SNAPSHOT, rev.1332609)
was used.</p>
+<h2 id="outline">Outline</h2>
+<p>As described in detail in [1], there are multiple communication paths that can (and
need) to be secured. For two-way SSL authentication, several scenarios can be identified:</p>
+<ol>
+<li>only the communication between management agent and ACE server is secured by means
of two-way SSL. This implies that there is only  a trust relation between management agent
and ACE server, but the other clients that make use of the ACE server have no trust relation
(i.e., they still communicate by means of one-way SSL or might not even use SSL at all);</li>
+<li>all the communication paths for the ACE server are secured by means of two-way
SSL. This means that not only a trust relation exists between management agent and ACE server,
but also between, for example, the web-UI and the ACE server or the REST-API and the ACE server<sup
id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup>.</li>
+</ol>
+<p>In conclusion, we need to configure the trust relation between management agent
and the ACE server, and, optionally, the trust relation between ACE server and other components.</p>
+<h2 id="configuring-two-way-ssl-authentication">Configuring two-way SSL authentication</h2>
+<p>For two-way SSL authentication, you need two (or more) certificates. These can be
issued either by an official external certificate authority (CA), or by means of a self-signed
CA<sup id="fnref:2"><a href="#fn:2" rel="footnote">2</a></sup>.<br
/>
+The details on how to create a self-signed CA and certificates is well documented on many
places on the Internet, and therefore goes beyond this article. Let's assume we've got the
following:</p>
+<ul>
+<li>a self-signed CA whose certificate is added to a Java keystore file, called <tt>truststore</tt>.
This file will be used as <em>truststore</em> for both the management agent and
the ACE server<sup id="fnref:3"><a href="#fn:3" rel="footnote">3</a></sup>;</li>
+<li>a certificate (signed by our self-signed CA) for the management agent, available
in a Java keystore file, called <tt>keystore-ma</tt>;</li>
+<li>a certificate (signed by our self-signed CA) for the ACE server, available in a
Java keystore file, called <tt>keystore-server</tt>.</li>
+</ul>
+<p>For the management agent, we need to add some system properties in order to let
Java find and use the correct truststore and keystore (see also [2]):</p>
+<div class="codehilite"><pre><span class="o">[</span>localhost:/<span
class="o">]</span><span class="nv">$ </span>java <span class="se">\</span>
+  -Djavax.net.ssl.trustStore<span class="o">=</span>/path/to/truststore <span
class="se">\</span>
+  -Djavax.net.ssl.trustStorePassword<span class="o">=</span>secret <span class="se">\</span>
+  -Djavax.net.ssl.keyStore<span class="o">=</span>/path/to/keystore-ma <span
class="se">\</span>
+  -Djavax.net.ssl.keyStorePassword<span class="o">=</span>secret <span class="se">\</span>
+  -jar org.apache.ace.launcher-0.8.1-SNAPSHOT.jar <span class="se">\</span>
+  <span class="nv">discovery</span><span class="o">=</span>https://10.0.1.16:8443
<span class="se">\</span>
+  <span class="nv">identification</span><span class="o">=</span>MyTarget
+</pre></div>
+
+
+<p><em>Note to double check the paths to both files, as there will not be printed
any error in case one of them points to an incorrect file!</em></p>
+<p>For the ACE server, the configuration is provided by means of a property-file called
<tt>platform.properties</tt>. Similar as the management agent, we should add some
additional properties to it:</p>
+<div class="codehilite"><pre><span class="na">-Dorg.osgi.service.http.port.secure</span><span
class="o">=</span><span class="s">8443</span>
+<span class="na">-Dorg.apache.felix.https.enable</span><span class="o">=</span><span
class="s">true</span>
+<span class="na">-Dorg.apache.felix.https.truststore</span><span class="o">=</span><span
class="s">/path/to/truststore</span>
+<span class="na">-Dorg.apache.felix.https.truststore.password</span><span
class="o">=</span><span class="s">secret</span>
+<span class="na">-Dorg.apache.felix.https.keystore</span><span class="o">=</span><span
class="s">/path/to/keystore-server</span>
+<span class="na">-Dorg.apache.felix.https.keystore.password</span><span class="o">=</span><span
class="s">secret</span>
+<span class="na">-Dorg.apache.felix.https.clientcertificate</span><span class="o">=</span><span
class="s">needs</span>
+</pre></div>
+
+
+<p>This will not only ensure that the Jetty container inside ACE will obtain the correct
keystore and truststore and start a listener on port <tt>8443</tt>, but also mandates
that all clients <strong>must</strong> provide a certificate upon connecting (as
denoted by the last property). Without this, client that do not offer a client certificate
will simply be accepted as well, hence resulting in only one-way SSL authentication.<br
/>
+</p>
+<p>In order to secure all internal communication paths as well, we need to specify
some additional properties in <tt>platform.properties</tt>:</p>
+<div class="codehilite"><pre><span class="na">-Djavax.net.ssl.keyStore</span><span
class="o">=</span><span class="s">/path/to/keystore-server</span>
+<span class="na">-Djavax.net.ssl.keyStorePassword</span><span class="o">=</span><span
class="s">secret</span>
+<span class="na">-Djavax.net.ssl.trustStore</span><span class="o">=</span><span
class="s">/path/to/truststore</span>
+<span class="na">-Djavax.net.ssl.trustStorePassword</span><span class="o">=</span><span
class="s">secret</span>
+</pre></div>
+
+
+<p>This will ensure that all created HTTPS connections will use the mentioned keystore
and truststore.<br />
+Note that in order to let <strong>all</strong> communication to use HTTPS, you
need to modify the configuration files of ACE (as found in the <tt>conf</tt> directory)
to mention this, for example, the <tt>org.apache.ace.webui.vaadin.cfg</tt> file
would look like:</p>
+<div class="codehilite"><pre><span class="c"># The endpoint of the Vaadin
UI</span>
+<span class="na">org.apache.ace.server.servlet.endpoint</span> <span class="o">=</span>
<span class="s">/ace</span>
+<span class="c"># Vaadin UI settings</span>
+<span class="na">ui.authentication.enabled</span> <span class="o">=</span>
<span class="s">true</span>
+<span class="c">#ui.authentication.user.name = d</span>
+<span class="c">#ui.authentication.user.password = f</span>
+<span class="c"># ACE MS settings</span>
+<span class="na">ace.host</span> <span class="o">=</span> <span
class="s">https://10.0.1.16:8443/</span>
+<span class="c"># OBR settings</span>
+<span class="na">obr.url</span> <span class="o">=</span> <span
class="s">https://10.0.1.16:8443/obr/</span>
+</pre></div>
+
+
+<p>Alternatively, one could also provide a keystore with a <em>different</em>
certificate for securing the internal communication as well. The only thing needed is to change
the <tt>javax.net.ssl.keyStore</tt> property to let it point to another keystore
file.</p>
+<h3 id="using-multiple-different-keystores">Using multiple different keystores</h3>
+<p>So far, we only used the "standard" Java functionality to secure the communication
paths with two-way SSL authentication. While this works for most use cases, one can think
of more sophisticated scenario's in which multiple trust relations between different hosts
have to be created. For example, when the OBR of ACE runs on a different host, secured with
its own certificate. In order to support this use case, we can leverage the authentication
framework of ACE by providing it configurations for all URLs that need their own keystore
and/or truststore. In our OBR example, we could supply the following configuration to the
<tt>ConnectionFactory</tt>:</p>
+<div class="codehilite"><pre><span class="na">authentication.baseURL</span>
<span class="o">=</span> <span class="s">https://10.0.1.17:8443/obr/</span>
+<span class="na">authentication.type</span> <span class="o">=</span>
<span class="s">client_cert</span>
+<span class="c"># optional: use a specific keystore for this URL</span>
+<span class="na">authentication.keystore.file</span> <span class="o">=</span>
<span class="s">/path/to/obr-keystore</span>
+<span class="na">authentication.keystore.storepass</span> <span class="o">=</span>
<span class="s">secret</span>
+<span class="c"># optional: use a specific truststore for this URL</span>
+<span class="na">authentication.truststore.file</span> <span class="o">=</span>
<span class="s">/path/to/obr-truststore</span>
+<span class="na">authentication.truststore.storepass</span> <span class="o">=</span>
<span class="s">secret</span>
+</pre></div>
+
+
+<p>Different configurations can be supplied for different URLs, allowing many different
trust relations to be established.</p>
+<p>Be sure that in order to let ACE correctly map certificates to users, you need to
install the <tt>ClientCertAuthenticationProcessor</tt> as additional authentication
processor! </p>
+<h2 id="faq">FAQ</h2>
+<dl>
+<dt>How should I name the certificates?</dt>
+<dd>One should use the hostname of the calling side as common name (CN) of the certificate's
distinguished name (DN), for example, <tt>CN=localhost</tt> or <tt>CN=10.0.1.16</tt>;</dd>
+<dt>How should I name the users that are authenticated through certificates?</dt>
+<dd>The user should have the same name as the common name of the certificate, for example,
<tt>localhost</tt> or <tt>10.0.1.16</tt>;</dd>
+<dt>I've enabled two-way SSL authentication, but it doesn't work!</dt>
+<dd>There can be many reasons for this, like, can the truststore and keystore files
be loaded (<em>no warnings or errors will be printed for this!</em>), or, is the
name of the certificate matching the name of the host, or …? In general, if it doesn't
work, one should enable SSL-debugging in Java by adding <tt>-Djavax.net.debug=ssl</tt>
as system property. This will print <em>lots</em> of information about the keystore
and truststore, the communication itself as well as detailed error messages. Also, the authentication
parts in ACE provide lots of debugging information, logged at <tt>DEBUG</tt> level.</dd>
+</dl>
+<h2 id="references">References</h2>
+<ol>
+<li>Developer documentation on <a href="/dev-doc/design/ace-authentication.html">ACE
Authentication</a>;</li>
+<li><a href="http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.html#Customization">JSSE
Reference Guide for JDK 5.0</a>;</li>
+</ol>
+<h2 id="notes">Notes</h2>
+<div class="footnote">
+<hr />
+<ol>
+<li id="fn:1">
+<p>One can argue whether this is strictly necessary for <strong>all</strong>
internal communication paths, as we will see later on, one can configure which paths use two-way
SSL authentication and which paths do not.&#160;<a href="#fnref:1" rev="footnote" title="Jump
back to footnote 1 in the text">&#8617;</a></p>
+</li>
+<li id="fn:2">
+<p>Using a self-signed CA for two-way SSL authentication is not that much of a problem
as one needs to make the certificate of the client available to the server, and the other
way around. When both certificates are signed by the same CA, and both sides also trust this
self-signed CA, the trust relation between client and server can be established as well.&#160;<a
href="#fnref:2" rev="footnote" title="Jump back to footnote 2 in the text">&#8617;</a></p>
+</li>
+<li id="fn:3">
+<p>Based on the certificate in the truststore, each side will be able to validate the
certificate of the other side.&#160;<a href="#fnref:3" rev="footnote" title="Jump back
to footnote 3 in the text">&#8617;</a></p>
+</li>
+</ol>
+</div></div>
+      <hr>
+      <footer>
+        <p>Copyright &#169; 2012 <a href="http://www.apache.org/">The Apache
Software Foundation</a>, Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache
License, Version 2.0</a>.<br/>Apache ACE, the Apache ACE logo, Apache and the
Apache feather logo are trademarks of The Apache Software Foundation. All other marks mentioned
may be trademarks or registered trademarks of their respective owners.</p>
+      </footer>
+    </div>
+  </body>
+</html>



Mime
View raw message