Table of Contents Previous Next
Logo
IceSSL : 41.3 Using IceSSL
Copyright © 2003-2010 ZeroC, Inc.

41.3 Using IceSSL

Incorporating IceSSL into your application requires installing the plug‑in, config­uring it according to your security requirements, and creating SSL endpoints.

41.3.1 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 (see Appendix D) provides language-specific informa­tion 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 last component of the property name (IceSSL) becomes the plug‑in’s offi­cial identifier for configuration purposes, but the IceSSL plug‑in requires its iden­tifier 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 direc­tory that appears in the shared library path (LD_LIBRARY_PATH on most Unix platforms, PATH on Windows).
Additional configuration properties are usually necessary as well; see Section 41.4.1 for more information.

Java Applications

The format for the Ice.Plugin property is shown below:
Ice.Plugin.IceSSL=IceSSL.PluginFactory
The last component of the property name (IceSSL) becomes the plug‑in’s offi­cial identifier for configuration purposes, but the IceSSL plug‑in requires its iden­tifier to be IceSSL. The property value IceSSL.PluginFactory is the name of a class that allows the Ice run time to initialize the plug‑in. The IceSSL classes are included in Ice.jar, therefore no additional changes to your CLASSPATH are necessary.
Additional configuration properties are usually necessary as well; see Section 41.4.2 for more information.

.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 offi­cial identifier for configuration purposes, but the IceSSL plug‑in requires its iden­tifier 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. As described in Appendix D, you may also specify the full assembly name instead of the file name in an Ice.Plugin property.
Additional configuration properties are usually necessary as well; see Section 41.4.3 for more information.

Ice Touch Applications

The IceSSL plug‑in is included in the Ice Touch run time and installed automati­cally, therefore it is not necessary to explicitly load it. See Section 41.4.4 for more information on configuring IceSSL in Ice Touch applications.

41.3.2 Creating SSL Endpoints

Installing the IceSSL plug‑in enables you to use a new protocol, ssl, in your endpoints. For example, the following 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 its own 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 stringified proxies is equally straightforward:
MyProxy=MyObject:tcp ‑p 4063:ssl ‑p 4064:udp ‑p 4063
For more information on proxies and endpoints, see Appendix E.

41.3.3 Security Considerations

Defining an object adapter’s endpoints to use multiple protocols, as shown in the example in Section 41.3.2, 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. Figure 41.1 illustrates an environment in which TCP endpoints are allowed behind the firewall, but external clients are required to use SSL.
Figure 41.1. An application of multiple protocol endpoints.
The firewall in Figure 41.1 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, see Chapter 42.

Table of Contents Previous Next
Logo