Author: jochen
Date: Fri Jul 14 18:58:34 2006
New Revision: 422130
URL: http://svn.apache.org/viewvc?rev=422130&view=rev
Log:
Added docs for accessing an SSL server. (XMLRPC-93)
Added:
webservices/xmlrpc/trunk/src/site/apt/ssl.apt
Modified:
webservices/xmlrpc/trunk/src/changes/changes.xml
webservices/xmlrpc/trunk/src/site/apt/advanced.apt
webservices/xmlrpc/trunk/src/site/site.xml
Modified: webservices/xmlrpc/trunk/src/changes/changes.xml
URL:
http://svn.apache.org/viewvc/webservices/xmlrpc/trunk/src/changes/changes.xml?rev=422130&r1=422129&r2=422130&view=diff
==============================================================================
--- webservices/xmlrpc/trunk/src/changes/changes.xml (original)
+++ webservices/xmlrpc/trunk/src/changes/changes.xml Fri Jul 14 18:58:34 2006
@@ -13,6 +13,9 @@
Fixed an invalid index, that caused the ReflectiveXmlRpcHandler to fail
detecting a method.
</action>
+ <action dev="jochen" type="enhancement">
+ Added documentation for accessing an SSL server.
+ </action>
</release>
<release version="3.0b1" date="24-Jun-2006">
<action dev="hgomez" type="add">
Modified: webservices/xmlrpc/trunk/src/site/apt/advanced.apt
URL:
http://svn.apache.org/viewvc/webservices/xmlrpc/trunk/src/site/apt/advanced.apt?rev=422130&r1=422129&r2=422130&view=diff
==============================================================================
--- webservices/xmlrpc/trunk/src/site/apt/advanced.apt (original)
+++ webservices/xmlrpc/trunk/src/site/apt/advanced.apt Fri Jul 14 18:58:34 2006
@@ -1,9 +1,8 @@
- --------------------
- Advanced Programming
- --------------------
+ ---------------------------
+ Advanced Programming Topics
+ ---------------------------
- The Apache XML-RPC library offers some advanced techniques, which
- are being described on this page.
+ This page describes some advanced topics.
Dynamic proxies
Added: webservices/xmlrpc/trunk/src/site/apt/ssl.apt
URL:
http://svn.apache.org/viewvc/webservices/xmlrpc/trunk/src/site/apt/ssl.apt?rev=422130&view=auto
==============================================================================
--- webservices/xmlrpc/trunk/src/site/apt/ssl.apt (added)
+++ webservices/xmlrpc/trunk/src/site/apt/ssl.apt Fri Jul 14 18:58:34 2006
@@ -0,0 +1,130 @@
+ ---------
+ Using SSL
+ ---------
+
+ This page describes how to configure a client for using SSL (aka https).
+ Server configuration is out of this documents scope, because it clearly
+ depends on the webserver. We refer, for example, to the
+ {{{http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html} Tomcat SSL HowTo}}
+ or to the FAQ entry on
+ {{{http://www.mortbay.org/jetty/faq?s=400-Security&t=ssl} SSL with Jetty}}.
+
+Background
+
+ Client configuration for SSL is not as simple as one might expect. This
+ is surprising, because using SSL with a browser is as simple as typing in
+ an https URL into the browsers input field.
+
+ Thus, the first thing to keep in mind: Never start with Apache XML-RPC as
+ a client. It is much better to create a simple static page and point your
+ browser to the static pages URL. If you get this working, then you may
+ assume that all remaining problems rest with the client.
+
+ If you did that, you may have noticed, that the browser brings up a
+ warning, that your web server is "not trusted". This is typically the
+ case, if you did not buy a certificate: For the case of simplicity,
+ developers are typically creating a so-called "self-signed certificate".
+
+ And that's exactly your most likely problem: Like pressing the browsers
+ button to "Accept the certificate" (temporarily or permanently), you've
+ got to tell your Java client, that you want to accept the certificate.
+
+Choose the right URL
+
+ Typically, your server may be accessible with multiple URL's. For example,
+ on my machine the following URL's will all reach the same servlet:
+
+ https://mcjwi.eur.ad.sag/xmlrpc
+ https://localhost/xmlrpc
+ https://127.0.0.1/xmlrpc
+
+ Unfortunately, at most one will work in the most cases. The question is:
+ How do I choose the right one?
+
+ The answer is given by the certificate field CN. For example, my self
+ certified key looks like this:
+
+ Owner: CN=mcjwi.eur.ad.sag, OU=-, O=-, L=-, ST=-, C=-
+ Issuer: CN=mcjwi.eur.ad.sag, OU=-, O=-, L=-, ST=-, C=-
+
+ Note, that you've got to pick a proper CN when generating the certificate!
+ If you are self-certifying the key and the keytool asks you for your own
+ name: Ignore it. In your case the proper reply is the host name.
+
+The quick and dirty solution
+
+ Yes, there is a quick and dirty solution: Just tell your client, that you
+ want to accept any certificate, regardless of issuer and host. This can be
+ done by installing a custom TrustManager and a HostnameVerifier. Add the
+ following code to your clients initialization:
+
+-----------------------------------------------------------------------------------
+ import java.security.cert.X509Certificate;
+
+ import javax.net.ssl.HostnameVerifier;
+ import javax.net.ssl.HttpsURLConnection;
+ import javax.net.ssl.SSLContext;
+ import javax.net.ssl.SSLSession;
+ import javax.net.ssl.TrustManager;
+ import javax.net.ssl.X509TrustManager;
+
+ // Create a trust manager that does not validate certificate chains
+ TrustManager[] trustAllCerts = new TrustManager[] {
+ new X509TrustManager() {
+ public X509Certificate[] getAcceptedIssuers() {
+ return null;
+ }
+
+ public void checkClientTrusted(X509Certificate[] certs, String
authType) {
+ // Trust always
+ }
+
+ public void checkServerTrusted(X509Certificate[] certs, String
authType) {
+ // Trust always
+ }
+ }
+ };
+
+ // Install the all-trusting trust manager
+ SSLContext sc = SSLContext.getInstance("SSL");
+ // Create empty HostnameVerifier
+ HostnameVerifier hv = new HostnameVerifier() {
+ public boolean verify(String arg0, SSLSession arg1) {
+ return true;
+ }
+ };
+
+ sc.init(null, trustAllCerts, new java.security.SecureRandom());
+ HttpsURLConnection.setDefaultSSLSocketFactory(sc.getSocketFactory());
+ HttpsURLConnection.setDefaultHostnameVerifier(hv);
+-----------------------------------------------------------------------------------
+
+The recommended solution
+
+ Needless to say, the quick and dirty solution may is insecure, because it can
+ your requests can be intercepted by a man-in-the-middle attack. Fortunately,
+ there is also a clean solution: Import the servers public key into your
+ truststore.
+
+ As a first step, you've got to obtain the servers public key. Assuming, that
+ the key is in your keystore, you may export it by running
+
+-----------------------------------------------------------------------------------
+ keytool -export -alias tomcat -rfc -file tomcat.crt
+-----------------------------------------------------------------------------------
+
+ This example would export the public key named "tomcat" (which is used by
+ Tomcat) into the file "tomcat.crt". The key would be read from your default
+ keystore, which is the file .keystore in your home directory (something like
+ "c:\Documents and Settings\jwi\.keystore" on windows or "/home/jwi/.keystore"
+ on Linux/Unix).
+
+ Obviously, this first step must be done on the server. The second step would
+ be to create a truststore on your client by importing the file "tomcat.crt":
+
+-----------------------------------------------------------------------------------
+ keytool -import -alias servercert -file tomcat.crt -keystore truststore
+-----------------------------------------------------------------------------------
+
+ The option "-keystore truststore" specifies a file name. Of course, this may
+ as well be an absolute path.
Modified: webservices/xmlrpc/trunk/src/site/site.xml
URL:
http://svn.apache.org/viewvc/webservices/xmlrpc/trunk/src/site/site.xml?rev=422130&r1=422129&r2=422130&view=diff
==============================================================================
--- webservices/xmlrpc/trunk/src/site/site.xml (original)
+++ webservices/xmlrpc/trunk/src/site/site.xml Fri Jul 14 18:58:34 2006
@@ -16,6 +16,7 @@
<item name="Client Classes" href="/client.html"/>
<item name="Server Side XML-RPC" href="/server.html"/>
<item name="Vendor Extensions" href="/extensions.html"/>
+ <item name="SSL" href="/ssl.html"/>
<item name="Advanced Techniques" href="/advanced.html"/>
<item name="XML-RPC Types" href="/types.html"/>
<item name="Download" href="/download.html"/>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
