151
|
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
2
|
|
3
|
|
4
|
|
5
|
|
6
|
|
7
|
|
8
|
|
9
|
|
10
|
|
11
|
|
12
|
|
13 <html xmlns="http://www.w3.org/1999/xhtml">
|
|
14 <head>
|
|
15 <title>ws-xmlrpc - Using SSL</title>
|
|
16 <style type="text/css" media="all">
|
|
17 @import url("./css/maven-base.css");
|
|
18 @import url("./css/maven-theme.css");
|
|
19 @import url("./css/site.css");
|
|
20 </style>
|
|
21 <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
|
|
22 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
|
|
23 </head>
|
|
24 <body class="composite">
|
|
25 <div id="banner">
|
|
26 <a href="" id="bannerLeft">
|
|
27
|
|
28 <img src="images/xmlrpc-logo.gif" alt="" />
|
|
29
|
|
30 </a>
|
|
31 <div class="clear">
|
|
32 <hr/>
|
|
33 </div>
|
|
34 </div>
|
|
35 <div id="breadcrumbs">
|
|
36
|
|
37
|
|
38
|
|
39
|
|
40
|
|
41
|
|
42
|
|
43
|
|
44 <div class="xleft">
|
|
45 Last Published: 2010-02-06
|
|
46 </div>
|
|
47 <div class="xright"> <a href="http://www.apache.org/" class="externalLink">Apache</a>
|
|
48 |
|
|
49 <a href="../">Webservices</a>
|
|
50 |
|
|
51 <a href="">XML-RPC</a>
|
|
52
|
|
53
|
|
54
|
|
55
|
|
56
|
|
57
|
|
58
|
|
59
|
|
60 </div>
|
|
61 <div class="clear">
|
|
62 <hr/>
|
|
63 </div>
|
|
64 </div>
|
|
65 <div id="leftColumn">
|
|
66 <div id="navcolumn">
|
|
67
|
|
68
|
|
69
|
|
70
|
|
71
|
|
72
|
|
73
|
|
74
|
|
75 <h5>XML-RPC</h5>
|
|
76 <ul>
|
|
77
|
|
78 <li class="none">
|
|
79 <a href="index.html">Overview</a>
|
|
80 </li>
|
|
81
|
|
82 <li class="none">
|
|
83 <a href="download.html">Download</a>
|
|
84 </li>
|
|
85
|
|
86 <li class="none">
|
|
87 <a href="changes-report.html">Changes</a>
|
|
88 </li>
|
|
89
|
|
90 <li class="none">
|
|
91 <a href="mail-lists.html">Mailing Lists</a>
|
|
92 </li>
|
|
93
|
|
94 <li class="none">
|
|
95 <a href="contributing.html">Contributing</a>
|
|
96 </li>
|
|
97
|
|
98 <li class="none">
|
|
99 <a href="xmlrpc2">XML-RPC 2</a>
|
|
100 </li>
|
|
101
|
|
102 <li class="none">
|
|
103 <a href="links.html">Links</a>
|
|
104 </li>
|
|
105 </ul>
|
|
106 <h5>Documentation</h5>
|
|
107 <ul>
|
|
108
|
|
109 <li class="none">
|
|
110 <a href="client.html">Client Classes</a>
|
|
111 </li>
|
|
112
|
|
113 <li class="none">
|
|
114 <a href="server.html">Server Side XML-RPC</a>
|
|
115 </li>
|
|
116
|
|
117 <li class="none">
|
|
118 <a href="extensions.html">Vendor Extensions</a>
|
|
119 </li>
|
|
120
|
|
121 <li class="none">
|
|
122 <strong>SSL</strong>
|
|
123 </li>
|
|
124
|
|
125 <li class="none">
|
|
126 <a href="introspection.html">Introspection</a>
|
|
127 </li>
|
|
128
|
|
129 <li class="none">
|
|
130 <a href="advanced.html">Advanced Techniques</a>
|
|
131 </li>
|
|
132
|
|
133 <li class="none">
|
|
134 <a href="types.html">XML-RPC Types</a>
|
|
135 </li>
|
|
136
|
|
137 <li class="none">
|
|
138 <a href="faq.html">FAQ</a>
|
|
139 </li>
|
|
140
|
|
141 <li class="none">
|
|
142 <a href="apidocs/index.html">Javadocs</a>
|
|
143 </li>
|
|
144 </ul>
|
|
145 <h5>Project Documentation</h5>
|
|
146 <ul>
|
|
147
|
|
148
|
|
149
|
|
150
|
|
151
|
|
152
|
|
153
|
|
154
|
|
155
|
|
156
|
|
157
|
|
158
|
|
159
|
|
160
|
|
161
|
|
162
|
|
163
|
|
164
|
|
165
|
|
166
|
|
167
|
|
168
|
|
169
|
|
170
|
|
171
|
|
172
|
|
173
|
|
174 <li class="collapsed">
|
|
175 <a href="project-info.html">Project Information</a>
|
|
176 </li>
|
|
177
|
|
178
|
|
179
|
|
180
|
|
181
|
|
182
|
|
183
|
|
184
|
|
185
|
|
186 <li class="collapsed">
|
|
187 <a href="project-reports.html">Project Reports</a>
|
|
188 </li>
|
|
189 </ul>
|
|
190 <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
|
|
191 <img alt="Built by Maven" src="./images/logos/maven-feather.png"></img>
|
|
192 </a>
|
|
193
|
|
194
|
|
195
|
|
196
|
|
197
|
|
198
|
|
199
|
|
200
|
|
201 </div>
|
|
202 </div>
|
|
203 <div id="bodyColumn">
|
|
204 <div id="contentBox">
|
|
205 <p>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 <a href="http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html" class="externalLink"> Tomcat SSL HowTo</a> or to the FAQ entry on <a href="http://docs.codehaus.org/display/JETTY/How+to+configure+SSL" class="externalLink"> SSL with Jetty</a>.</p>
|
|
206 <div class="section"><h2>Background</h2>
|
|
207 <p>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.</p>
|
|
208 <p>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.</p>
|
|
209 <p>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".</p>
|
|
210 <p>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.</p>
|
|
211 </div>
|
|
212 <div class="section"><h2>Choose the right URL</h2>
|
|
213 <p>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:</p>
|
|
214 <p>https://mcjwi.eur.ad.sag/xmlrpc https://localhost/xmlrpc https://127.0.0.1/xmlrpc</p>
|
|
215 <p>Unfortunately, at most one will work in the most cases. The question is: How do I choose the right one?</p>
|
|
216 <p>The answer is given by the certificate field CN. For example, my self certified key looks like this:</p>
|
|
217 <p>Owner: CN=mcjwi.eur.ad.sag, OU=-, O=-, L=-, ST=-, C=- Issuer: CN=mcjwi.eur.ad.sag, OU=-, O=-, L=-, ST=-, C=-</p>
|
|
218 <p>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.</p>
|
|
219 </div>
|
|
220 <div class="section"><h2>The quick and dirty solution</h2>
|
|
221 <p>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:</p>
|
|
222 <div class="source"><pre> import java.security.cert.X509Certificate;
|
|
223
|
|
224 import javax.net.ssl.HostnameVerifier;
|
|
225 import javax.net.ssl.HttpsURLConnection;
|
|
226 import javax.net.ssl.SSLContext;
|
|
227 import javax.net.ssl.SSLSession;
|
|
228 import javax.net.ssl.TrustManager;
|
|
229 import javax.net.ssl.X509TrustManager;
|
|
230
|
|
231 // Create a trust manager that does not validate certificate chains
|
|
232 TrustManager[] trustAllCerts = new TrustManager[] {
|
|
233 new X509TrustManager() {
|
|
234 public X509Certificate[] getAcceptedIssuers() {
|
|
235 return null;
|
|
236 }
|
|
237
|
|
238 public void checkClientTrusted(X509Certificate[] certs, String authType) {
|
|
239 // Trust always
|
|
240 }
|
|
241
|
|
242 public void checkServerTrusted(X509Certificate[] certs, String authType) {
|
|
243 // Trust always
|
|
244 }
|
|
245 }
|
|
246 };
|
|
247
|
|
248 // Install the all-trusting trust manager
|
|
249 SSLContext sc = SSLContext.getInstance("SSL");
|
|
250 // Create empty HostnameVerifier
|
|
251 HostnameVerifier hv = new HostnameVerifier() {
|
|
252 public boolean verify(String arg0, SSLSession arg1) {
|
|
253 return true;
|
|
254 }
|
|
255 };
|
|
256
|
|
257 sc.init(null, trustAllCerts, new java.security.SecureRandom());
|
|
258 HttpsURLConnection.setDefaultSSLSocketFactory(sc.getSocketFactory());
|
|
259 HttpsURLConnection.setDefaultHostnameVerifier(hv);
</pre>
|
|
260 </div>
|
|
261 </div>
|
|
262 <div class="section"><h2>The recommended solution</h2>
|
|
263 <p>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.</p>
|
|
264 <p>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</p>
|
|
265 <div class="source"><pre> keytool -export -alias tomcat -rfc -file tomcat.crt
</pre>
|
|
266 </div>
|
|
267 <p>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).</p>
|
|
268 <p>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":</p>
|
|
269 <div class="source"><pre> keytool -import -alias servercert -file tomcat.crt -keystore truststore
</pre>
|
|
270 </div>
|
|
271 <p>The option "-keystore truststore" specifies a file name. Of course, this may as well be an absolute path.</p>
|
|
272 </div>
|
|
273
|
|
274 </div>
|
|
275 </div>
|
|
276 <div class="clear">
|
|
277 <hr/>
|
|
278 </div>
|
|
279 <div id="footer">
|
|
280 <div class="xright">©
|
|
281 2001-2010
|
|
282
|
|
283 The Apache Software Foundation
|
|
284
|
|
285
|
|
286
|
|
287
|
|
288
|
|
289
|
|
290
|
|
291
|
|
292 </div>
|
|
293 <div class="clear">
|
|
294 <hr/>
|
|
295 </div>
|
|
296 </div>
|
|
297 </body>
|
|
298 </html>
|