-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathSSLNOTES.txt
311 lines (232 loc) · 11.4 KB
/
SSLNOTES.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
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
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
Notes for use of SSL with JavaMail
----------------------------------
JavaMail now supports accessing mail servers over connections secured
using SSL or TLS. To simplify such access, there are two alternative
approaches to enable use of SSL.
First, and perhaps the simplest, is to set a property to enable use
of SSL. For example, to enable use of SSL for SMTP connections, set
the property "mail.smtp.ssl.enable" to "true".
Alternatively, you can configure JavaMail to use one of the SSL-enabled
protocol names. In addition to the non-SSL JavaMail protocols "imap",
"pop3", and "smtp", the protocols "imaps", "pop3s", and "smtps" can
be used to connect to the corresponding services using an SSL
connection.
In addition, the "imap" and "smtp" protocols support use of the
STARTTLS command (see RFC 2487 and RFC 3501) to switch the connection
to be secured by TLS.
Use of the STARTTLS command is preferred in cases where the server
supports both SSL and non-SSL connections.
This SSL/TLS support in JavaMail works only when JavaMail is used on
a version of J2SE that includes SSL support. We have tested this
support on J2SE 1.4 and newer, which include SSL support. The
SSL support is provided by the JSSE package, which is also available
for earlier versions of J2SE. We have not tested such configurations.
-- STARTTLS support
The STARTTLS support is available in the standard "imap" and "smtp"
protocols, but must be enabled by setting the appropriate property,
mail.imap.starttls.enable or mail.smtp.starttls.enable, to "true".
When set, if the server supports the STARTTLS command, it will be
used after making the connection and before sending any login
information.
-- Secure protocols
When using the new protocol names, configuration properties must also use
these protocol names. For instance, set the property "mail.smtps.host"
to specify the host name of the machine to connect to when using the
"smtps" protocol for SMTP over SSL. Similarly, to set the IMAP protocol
timeout when using the "imaps" protocol for IMAP over SSL, set the property
"mail.imaps.timeout". See the package documentation for the different
protocol packages for the list of available properties, which are
always set using property names of the form mail.<protocol>.<property>.
The Transport.send method will use the default transport protocol,
which remains "smtp". To enable SMTP connections over SSL, set the
"mail.smtp.ssl.enable" property to "true". This is usually the easiest
approach.
Alternatively, to change the default transport protocol
returned by the Session.getTransport() method to SMTP over SSL, set
the property "mail.transport.protocol" to "smtps". To change the
transport used for internet addresses (as returned by the
Session.getTransport(Address) method, and used by the Transport.send
method), use
session.setProtocolForAddress("rfc822", "smtps");
-- Trusted Certificates
To establish an SSL/TLS connection, the JavaMail client must be able
to verify that the security certificate presented by the server
it is connecting to is "trusted" by the client. Trusted certificates
are maintained in a Java keystore file on the client. The J2SE
SDK "keytool" command is used to maintain the keystore file.
There are two common approaches for verifying server certificates.
The first approach is probably most common for servers accessible to
partners outside a company. The second approach is probably most
common for servers used within a company.
1. Server certificates may be signed be a well known public
Certificate Authority. The default Java keystore file contains
the public keys of well known Certificate Authorities and can
verify the server's certificate by following the chain of
certificates signing the server's certificate back to one of
these well known CA certificates.
In this case the client doesn't need to manage certificates
explicitly but can just use the default keystore file.
2. Server certificates may be "self-signed". In this case there is
no chain of signatures to use in verifying the server's certificate.
Instead, the client will need the server's certificate in the
client's keystore file. The server's certificate is imported into
the keystore file once, using the keytool command, and after that
is used to verify connections to the server. A single keystore file
may contain certificates of many servers.
In this case the client will need to set the appropriate System
properties to point to the client's keystore file containing the
trusted certificate. These properties can be set when invoking
the "java" command, or can be set programmatically. For example,
java -Djavax.net.ssl.trustStore=$HOME/.keystore ...
See the JSSE Reference Guide for details:
http://download.oracle.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#CustomizingStores
-- Server Identity Check
RFC 2595 specifies addition checks that must be performed on the
server's certificate to ensure that the server you connected to is
the server you intended to connect to. This reduces the risk of
"man in the middle" attacks. For compatibility with earlier releases
of JavaMail, these additional checks are disabled by default. We
strongly recommend that you enable these checks when using SSL. To
enable these checks, set the "mail.<protocol>.ssl.checkserveridentity"
property to "true".
-- Socket Factories
In earlier releases it was necessary to explicitly set a socket
factory property to enable use of SSL. In almost all cases, this
is no longer necessary. SSL support is built in. However, there
is one case where a special socket factory may be needed.
JavaMail now includes a special SSL socket factory that can simplify
dealing with servers with self-signed certificates. While the
recommended approach is to include the certificate in your keystore
as described above, the following approach may be simpler in some cases.
The class com.sun.mail.util.MailSSLSocketFactory can be used as a
simple socket factory that allows trusting all hosts or a specific set
of hosts. For example:
MailSSLSocketFactory sf = new MailSSLSocketFactory();
sf.setTrustAllHosts(true);
// or
// sf.setTrustedHosts(new String[] { "my-server" });
props.put("mail.smtp.ssl.enable", "true");
// also use following for additional safety
//props.put("mail.smtp.ssl.checkserveridentity", "true");
props.put("mail.smtp.ssl.socketFactory", sf);
Use of MailSSLSocketFactory avoids the need to add the certificate to
your keystore as described above, or configure your own TrustManager
as described below.
-- Debugging
Debugging problems with certificates and keystores can be difficult.
The JSSE Reference Guide contains information on debugging utilities
that can help. See:
http://download.oracle.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#Debug
There are some debugging options in the JDK that can help, depending
on the sorts of problems you're having. Setting the following system
properties will produce additional debugging output:
java.security.debug=certpath
javax.net.debug=trustmanager
Set these on the command line when you run your program using, for example:
java -Djava.security.debug=certpath -Djavax.net.debug=trustmanager ...
-- keytool Usage
Given a certificate for the server as used in case #2 above, you can
import this certificate into your Java keystore file using a command
such as:
keytool -import -alias imap-server -file imap.cer
The keytool command can also be used to generate a self-signed certificate
that can be used by your mail server, if you're setting up your own server.
Other utilities, such as those included with the OpenSSL package, can also
be used to generate such certificates, and they can be imported into the
Java keystore using keytool.
For more information on using the keytool command, see the keytool
reference pages at:
http://download.oracle.com/javase/6/docs/technotes/guides/security/index.html
-- Configuring Your Own Trust Manager
When using SSL/TLS, it's important to ensure that the server you connect
to is actually the server you expected to connect to, to prevent "man in
the middle" attacks on your communication. The recommended technique is
to configure the Java keystore using one of the methods described above.
If, for some reason, that approach is not workable, it's also possible
to configure the SSL/TLS implementation to use your own TrustManager
class to evaluate whether to trust the server you've connected to.
The following "dummy" classes illustrate the framework necessary to create
your own TrustManager implementation.
First, a replacement for the standard SSLSocketFactory is needed, to allow
you to specify which TrustManager to use:
==> DummySSLSocketFactory.java <==
import java.io.IOException;
import java.net.InetAddress;
import java.net.Socket;
import javax.net.SocketFactory;
import javax.net.ssl.*;
/**
* DummySSLSocketFactory
*/
public class DummySSLSocketFactory extends SSLSocketFactory {
private SSLSocketFactory factory;
public DummySSLSocketFactory() {
try {
SSLContext sslcontext = SSLContext.getInstance("TLS");
sslcontext.init(null,
new TrustManager[] { new DummyTrustManager()},
null);
factory = (SSLSocketFactory)sslcontext.getSocketFactory();
} catch(Exception ex) {
// ignore
}
}
public static SocketFactory getDefault() {
return new DummySSLSocketFactory();
}
public Socket createSocket() throws IOException {
return factory.createSocket();
}
public Socket createSocket(Socket socket, String s, int i, boolean flag)
throws IOException {
return factory.createSocket(socket, s, i, flag);
}
public Socket createSocket(InetAddress inaddr, int i,
InetAddress inaddr1, int j) throws IOException {
return factory.createSocket(inaddr, i, inaddr1, j);
}
public Socket createSocket(InetAddress inaddr, int i)
throws IOException {
return factory.createSocket(inaddr, i);
}
public Socket createSocket(String s, int i, InetAddress inaddr, int j)
throws IOException {
return factory.createSocket(s, i, inaddr, j);
}
public Socket createSocket(String s, int i) throws IOException {
return factory.createSocket(s, i);
}
public String[] getDefaultCipherSuites() {
return factory.getDefaultCipherSuites();
}
public String[] getSupportedCipherSuites() {
return factory.getSupportedCipherSuites();
}
}
Next you need the actual implementation of the TrustManager. This dummy
trust manager trusts anything. THIS IS NOT SECURE!!!
==> DummyTrustManager.java <==
import javax.net.ssl.X509TrustManager;
import java.security.cert.X509Certificate;
/**
* DummyTrustManager - NOT SECURE
*/
public class DummyTrustManager implements X509TrustManager {
public void checkClientTrusted(X509Certificate[] cert, String authType) {
// everything is trusted
}
public void checkServerTrusted(X509Certificate[] cert, String authType) {
// everything is trusted
}
public X509Certificate[] getAcceptedIssuers() {
return new X509Certificate[0];
}
}
Finally, you need to configure JavaMail to use your SSLSocketFactory.
Set the appropriate protocol-specific property, e.g.,
props.setProperty("mail.imap.ssl.enable", "true");
props.setProperty("mail.imap.ssl.socketFactory.class",
"DummySSLSocketFactory");
props.setProperty("mail.imap.ssl.socketFactory.fallback", "false");
Session session = Session.getInstance(props, null);
Similar properties would need to be set to use other protocols.