This page describes some general configuration topics:
You can find platform-specific instructions for configuring IceSSL on the following pages:
- Configuring IceSSL for OpenSSL - For Linux applications; also for Windows applications that use OpenSSL instead of the default Schannel
- Configuring IceSSL for Schannel - For Windows and UWP applications in C++, .NET
- Configuring IceSSL for Secure Transport - For macOS and iOS applications
- Configuring IceSSL for Java
Configuring Ciphersuites
A ciphersuite represents a particular combination of encryption, authentication and hashing algorithms. You can configure the ciphersuites that the underlying SSL engines are allowed to negotiate during handshaking with a peer. By default, IceSSL uses the underlying engine's default ciphersuites, but you can define a property to customize 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.
Refer to the platform notes in the IceSSL.Ciphers property description for the details about your platform.
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 SSL 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.
Verification Depth
In order to authenticate a peer, SSL obtains the peer's certificate chain, which includes the peer's certificate as well as that of the root CA. SSL 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.
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.
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.