Configuring IceSSL

This page describes some general configuration topics:

You can find platform-specific instructions for configuring IceSSL on the following pages:

Security Considerations for Protocols and Ciphersuites

You can configure the protocols and ciphersuites that the underlying TLS engines are allowed to negotiate during handshaking with a peer. By default, IceSSL uses the TLS1_0, TLS1_1, TLS1_2, and TLS1_3 (when available) protocols along with the underlying engine's default ciphersuites. You can define a property to customize the both the protocols and the ciphersuite list. Normally the default configuration is chosen to eliminate relatively insecure ciphersuites such as ADH. In general, we recommend setting IceSSL.Trace.Security=1 when experimenting with ciphersuite configurations. When executing your program, pay special attention to the log output to verify the ciphersuites that IceSSL has enabled, as well as the protocol and ciphersuite negotiated for each connection.

We recommend setting IceSSL.Protocols and IceSSL.ProtocolVersionMin (SecureTransport engine only) to the latest TLS version supported by the underlying engine — preferably TLS1_2 or TLS1_3. 

We recommend limiting ciphersuites by setting IceSSL.Ciphers. 

By limiting the possible protocols and ciphersuites, you're establishing a security policy that it's preferable for a connection attempt to fail if the remote peer does not support a compatible match.

Back to Top ^

Configuring Trust Relationships

Declaring that you trust a certificate authority implies that you trust any peer whose certificate was signed directly or indirectly by that certificate authority. It is necessary to use this broad definition of trust in some applications, such as a public Web server. In more controlled environments, it is a good idea to restrict access as much as possible, and IceSSL provides a number of ways for you to do that.

Trusted Peers

After the low-level TLS engine has completed its authentication process, IceSSL can be configured to take additional steps to verify whether a peer should be trusted. The IceSSL.TrustOnly family of properties defines a collection of acceptance and rejection filters that IceSSL applies to the distinguished name of a peer's certificate in order to determine whether to allow the connection to proceed. IceSSL permits the connection if the peer's distinguished name matches any of the acceptance filters and does not match any of the rejection filters.

A distinguished name uniquely identifies a person or entity and is generally represented in the following textual form:

C=US, ST=Florida, L=Palm Beach Gardens, O="ZeroC, Inc.", OU=Servers, CN=Quote Server

Suppose we are configuring a client to communicate with the server whose distinguished name is shown above. If we know that the client is allowed to communicate only with this server, we can enforce this rule using the following property:

IceSSL.TrustOnly=O="ZeroC, Inc.", OU=Servers, CN=Quote Server

With this property in place, IceSSL allows a connection to proceed only if the distinguished name in the server's certificate matches this filter. The property may contain multiple filters, separated by semicolons, if the client needs to communicate with more than one server. Additional variations of the property are also supported.

If the IceSSL.TrustOnly properties do not provide the selectivity you require, the next step is to install a custom certificate verifier.

Back to Top ^

Verification Depth

In order to authenticate a peer, TLS obtains the peer's certificate chain, which includes the peer's certificate as well as that of the root CA. TLS verifies that each certificate in the chain is valid, but there still remains a subtle security risk. Suppose that we have identified a trusted root CA (via its certificate), and a peer has supplied a valid certificate chain signed by our trusted root CA. It is possible for an attacker to obtain a special signing certificate that is signed by our root CA and therefore trusted implicitly. The attacker can use this certificate to sign fraudulent certificates with the goal of masquerading as a trusted peer, presumably for some nefarious purpose.

We could use the IceSSL.TrustOnly properties described above in an attempt to defend against such an attack. However, the attacker could easily manufacture a certificate containing a distinguished name that satisfies the trust properties.

If you know that all trusted peers present certificate chains of a certain length, set the property IceSSL.VerifyDepthMax so that IceSSL automatically rejects longer chains. The default value of this property is three, therefore you may need to set it to a larger value if you expect peers to present longer chains.

In situations where you cannot make assumptions about the length of a peer's certificate chain, yet you still want to examine the chain before allowing the connection, you should install a custom certificate verifier.

Back to Top ^

Configuring Secure Proxies

Proxies may contain any combination of secure and insecure endpoints. An application that requires secure communication can guarantee that proxies it manufactures itself, such as those created by calling stringToProxy, contain only secure endpoints. However, the application cannot make the same assumption about proxies received as the result of a remote invocation.

The simplest way to guarantee that all proxies use only secure endpoints is to define the Ice.Override.Secure configuration property:

Ice.Override.Secure=1

Setting this property is equivalent to invoking the proxy method ice_secure(true) on every proxy. When enabled, attempting to establish a connection using a proxy that does not contain a secure endpoint results in NoEndpointException.

If you want the default behavior of proxies to give precedence to secure endpoints, you can set this property instead:

Ice.Default.PreferSecure=1

Note that proxies may still attempt to establish connections to insecure endpoints, but they try all secure endpoints first. This is equivalent to invoking ice_preferSecure(true) on a proxy.

Back to Top ^

IceSSL Diagnostics

You can use two configuration properties to obtain more information about the plug-in's activities. Setting IceSSL.Trace.Security=1 enables the plug-in's diagnostic output, which includes a variety of messages regarding events such as ciphersuite selection, peer verification and trust evaluation. The other property, Ice.Trace.Network, determines how much information is logged about network events such as connections and packets. Note that the output generated by Ice.Trace.Network also includes other transports such as TCP and UDP. Additional platform-specific logging information may also be available. Refer to the appropriate Configuring IceSSL page for your platform for more details.

Back to Top ^

See Also