Bug 57759

Summary: Clarify keyAlias definition to reduce likelihood of readers making invalid assumptions
Product: Tomcat 7 Reporter: Andrew Lane Carr <andrewlanecarr>
Component: ConnectorsAssignee: Tomcat Developers Mailing List <dev>
Status: RESOLVED FIXED    
Severity: enhancement CC: andrewlanecarr
Priority: P2    
Version: trunk   
Target Milestone: ---   
Hardware: PC   
OS: Mac OS X 10.1   
Attachments: Proposed patch to the documentation.

Description Andrew Lane Carr 2015-03-25 15:06:22 UTC 
keyAlias Definition from: 

https://tomcat.apache.org/tomcat-7.0-doc/config/http.html

The alias used to for the server certificate in the keystore. If not specified the first key read in the keystore will be used.

Wouldn't this lead you to believe if no alias is specified it will use the first key in the keystore?  This is not the case.

Steps to recreate:

Create a keystore using the recommended method: 

%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA

(This will generate ${user.home}/.keystore if it does not exist.  If it does, specify the keystore value.)

Start tomcat with the default SSL connector defined, no "keyAlias" value specified, and the keystore we created previous specified as the keystoreFile.

It will use the cert in the file.

Add another cert (specify different name and values to differentiate between the two) to the keystore with :

%JAVA_HOME%\bin\keytool" -genkey -alias tomcat2 -keyalg RSA

Shutdown and restart the tomcat instance.

Access the SSL site "localhost:8443", inspect the cert.  You will see it is not the first certificate in the keystore like the document leads you to believe, but the last one added, no matter how many you add.
Comment 1 Mark Thomas 2015-03-28 15:30:13 UTC 
(In reply to Andrew Lane Carr from comment #0)
> keyAlias Definition from: 
> 
> https://tomcat.apache.org/tomcat-7.0-doc/config/http.html
> 
> The alias used to for the server certificate in the keystore. If not
> specified the first key read in the keystore will be used.
> 
> Wouldn't this lead you to believe if no alias is specified it will use the
> first key in the keystore?

No. The documentation states the first key read from the keystore is used. It makes no statements regarding the relationship between the order the keys were added to the store, the order the keys are stored in the store (if such a concept makes sense - depening on the keystore it may not) and the order the keys are read from the keystore. All of which will depend on the implementation.

We can add a note to the documentation to clarify the above to reduce the chances of future users making such invalid assumptions.

Generally, unless there is only a single key in the key store, it is advisable to specify an alias. This advice can be added to the docs as well.
Comment 2 Mark Thomas 2015-03-28 17:04:55 UTC 
Fixed in trunk, 8.0.x (for 8.0.22 onwards), 7.0.x (for 7.0.62 onwards) and 6.0.x (for 6.0.44 onwards).
Comment 3 Andrew Lane Carr 2015-03-28 18:58:27 UTC 
Created attachment 32620 [details]
Proposed patch to the documentation.

This is my first time patching the documentation.  Should I have placed this patch somewhere else?
Comment 4 Mark Thomas 2015-03-28 20:53:35 UTC 
This is the right place and the patch looks good - it was just a couple of hours late.

Generally, patches should be against trunk and the committers will back-port them as necessary but any patch is helpful.