Stubby - Accessing HTTPS/SSL Web Services

This page discusses how to access a web service using HTTPS/SSL using Stubby, a Lotus Notes database that helps you create Apache Axis "stub" files that can be used to call web services from a Lotus Notes 7.x environment. If you need more information, please see the main page.

Currently, if you use Stubby to generate files to access a web service in Lotus Notes, and the endpoint is a secure connection with an https:// URL, you will get the following error:

java.lang.NullPointerException
    at lotus.domino.axis.AxisFault.makeFault(Unknown Source)
    at lotus.domino.axis.transport.http.HTTPSender.invoke(Unknown Source)
    ...

This is because the Apache Axis SocketFactory classes that handle SSL connections seem to have been excluded from the Axis package that was shipped with Lotus Notes/Domino 7.0. I can't find them anyway, and neither can my web service agents. So...

short version:
Here's how to make it work:

download AxisSSLFactory.zip from this amazing website ;-)
extract the files somewhere
read and understand the README.TXT file
copy the AxisSSLFactory.jar file to your local /notes/jvm/lib/ext folder
restart Lotus Notes/Domino on the machine you're on
add the following line to your code that is trying to make the HTTPS web service connection, before it attempts to make the connection:
```
System.setProperty("axis.socketSecureFactory",
    "com.nsftools.AxisSocketFactories.IBMFakeTrustSocketFactory");
```

This should allow you to properly make the connection and go on with your life.

long version:
It appears that IBM stripped all of the SSL functionality out of Axis when they packaged it up for Domino 7.0, so the HTTPS connection classes just aren't even there. This was probably a wise idea from a support standpoint -- just in case people like me tried to hack together web service clients like this -- because making "proper" SSL connections in Java requires creating keystores and importing certificates and other stuff that's a pain in the butt.

Anyway, the NullPointerException that was being thrown was actually telling you that there were no classes available to create an SSL socket -- although that wasn't obvious at all based on the error message. To fix that, I took the relevant HTTPS connection classes out of the Axis 1.1 distribution, made some modifications to make them work with Notes, and compiled them up into a JAR file.

To use them, just follow the instructions above.

I'm not really crazy about a solution that requires you to copy a file to the /notes/jvm/lib/ext directory, because it's not transparent, it requires intervention on client/server machines, and it requires a client or server restart, but that was the only way I could find to do it for now. The unusual way that Axis loads the SocketFactory classes seems to require that the class files are actually available on the local filesystem, not attached to an agent or script library.

last edited March 8, 2007