Bug 65007 - Misleading instructions on import an SSL certificate
Summary: Misleading instructions on import an SSL certificate
Alias: None
Product: Tomcat 8
Classification: Unclassified
Component: Documentation (show other bugs)
Version: 8.5.x-trunk
Hardware: PC Linux
: P2 normal (vote)
Target Milestone: ----
Assignee: Tomcat Developers Mailing List
URL: http://tomcat.apache.org/tomcat-8.5-d...
Depends on:
Reported: 2020-12-18 20:17 UTC by Yuval Levin
Modified: 2021-01-04 16:28 UTC (History)
0 users


Note You need to log in before you can comment on or make changes to this bug.
Description Yuval Levin 2020-12-18 20:17:24 UTC
In the page http://tomcat.apache.org/tomcat-8.5-doc/ssl-howto.html#Installing_a_Certificate_from_a_Certificate_Authority

The instructions to "Importing the Certificate" are misleading:
the command:
keytool -import -alias tomcat -keystore <your_keystore_filename>
    -file <your_certificate_filename>

Does not work and it should read:
keytool -import -alias tomcat -keystore <your_keystore_filename>
   -trustcacerts -file <your_certificate_filename>

Comment 1 Christopher Schultz 2020-12-18 22:00:55 UTC
Perhaps the HOWTO could explain the difference between using -trustcacerts and not using -trustcacerts, but it's not true that the existing instructions "do not work" and that adding -trustcacerts will solve the problem.

Whether or not -trustcacerts should be provided on the command-line depends upon the usage scenario for the user.

For example, if you are importing a self-signed certificate, specifying -trustcacerts is never necessary. It's very common to use a self-signed certificate for a Tomcat server, so I suspect this is why the documentation omits the use of -trustcacerts.

If you are importing a certificate you expect to be signed by a local CA (e.g. a corporate internal one) then you specifically DO NOT want to specify -trustcacerts as a sanity check against importing a certificate that has been signed by a globally-trustued CA (e.g. VeriSign).

Would you care to submit a documentation patch which explains the difference, and when you might want (or need) to include the -trustcacerts command-line option?
Comment 2 Yuval Levin 2020-12-18 22:07:33 UTC
Maybe I had to specify, but this is in the part that explains how to import a CA Authority cert.
BTW the documentation of 8.0 has the same explanation.
Comment 3 Christopher Schultz 2020-12-18 23:07:15 UTC
(In reply to Yuval Levin from comment #2)
> Maybe I had to specify, but this is in the part that explains how to import
> a CA Authority cert.

Good point. Note that -trustcacerts should only be necessary when importing the CA's intermediate certificate into a trust store. Once the intermediate cert is in the trust store, importing your server's certificate does not require the -trustcacerts -- because the intermediate cert is already in your trust store and therefore already trusted :)

> BTW the documentation of 8.0 has the same explanation.

And 7.0, 9.0, and 10.0. Note that 8.0 reached EOL in 2018.

Patches are always welcome.
Comment 4 Yuval Levin 2020-12-18 23:29:25 UTC
I don't know, it was the first time ever for me. I got from GoDaddy one CA (bundle) and our trusted cert (alias=tomcat). the only way I could do it was to add the -trustcacerts to the import of our trusted cert (alias=tomcat).
Also, the documentation does not explain the intermediate cert step, it has only 2 steps, the chain cert (bundle) and the "tomcat" cert.
Somehow, something is missing there.
Comment 5 Mark Thomas 2021-01-04 16:05:15 UTC
The instructions are correct for the specific example shown.

The nature of TLS is such that any change in circumstances can (and usually does) change the commands required (if you are lucky) or breaks TLS entirely (if you are unlucky).

Advice is always available via the users@ list.

I think the best thing to do is add something along the lines of the above to paragraphs to that section of the docs. I'll get that done shortly.
Comment 6 Mark Thomas 2021-01-04 16:28:27 UTC
Fixed in:
- 10.0.x for 10.0.1 onwards
- 9.0.x for 9.0.42 onwards
- 8.5.x for 8.5.62 onwards
- 7.0.x for 7.0.108 onward