The SSL Transport

The SSL transport provides support for securing Ice connections using the SSL/TLS protocols. It is a built-in transport available with all supported language mappings and platforms.

The only exception is JavaScript which only supports WSS transport, the secure version of the WS (WebSocket) transport.

The SSL transport is built on top of each platform’s native SSL/TLS engine. This ensures interoperability with platform-provided features and that any security updates to the SSL/TLS engine also apply to your Ice applications.

Using the SSL Transport

To use the SSL transport, you must configure ssl endpoints for your client and server applications.

Clients use the SSL transport by specifying a ssl endpoint when creating a proxy:

GreeterPrx greeter(communicator, "greeter:ssl -h localhost -p 4061");

Servers enable the SSL transport by using a ssl endpoint for their object adapter:

auto adapter = communicator->createObjectAdapterWithEndpoints(
    "GreeterAdapter",
    "ssl -p 4061");

Both client and server must provide additional configuration to use the SSL transport. The configuration can be done using the SSL transport configuration properties, or programmatically using the platform specific APIs for the SSL transport.

At a minimum, you need to:

• Specify the server’s certificate and private key.

• Configure the trusted certificate authorities that the client uses to validate the server certificate.

Many additional options are available, but they are optional.

Configure the SSL Transport Using Properties

Sample server-side configuration showing how to set the server’s certificate and private key:

# The server's certificate file.
IceSSL.CertFile=server.p12
IceSSL.Password=password

# The name of the keychain in which to import the server's certificate,
# and the keychain password (macOS and iOS only).
IceSSL.Keychain=server.keychain
IceSSL.KeychainPassword=password

# Turn on security logging/tracing.
IceSSL.Trace.Security=1

Sample client-side configuration showing how to set the trusted root authorities for validating the server certificate:

# The trusted certificated authorities used to validate peer certaificates.
IceSSL.CAs=ca_cert.pem

For additional details refer to the IceSSL properties documentation.

Configure the SSL Transport Programmatically

The SSL transport configuration APIs provide access to more advanced features and to the underlying SSL engine.
Because they rely on platform-native APIs, you can only use them with C++, Java, and C#, which provide their own SSL transport implementations. These APIs are not available in language mappings that reuse the C++ SSL transport (such as Python, PHP, Ruby, MATLAB, and Swift). For those, you must rely on the SSL transport configuration properties described above.

In C++, three SSL transport implementations are available:

• OpenSSL (Linux)

• Secure Transport (macOS)

• Schannel (Windows)

C# uses the SSL engine provided by .NET, and Java uses the SSL engine provided by the JDK.

In all cases, these APIs allow you to configure the SSL transport:

• Per Object Adapter for incoming connections.

• Per Communicator for outgoing connections.

These APIs address the following needs:

• Provide certificates and keys programmatically.

• Support hot certificate reload.

• Support custom certificate validation.

• Allow advanced configuration of the platform SSL engine.

The Ice/secure demo provides a good starting point for using these APIs.

The SSL configuration for outgoing connections can be customized using the platform-specific client authentication options class:

• On Linux, use Ice::SSL::OpenSSLClientAuthenticationOptions.

• On macOS, use Ice::SSL::SecureTransportClientAuthenticationOptions.

• On Windows, use Ice::SSL::SchannelClientAuthenticationOptions.

Ice::SSL::ClientAuthentificationOptions is an alias that resolves to the platform-specific class and can be used in cross-platform code.

Client authentication options are set in the InitializationData used to create the communicator.

This SSL configuration applies to all SSL outgoing connections created by that communicator.

The SSL configuration for incoming connections can be customized using the platform-specific server authentication options class:

• On Linux, use Ice::SSL::OpenSSLServerAuthenticationOptions.

• On macOS, use Ice::SSL::SecureTransportServerAuthenticationOptions.

• On Windows, use Ice::SSL::SchannelServerAuthenticationOptions.

Ice::SSL::ServerAuthentificationOptions is an alias that resolves to the platform-specific class and can be used in cross-platform code.

Server authentication options are set when creating an object adapter, using the serverAuthenticationOptions parameter of createObjectAdapter, createObjectAdapterWithEndpoints.

This SSL configuration applies to all SSL incoming connections accepted by that object adapter.

Endpoint Security Considerations

You should avoid creating object adapters that include both secure and non-secure endpoints.
For example, having both TCP and SSL endpoints on the same object adapter defeats the purpose of using SSL, since clients could bypass the secure connection and access the adapter through the plain TCP endpoint.

For most applications that handle sensitive data or operate on untrusted networks (including the internet or intranets), the recommended practice is to use only secure endpoints.

Using SSL With Other Transports

You can see the SSL transport as using the SSL/TLS protocol on top of Ice TCP transport, but it is possible to use SSL/TLS on top of other transports.

Ice supports the following secure transports:

The configuration for the SSL/TLS protocol for these secure transports is the same as what was described above for the SSL transport.