Portfolio Manager will support TLS V1.0 through March 30th, 2019. On March 31, 2019, Portfolio Manager web services will discontinue support for TLSv1.0 in both the LIVE and TEST environments.
Why?
In order to provide a secure data transfer environment under the PCI Data Security Standard (PCI DSS), TLSv1.0 will no longer be supported in Portfolio Manager web services. As a result, all web servers and clients must transition to TLS 1.1 or above.
What do you need to do?
Portfolio Manager web services will end support for TLSv1.0 on March 31, 2019. Web service requests using TLSv1.0 will no longer be accepted starting on that date. API users are therefore strongly encouraged to configure their servers/implementations to support TLS 1.1 or above well before March 31, 2019.
To help you verify that your implementation is not using TLSv1.0, we have setup a temporary subdomain for the LIVE and TEST environments that does not accept TLSv1.0 traffic. The verification subdomain can be accessed as follows:
- LIVE environment --> https://validtls-portfoliomanager.energystar.gov/ws
- Example: To add a property to account 1234 in the LIVE environment, you can POST to the URL of https://validtls-portfoliomanager.energystar.gov/ws/account/1234/property.
- TEST environment --> https://validtls-portfoliomanager.energystar.gov/wstest
- Example: To add a property to account 1234 in the TEST environment, you can POST to the URL of https://validtls-portfoliomanager.energystar.gov/wstest/account/1234/property.
After you verify that your implementation does not use TLSv1.0, we suggest that you immediately point back to the subdomain of portfoliomanager.energystar.gov since it already supports TLSv1.1 and TLSv1.2.
*** Please note that any requests sent to the URLs above are still run against the LIVE and TEST environments. For example, if you add a property using "https://validtls-portfoliomanager.energystar.gov/ws" then you are adding that property into the LIVE environment. In other words, it's equivalent to using "https://portfoliomanager.energystar.gov/ws". See graphic below. ***
How can I tell if I am still using TLSv1.0?
When referencing the temporary subdomain of validtls-portfoliomanager.energystar.gov using TLSv1.0, you should receive an error that indicates your connection was refused. It will not be an XML-structured response that the Portfolio Manager APIs typically return. The error message depends on what programming language/libraries you are using, and the level of detail will vary. For example, if you are using Java then you may encounter the following stack trace
- [SEVERE] Connection reset
- Exception in thread "main" java.lang.RuntimeException: java.net.SocketException: Connection reset
- at Test.main(Test.java:67)
- Caused by: java.net.SocketException: Connection reset
- at java.net.SocketInputStream.read(SocketInputStream.java:196)
- at java.net.SocketInputStream.read(SocketInputStream.java:122)
- at sun.security.ssl.InputRecord.readFully(InputRecord.java:442)
- at sun.security.ssl.InputRecord.read(InputRecord.java:480)
- at sun.security.ssl.SSLSocketImpl.readRecord(SSLSocketImpl.java:934)
- at sun.security.ssl.SSLSocketImpl.performInitialHandshake(SSLSocketImpl.java:1332)
- at sun.security.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:1359)
- at sun.security.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:1343)
- at sun.net.www.protocol.https.HttpsClient.afterConnect(HttpsClient.java:559)
- at sun.net.www.protocol.https.AbstractDelegateHttpsURLConnection.connect(AbstractDelegateHttpsURLConnection.java:185)
- at sun.net.www.protocol.http.HttpURLConnection.getInputStream(HttpURLConnection.java:1301)
- at sun.net.www.protocol.https.HttpsURLConnectionImpl.getInputStream(HttpsURLConnectionImpl.java:254)
How can I tell if I am not using TLSv1.0 anymore?
When referencing the temporary subdomain of validtls-portfoliomanager.energystar.gov without using TLSv1.0, you should receive normal XML responses that are typically returned back from the Portfolio Manager web service APIs. If you get to this point, it is safe to say that you are not using TLSv1.0 anymore. It is also important to note that you should immediately re-point back to the subdomain of portfoliomanager.energystar.gov as validtls-portfoliomanager.energystar.gov will eventually be removed.
Using Java?
If your application runs on Java 1.6 prior to update 111, or earlier, TLS 1.1 and 1.2 are not supported. Therefore, you need to update the version of Java your application runs on. If you use another library for connections such as Apache HttpClient, you should consult the documentation to enable TLS 1.2.
Using .NET 4.0?
.Net 4.0 does not currently support TLS 1.1 and above. If you are using .NET 4.0, consider:
1) Upgrading to a more recent version of .NET
2) Keeping your current .NET implementation and setup but implementing a reverse proxy or non-transparent forward proxy. This proxy would sit in between your application and Portfolio Manager and would basically start a new TLS connection to Portfolio Manager. You can use nginx as this proxy and use the following SAMPLE nginx config which would basically forward all requests received on whatever internal hostname they decide to run to Portfolio Manager.
After verifying that "validtls-portfoliomanager.energystar.gov" accepts your TLS traffic, you can change the config back to "portfoliomanager.energystar.gov".
Still need help or have questions?
If you have questions, please submit them here .