Using XPI Inspector to troubleshoot HTTP SSL connections (Part 1 – Server Authentication)
Update 16 Feb 2016: Added additional step to restart channel to refresh the cached certificate. Added link to second part of the blog series on client authentication.
HTTPS (HTTP over SSL) connections are sometimes a bit tricky to establish. There have been quite a number of threads opened on SCN recently regarding SSL related errors. Below are some of the common errors that could occur when trying to establish an outbound SSL connection from PI.
|SOAP: Call failed: iaik.security.ssl.SSLCertificateException: Peer certificate rejected by ChainVerifier|
|SOAP: Call failed: iaik.security.ssl.SSLException: Peer sent alert: Alert Fatal: handshake failure|
|javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target|
SAP’s troubleshooting tool, XPI Inspector is one of the most useful tool to troubleshoot SSL connections. In this blog I will share an example of an SSL related error and how to utilize XPI Inspector to troubleshoot and resolve the issue.
XPI Inspector does not come pre-installed in the PI system. To install and use it, please refer to the following SAP Note:-
1514898 – XPI Inspector for troubleshooting XI
For more details about XPI Inspector, refer to the following blog:-
Michal’s PI tips: XPI inspector – help OSS and yourself
Step by Step Guide
In this example, we will use a SOAP receiver channel with an HTTPS target URL. For simplicity sake, we will use SCN as the target system (even though it is not a SOAP web server!).
Step 1 – Set up receiver channel
Populate SCN’s URL into the SOAP receiver channel’s setting. Ensure that the iFlow/ICO is configured correctly and activated.
Step 2 – Launch XPI Inspector and start test
XPI Inspector can be accessed from the following URL of the PI system
Select Example 11 for Authentication, SSL & PP. Populate the SSL Server URL and any proxy server if necessary.
Once everything is ready for testing, click the Start button and then trigger the scenario for the iFlow/ICO in step 1. Once the scenario is completed, click Stop.
Step 3 – Analyse the results
After XPI Inspector has gathered all the logs, it will present a results page. Under section Performed Checks > Verify Remote SSL Server Certificate, the SSL debug logs are shown.
In the example below, it shows that the chain verification failed because no trusted certificate was found.
In the Performed Checks > Is Remote SSL Server Certificate Trusted section, more details of the certificate and the chain are shown.
The analysis shows that none of the certificates has a CA (Certificate Authority) that is trusted. It means that there is no corresponding certificate for the CA in the TrustedCAs view in NWA’s keystore.
Step 4 – Retrieve the server’s Root CA certificate
In order to establish the SSL trust with the server, we need to retrieve the Root CA’s certificate and import it into NWA’s keystore.
First of all, we need to retrieve the certificate. This can be done by entering the HTTPS URL into a web browser and viewing the certificate details. The example shown below is using Google Chrome where we can view the certificate information by clicking on the padlock icon on the browser.
After the certificate is displayed, switch to the Certification Path tab, select the top most entry of the path as it represents the Root CA. Click View Certificate to view the CA’s certificate.
The Root CA certificate is displayed in another window and normally this is a self-signed certificate by the CA itself.
Switch to the Details tab and select Copy to File to save a version of the certificate on the local PC. It can be saved in the DER encoded binary X.509 format.
Alternatively, the certificates are also accessible via the hyperlinks on the XPI Inspector results page.
Step 5 – Import Root CA certificate into NWA’s keystore
Now that we have the Root CA, we can import it into the keystore in NWA. The keystore can be accessed in NWA> Configuration > Security > Certificates and Keys.
Specifically, we want to import the Root CA certificate into the TrustedCAs view of the keystore. Refer to the following article on importing the certificate. We will only be importing the X.509 certificate.
After completing the import, the Root CA certificate can be viewed as an entry in NWA.
Step 6 – Stop and restart receiver channel
Per SAP Note 1829329, the SOAP receiver channel caches the certificate upon channel start up. As such, it is recommended to stop the channel and restart it so that the channel’s cache is updated with the new certificate.
Step 7 – Repeat XPI Inspector test
Now that the Root CA certificate is in place, the XPI Inspector test can be repeated.
In the results page, we can see now that the trusted certificate is found and the chain verification is successful. Therefore the SSL handshake completes successfully.
Here is an additional example of an XPI Inspector debug log for another SSL issue. In this case, the SSL handshake failed but not because the chain verification failed. After the chain verification, the server requested the client to present the client’s certificate for authentication. However, the client sent an empty one causing the handshake to fail.
For this scenario, usage of client certificate for authentication is mandatory and therefore the resolution is to configure a valid client certificate to be used in the receiver channel.
For a thorough example on client authentication, check out the second part of this blog series – Using XPI Inspector to troubleshoot HTTP SSL connections (Part 2 – Client Authentication).
As shown, XPI Inspector is very useful to troubleshoot SSL related issues. As a matter of fact, I personally would use it at the beginning of a development that involves HTTPS connection before even designing or developing.
Hi Eng Swee,
Thanks for this blog.
can you please confirm that , is this same way troubleshooting for TLS connections?
actually recently i had to work on HMRC interfaces and they were moved from SSL to TLS connection. that time being SAP suggested to apply SAP notes in PI to establish connection, so before we go ahead with that SAP Notes i have tested TLS connection url which HMRC had given to us just for testing, unfortunately that connection seems working at least for me with out that sap notes, when i check channel monitoring i could see hand shake happened though response seems obtaining Octa-stream format. so again an doubt raised on my mind whether that connection is working or not.
also i will check same way you explained above once you confirms 🙂
anyway i am on positive way because at least i am getting something response from that server 🙂
this blog explained mostly server certificate authentication(one way authentication) correct me if i am wrong..can i ask you to prepare an blog for client certificate authentication (how can we handle that cases like what type of signing is required for and key and default values how we will maintain in channel--)
Thanks for your comment.
SSL is the predecessor of TLS and these days actually TLS is more commonly used although it is still referred to by the old SSL name. Refer to the Wiki entry below.
From the debug log provided, you can see that PI is sending request for SSL version 3.1 which apparently is also sometimes considered TLS 1.0.
I think as long as the target server is willing to accept the SSL version from PI, it should be okay.
Yes, the example on this blog is based on server authentication which is more widely encountered. The example is just to showcase how to use the feature in XPI Inspector. The principles for troubleshooting can be similarly applied for client certificate authentication, which I added a little at the last section.
Right now I don't have access to a server to test more on client authentication. When I do I'll try to write more on that.
Like always a great blog Eng!,
The last week i've just had a problem with a SOAP SSL the last week. The problem was two certificates on the endpoint and the chainverifer in PI throwed a exception. With your debug example i think it had been easier to catch the issue. Thanks for sharing!
Thanks for the kind comment, Inaki.
Glad to know that this would be useful. Hopefully others would benefit from it too as HTTPS connectivity is quite a common requirement these days.
Great post. SSL have always been a bit dificult to figure out if there was anything missing.
This is really help and when i found the issue i followed this and established connection.
In case somebody stumbles upon this after all the years and struggles with a TLS/SSL handshake error using the REST adapter of PO: Try setting this module parameter (REST adapter module):
It changes the used SSL library internally and might be necessary for certain situations.
PS: By the way, triggering the scenario is not needed (at least nowadays) (part of step 2). XPI inspector tries to establish a connection as soon as you click Start. Just click start and after a few seconds Stop again, and you'll see the correct results.