Incorporating IceSSL into your application requires installing the plug-in, configuring it according to your security requirements, and creating SSL endpoints.
On this page:
Installing IceSSL
Ice supports a generic plug-in facility that allows extensions (such as IceSSL) to be installed dynamically without changing the application source code. The Ice.Plugin property provides language-specific information that enables the Ice run time to install a plug-in.
C++ Applications
The executable code for the IceSSL C++ plug-in resides in a shared library on Unix and a dynamic link library (DLL) on Windows. The format for the Ice.Plugin property is shown below:
Ice.Plugin.IceSSL=IceSSL:createIceSSL
The C++ configuration is the same for the C++11 mapping and the C++98 mapping: Ice computes the name of the shared library to load and adds automatically a "++11" suffix when needed.
The last component of the property name (IceSSL) becomes the plug-in's official identifier for configuration purposes, but the IceSSL plug-in requires its identifier to be IceSSL. The property value IceSSL:createIceSSL is sufficient to allow the Ice run time to locate the IceSSL library (on both Unix and Windows) and initialize the plug-in. The only requirement is that the library reside in a directory that appears in the shared library path (LD_LIBRARY_PATH on most Unix platforms, PATH on Windows).
Instead of dynamically loading the plug-in at runtime your application can also explicitly link with and register the plug-in. To register the plug-in, you must call the Ice::registerIceSSL(bool loadOnInitialize = true) function before the communicator initialization. The loadOnInitialize parameter specifies if the plug-in is installed when the communicator is initialized. If set to false, you will need to enable the plugin by setting the Ice.Plugin.IceSSL property to 1.
Additional configuration properties are usually necessary as well.
Ice::registerIceSSL is a simple helper function that calls Ice::registerPluginFactory.
iOS and UWP applications
iOS and UWP applications are using static linking and can't load at runtime the IceSSL plug-in. Instead, they need to link with the IceSSL library and register the plug-in with the Ice::registerIceSSL(bool loadOnInitialize = true) function. See Using Plugins with Static Libraries.
OpenSSL on Windows
Ice provides two implementations of IceSSL on Windows, a default implementation that relies on SChannel and a secondary implementation that relies on OpenSSL. To install IceSSL for OpenSSL on Windows, set Ice.Plugin.IceSSL as shown below:
Ice.Plugin.IceSSL=IceSSLOpenSSL:createIceSSLOpenSSL
The plug-in name remains IceSSL, and you can only install one IceSSL with a given communicator. You can however create multiple communicators in the same application, each configured with a different IceSSL plugin.
IceSSL for OpenSSL is not included in the Ice binary distributions for Windows. You need to build Ice C++ from sources to get this IceSSL plug-in.
Java Applications
The format for the Ice.Plugin property is shown below:
Ice.Plugin.IceSSL=IceSSL:com.zeroc.IceSSL.PluginFactory
Ice.Plugin.IceSSL=IceSSL.PluginFactory
The IceSSL classes are included in ice.jar, therefore no other changes to your CLASSPATH are necessary.
The last component of the property name (IceSSL) becomes the plug-in's official identifier for configuration purposes, but the IceSSL plug-in requires its identifier to be IceSSL. The property value is the name of a class that allows the Ice run time to initialize the plug-in.
Additional configuration properties are usually necessary as well.
JavaScript applications
SSL is not supported with JavaScript.
.NET Applications
The format for the Ice.Plugin property is shown below:
Ice.Plugin.IceSSL=C:/Ice/bin/IceSSL.dll:IceSSL.PluginFactory
The last component of the property name (IceSSL) becomes the plug-in's official identifier for configuration purposes, but the IceSSL plug-in requires its identifier to be IceSSL. The property value contains the file name of the IceSSL assembly as well as the name of a class, IceSSL.PluginFactory, that allows the Ice run time to initialize the plug-in.
You may also specify a partially or fully qualified assembly name instead of the file name in an Ice.Plugin property. For example, you can use the following configuration to load the plug-in from the release version of the assembly provided in ZeroC's binary distribution:
Ice.Plugin.IceSSL=IceSSL,Version=3.7.0.0,Culture=neutral,PublicKeyToken=cdd571ade22f2f16:IceSSL.PluginFactory
Alternatively, if you have built the Ice source code yourself, you can load the development version of the assembly as shown below:
Ice.Plugin.IceSSL=IceSSL,Version=3.7.0.0,Culture=neutral,PublicKeyToken=1f998c50fec78381:IceSSL.PluginFactory
You must use a fully qualified assembly name to load the IceSSL plug-in from the Global Assembly Cache.
Additional configuration properties are usually necessary as well.
Objective-C applications
Objective-C applications use the IceSSL C++ plug-in so the configuration is the same as the C++ configuration described above.
If instead of dynamically loading the plug-in at runtime your application prefers to link with the library, it needs to register the plug-in with the ICEregisterIceSSL(BOOL loadOnInitialize) function. The loadOnInitialize parameter specifies if the plug-in is installed when the communicator is initialized. If set to NO, you will need to enable the plugin by setting the Ice.Plugin.IceSSL property to 1.
iOS applications
iOS applications are using static linking and can't load at runtime the IceSSL plug-in. Instead, they need to link with the IceSSL library and register the plug-in with the ICEregisterIceSSL(BOOL loadOnInitialize) function. See Using Plugins with Static Libraries.
PHP applications
You should use the same configuration as the C++ configuration described above to install the IceSSL plugin.
Python applications
When using the PyPI package, the IceSSL plugin is automatically installed when the Ice runtime is loaded from the Python module, no additional configuration is required. If you are not using the PyPI package but a build provided with system packages such as RPM or DEB, you should use the same configuration as the C++ configuration described above to install the IceSSL plugin.
Ruby applications
When using the GEM package, the IceSSL plugin is automatically installed when the Ice runtime is loaded from the Ruby module, no additional configuration is required. If you are not using the GEM package but a build provided with system packages such as RPM or DEB, you should use the same configuration as the C++ configuration described above to install the IceSSL plugin.
Creating SSL Endpoints
Installing the IceSSL plug-in enables you to use a new protocol, ssl, in your endpoints. For example, the following adapter endpoint list creates a TCP endpoint, an SSL endpoint, and a UDP endpoint:
MyAdapter.Endpoints=tcp -p 4063:ssl -p 4064:udp -p 4063
As this example demonstrates, it is possible for a UDP endpoint to use the same port number as a TCP or SSL endpoint, because UDP is a different protocol and therefore has an indepdendent set of ports. It is not possible for a TCP endpoint and an SSL endpoint to use the same port number, because SSL is essentially a layer over TCP.
Using SSL in proxy endpoints is equally straightforward:
MyProxy=MyObject:tcp -p 4063:ssl -p 4064:udp -p 4063
Endpoint Security Considerations
Defining an object adapter's endpoints to use multiple protocols, as shown above, has obvious security implications. If your intent is to use SSL to protect session traffic and/or restrict access to the server, then you should only define SSL endpoints.
There can be situations, however, in which insecure endpoint protocols are advantageous. The figure below illustrates an environment in which TCP endpoints are allowed behind the firewall, but external clients are required to use SSL:
An application of multiple protocol endpoints.
The firewall in the illustration is configured to block external access to TCP port 4063 and to forward connections to port 4064 to the server machine.
One reason for using TCP behind the firewall is that it is more efficient than SSL and requires less administrative work. Of course, this scenario assumes that internal clients can be trusted, which is not true in many environments.
For more information on using SSL in complex network architectures, refer to our discussion of the Glacier2 router.