Bug 57238 - Updated SSL/TLS information for Tomcat 8/9
Updated SSL/TLS information for Tomcat 8/9
Status: RESOLVED FIXED
Product: Tomcat 8
Classification: Unclassified
Component: Documentation
8.0.x-trunk
All All
: P2 enhancement (vote)
: ----
Assigned To: Tomcat Developers Mailing List
:
Depends on:
Blocks:
  Show dependency tree
 
Reported: 2014-11-19 17:13 UTC by Glen Peterson
Modified: 2014-12-10 05:52 UTC (History)
1 user (show)



Attachments
A documentation diff made using git-svn diff. (5.10 KB, patch)
2014-11-19 17:13 UTC, Glen Peterson
Details | Diff
Made changes as suggested by others. (7.36 KB, patch)
2014-12-06 16:42 UTC, Glen Peterson
Details | Diff
OOPS! This was my user-error in submitting my fixed patch twice. (7.36 KB, text/plain)
2014-12-06 16:46 UTC, Glen Peterson
Details

Note You need to log in before you can comment on or make changes to this bug.
Description Glen Peterson 2014-11-19 17:13:43 UTC
Created attachment 32218 [details]
A documentation diff made using git-svn diff.

ssl-howto.html: Added TLS to the title and updated to say SSL/TLS in a few places and to acknowledge that SSL is obsolete since the POODLE attack this year, and that Transport Layer Security (TLS) has replaced it.  Didn't go crazy because all the Tomcat settings are still called sslWhatever.  Linked to the security-howto.html document.

security-howto.html: Added that the ciphers attribute supports OpenSSL syntax, plus an example attribute-value that works well today.  Also added a paragraph on sslEnabledProtocols since this is the only way I know to make standalone Tomcat POODLE-proof.

I may have made these changes to the Tomcat 9 docs by accident, but they apply equally well to 8 or 9 AFAIK, so maybe someone could merge them appropriately?

Christopher Schultz suggested on the Tomcat Users list 2011-11-13 that I try submitting a documentation patch here as an attachment.  This is my first Tomcat Documentation Patch ever.
Comment 1 Christopher Schultz 2014-11-20 21:06:53 UTC
Thank you for your contribution!

A few comments on the patch:

0. "Author" tags have been discouraged, while the older contributors names have been left in for ... nostalgia?

1. The level of detail you have added to security-howto.xml is probably not necessary. The note about supporting OpenSSL-ciphers-style configuration should be in the configuration section instead. I'm not sure it's appropriate to put instructions for getting high scores on Qualys's SSL/TLS testing is appropriate.

2. I wonder about the change in naming for the "SSL" sections to "SSL/TLS". I think it's good, but might break URLs containing anchors in archives, other sites, etc. The page will still exist of course, only the anchor will no longer function. Perhaps you could add an explicit anchor alias using <a name="Introduction to SSL"><!-- --></a><a name="Introduction_to_SSL"><!-- --></a> to be kind to the anchors.
Comment 2 Mark Thomas 2014-11-24 11:36:17 UTC
The best SSL settings are a moving target. I don't think we should be putting those in the docs. Maybe on the wiki which is more ephemeral.

I've no objection to adding a link to ssllabs - it is a useful resource - but it needs to be no-follow.
Comment 3 Konstantin Kolinko 2014-12-03 04:05:44 UTC
(In reply to Christopher Schultz from comment #1)
> 0. "Author" tags have been discouraged, while the older contributors names
> have been left in for ... nostalgia?

One should not add author tags. People are credited in commit message and changelog.

> 2. I wonder about the change in naming for the "SSL" sections to "SSL/TLS".
> I think it's good, but might break URLs containing anchors in archives,
> other sites, etc. The page will still exist of course, only the anchor will
> no longer function. Perhaps you could add an explicit anchor alias using <a
> name="Introduction to SSL"><!-- --></a><a name="Introduction_to_SSL"><!--
> --></a> to be kind to the anchors.

Hint: Anchor name can be set explicitly with "anchor" attribute on a <section> or <subsection>

See r1643055 for an example.


3. Update document name in menu and on introduction page
project.xml (SSL -> SSL/TLS)
index.xml
Comment 4 Glen Peterson 2014-12-06 16:42:37 UTC
Created attachment 32263 [details]
Made changes as suggested by others.

Thank you Christopher, Mark and Konstantin for your suggestions.  I'm responding to Christopher's numbers:

0. Author tags removed.

1a. Detailed configuration examples removed.

1b. The OpenSSL-ciphers-style configuration is specific to the ciphers attribute.  The ssl-config doc says nothing about ciphers - that is only referenced in the security-how-to.  I believe the two belong together, so I left them here.

2. Made sure the old anchors are preserved.

2.5(Mark). Made links to 3rd parties no-follow

3(Konstantin). Updated the document names on the menu and introduction pages.
Comment 5 Glen Peterson 2014-12-06 16:46:53 UTC
Created attachment 32264 [details]
OOPS!  This was my user-error in submitting my fixed patch twice.
Comment 6 Glen Peterson 2014-12-06 16:50:20 UTC
Comment on attachment 32264 [details]
OOPS!  This was my user-error in submitting my fixed patch twice.

USER-ERROR SUBMISSION - please delete/ignore.
Comment 7 Konstantin Kolinko 2014-12-10 04:08:13 UTC
Applied to Tomcat trunk and 8 (r1644321, r1644333), will be in 8.0.16 onwards. Thank you.
Comment 8 Konstantin Kolinko 2014-12-10 05:52:35 UTC
Applied to Tomcat 7 as well (r1644339), will be in 7.0.58.