Bug 58891 - Bad and/or dangerous SSL/TLS documentation
Summary: Bad and/or dangerous SSL/TLS documentation
Alias: None
Product: Tomcat 8
Classification: Unclassified
Component: Documentation (show other bugs)
Version: 8.0.x-trunk
Hardware: PC Linux
: P2 enhancement (vote)
Target Milestone: ----
Assignee: Tomcat Developers Mailing List
Depends on:
Reported: 2016-01-19 18:12 UTC by Alexander Kjäll
Modified: 2016-05-23 16:17 UTC (History)
0 users

improve SSL/TLS documentation (6.77 KB, patch)
2016-01-19 18:12 UTC, Alexander Kjäll
Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Alexander Kjäll 2016-01-19 18:12:37 UTC
Created attachment 33465 [details]
improve SSL/TLS documentation

The current documentation gives really bad advise about how to handle SSL/TLS certificates that might even lead to peoples websites being attacked.

I have rewritten the documentation and fixed the following problems:

1) Encouragement of using self signed certificates.
2) Advise to mix SSL and non-SSL pages on the same site (this could easily lead to session cookie theft).
3) No information about HSTS
4) Outdated information about SNI and how the SSL/TLS handshake works.

Attached is a patch that rewrites the documentation
Comment 1 Remy Maucherat 2016-01-19 23:33:57 UTC
IMO this howto is a quick start with running the SSL connectors and testing them, intended for developers. SSL is complex ! It could a good idea to add some "production" SSL information in addition to that though, but I wouldn't replace the existing content.
Comment 2 Alexander Kjäll 2016-01-20 08:49:14 UTC

I agree that SSL is complex, and I don't think it's within the scope of the tomcat documentation to address all aspects of it, it can be very lengthy to describe how different attack vectors works for example. I feel that a good condensed version could be to give advise that doesn't expose users to security vulnerabilities.

But the SSL "landscape" have change significantly since the original text was written and my personal opinion is that the text needs to be a bit updated so that it reflect how the world works today.

Maybe we can break down the changes that I feel are important from a security perspective and talk about them point by point, I'm of course willing to rewrite the patch again to incorporate your feedback.

1) About self signed certs:

This is pretty important, as the original text portrays scenarios where end users are presented with self signed certs. 

A self signed cert should never be presented to end users as this doesn't offer any protection against an attacker that does a man-in-the-middle attack.

There is also no real reason to not get your certificate signed by a real CA now that Lets encrypt offers SSL/TLS certificates that are both free and automatable.

2) Mixing SSL and non-SSL pages.

This advise is also important to remove, if people do SSL like this it's trivial to steal session cookies.

With todays hardware it's also not that computable expensive to make sure all content is distributed over a secure channel.

I feel that it adds value to say something about not mixing SSL/non-SSL content, but that could maybe be removed.

3) Information about HSTS.

This isn't that important, it's more of a nice to have.

4) SNI information.

This section could maybe be phrased differently? Maybe say something about the SSL limitation to one certificate per IP not being that important now that people use IPv6?
Comment 3 Christopher Schultz 2016-01-21 02:10:42 UTC
I like the idea, I don't like your re-write as it stands. A certificate, for instance, does not guarantee security of a site. The site can be full of malware designed to attack you and still have a certificate. The certificate is a part of common-deployments of TLS, and allows for the authentication of a web site (via a third party certificate authority) and the beginning of the negotiation of encryption keys for a session.

Perhaps what we should say is this:

TLS is complex! Go read all about it [provide links] and then come back here for the configuration details.
Comment 4 Remy Maucherat 2016-01-21 17:25:34 UTC
Generally, I would like to keep the SSL page as a quick start, focusing on people being able to test SSL with Tomcat as easily as possible.

BTW, the session cookie should be marked secure and shouldn't be leaked (assuming it is created by auth, and if it is not, the auth is supposed to renew it).

The main thing I'd agree on is remove the segment on hosts, since now it is implemented.
Comment 5 Mark Thomas 2016-05-23 16:17:33 UTC
Thanks for the suggestion. I haven't used the patch as is but I have updated the SSL how-to based on this suggestion and the subsequent discussion.

The changes will be in:
- 9.0.0.M7 onwards
- 8.5.3 onwards
- 8.0.36 onwards
- 7.0.70 onwards
- 6.0.46 onwards