Code change requirement when moving from ssl-1.0 to transportSecurity-1.0 (=Migrating from JavaEE to JakartaEE)

[una-tapa]

I am opening this issue per suggestion in this internal Slack discussion.

During JavaEE to JakartaEE migration, the server's ssl-1.0 feature is automatically switched to transportSecurity-1.0.
It was a design decision that JavartaEE does not provide ways to go back to ssl-1.0 feature.

A user reported that his application no longer works after moving from JavaEE to JakartaEE. Since ssl-1.0 feature is no longer available, the issue was resolved by the customer making code change in his application.

I would like Liberty doc to add the following information:

When SSL-1.0 is active, Liberty's default SSLContext is acquired using SSLContext.getDefault(). 
However, when TransportSecurity-1.0 is enabled, SSLContext.getDefault() will yield the JSSE SSLContext, 
potentially causing a change in behavior. To obtain the SSLContext for Liberty's default configuration in this case, 
you should use Liberty's API JSSEHelper.getInstance().getSSLContext(null, null, null) instead of SSLContext.getDefault(). 

I did not have luck finding an existing page for this topic in OpenLiberty documentation. Please help us find the place (or we might need to keep using the following WebSphere Liberty documentation)

For WebSphere Liberty, I found the behavior difference of ssl-1.0 and transportSecurity-1.0 is discussed in detail in the following page https://www.ibm.com/docs/en/was-liberty/core?topic=liberty-enabling-ssl-communication-in

There is an existing note below:
Note: Due to the nature of the JDK, if you are changing from the transportSecurity-1.0 feature to the ssl-1.0 feature or from the ssl-1.0 feature to the transportSecurity-1.0 feature, the Liberty server must be restarted to use the feature to its complete functionality.

Under this note, I would like the following added with a link to a new info (above section)

The customer was using the Liberty dev experience, he had to look for the following dependency to the pom.xml file to use JSSEHelper API. I thought it would be nice if our doc has this info with the required code change details. But it could be too much information. The following is for the doc team's evaluation.

For OpenLiberty, the following dependency needs to be added to be able to call JSSEHelper API without compile error.

	<dependency>
            <groupId>io.openliberty.features</groupId>
            <artifactId>transportSecurity-1.0</artifactId>
            <version>23.0.0.8</version>
            <type>pom</type>
            <scope>provided</scope>
    </dependency>

For WebSphere Liberty, a similar dependency would be needed. It should be something like below.

<dependency>
	<groupId>com.ibm.websphere.appserver.api</groupId>
	<artifactId>????</artifactId>  <= I have not figured out. 
	<version>1.1.70</version>
</dependency>

Additional note:
The migration team has been notified and they are agreeable to add a rule to the migration tool.

[dmuelle]

Hi @una-tapa

The corresponding SSL info on the open liberty site is here:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/transportSecurity-1.0.html

The second paragraph on this page describes how transport security obtains the SSL Context, that it returns the JSSE context and sets a custom SSL Socket Factory w/ the Liberty default context. We wroked with Alaine to add this statement last year. Not sure if it will need an edit in light of this case.

I added the third paragraph to redirect to a new troubleshooting item for moving btwn ssl-1.0 and transportSecurity-1.0 w/r/t obtaining the default SSLContext. This section includes the suggestion to use JSSEHelper.getInstance().getSSLContext(null, null, null).

However, I wonder if these two statements will be confusing to customers as they seem to suggest two different things-

on the transportSecurity page

When the Transport Security feature is enabled, the SSL context for the process is the default SSL context of the Java Secure Socket Extension (JSSE). Therefore, the SSLContext.getDefault() method returns the default SSL context of the JSSE. However, when this feature is enabled, Open Liberty also sets a custom SSL socket factory. Therefore, the SSLSocketFactory.getDefault() method returns an SSL socket factory that is based on the Open Liberty custom socket factory provider, which uses the Open Liberty SSL context instead of the JSSE default.

in the new troubleshooting note

...To obtain the default Liberty SSLContext class when the Transport Security feature is enabled, use the JSSEHelper.getInstance().getSSLContext(null, null, null) method instead of the SSLContext.getDefault() method.

Let me know if any further edits are needed to correct inconsistencies or make the distinction between the two suggestions more clear.

On the WL side, I added a link to this information from the top of the SSL page, per our strategy. I also added a troubleshooting note to the ssl/TLS troubleshooting info and linked to it from the page at the point you suggested.

https://ibmdocs-test.dcs.ibm.com/docs/en/SSAW57_liberty_test?topic=liberty-enabling-ssl-communication-in

Let me know if any further edits are needed- when you're satisfied with the updates you can sign off by adding the technical reviewed label to this issue. Thanks!

[una-tapa]

Hi, David

Thank you for the update. The troubleshooting addition looks great!

I also appreciate your finding the inconsistency in the transportSecurity page. I agree it is very confusing. Please help correct the page.

There was an unfortunate doc update in the past in this page. All of ssl-1.0 description was updated with transportSecurity-1.0 description by using replaceAll. Several customers opened support cases requesting to clarify. For some reason, the page could not be reverted back to the previous version. As a result, Alaine was going through the page to find which transportSecurity-1.0 needs to be changed back to ssl-1.0. The first Transport Security Feature needs to be Secure Socket Layer feature.

The following write-up in bold is the changes I would like to propose. It should be consistent with the rest of the page, and with the new paragraph in the troubleshooting page. Please improve the last sentence to fit the doc process.

[Proposal - example]
When the Secure Socket Layer is enabled, the SSL context for the process is the default SSL context of the Java Secure Socket Extension (JSSE). Therefore, the SSLContext.getDefault() method returns the default SSL context of the JSSE. However, when Transport Security feature is enabled, Open Liberty also sets a custom SSL socket factory. Therefore, the SSLSocketFactory.getDefault() method returns an SSL socket factory that is based on the Open Liberty custom socket factory provider, which uses the Open Liberty SSL context instead of the JSSE default. If Liberty is migrated from ssl-1.0 to transportSecurity-1.0, or from JavaEE to JakartaEE, please refer to the troubleshooting guide(link) for the required code change.

[dmuelle]

Thanks Hiroko- I see the source of the confusion now, but I'm still confused. :)

Per your suggestion in the previous comment:

When the Secure Socket Layer is enabled, the SSL context for the process is the default SSL context of the Java Secure Socket Extension (JSSE).

But the troubleshoting note says

When the Secure Sockets Layer (ssl-1.0) feature is enabled, you acquire the Liberty default SSLContext class by using the SSLContext.getDefault() method. However, when the Transport Security is enabled, the SSLContext.getDefault() method returns the Java Secure Socket Extension (JSSE) SSLContext class.

so - when you use SSLContext.getDefault(), which feature returns the Liberty default SSLContext, and which feature returns the JSSE SSLContext? I think the problem is that each feature has a different behavior for this method but Im confused about which is which.

[una-tapa]

Hi, @dmuelle

Thanks for pointing that there's still inconsistency. That's so true. My previous write up should have included another change
from
"When the Secure Socket Layer is enabled, the SSL context for the process is the default SSL context of the Java Secure Socket Extension (JSSE)."
to
"When the Security Socket Layer is enabled, the SSL context obtained by SSLContext.getDefault() is the default Liberty configuration"

The following is how I remember the difference:

ssl-1.0 is allowing only one SSL configuration in addition to LDAP SSL config.
Liberty creates its SSLContext, and overrides java's SSLContext by calling
SSLContext.setDefault()
then later, application can get Liberty's SSLContext by calling
SSLContext.getDefault()

transportSecurity-1.0 is introduced to handle multiple SSL configurations such as connection to WebService 1, 2, ...n, in addition to the LDAP SSL Connection.

The SSLConnection for Liberty's default SSL configuration is now JSSEHelper.getInstance().getSSLContext(null, null, null) ,
Others can be obtained by specifying certificate alias name or host & port, etc. (JSSEHelper.getInstance().getSSLContext(alias, connection, null) for example. In transpotSecurity-1.0, all the Liberty SSL connections are handled at SSLSocketFactory class that is different from ssl-1.0 using SSLContext class. As a result, SSLContext.getDefault() is left unchanged. It is returning JSSE's SSLContext.

It is great we have another pair of eyes to make sure all the confusion gets resolved. Hope I did better job this time.

Feature	Liberty's SSL Context	Java JSSE SSLContext
ssl-1.0	SSLContext.getDefault()	Liberty overrides SSLContext by setting its Context by calling SSLContext.setDefault()
transportSecurity-1.0	JSSEHelper.getInstance().getSSLContext(null,null,null)	SSLContext.getDefault()

[dmuelle]

Thanks for this information, I rewrote the information based on your recommendation, with a few tweaks

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/transportSecurity-1.0.html

Let me know if any further edits are needed. If not, you can sign off by adding the technical reviewed label to this issue and the update will publish with the 23.0.0.10 doc release. Thanks!

[una-tapa]

Hi, @dmuelle

Thank you so much David. "With a few treaks" part looks fantastic.