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
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_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 limiting ciphersuites by setting
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.
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.
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:
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:
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.
IceSSL.TrustOnly properties do not provide the selectivity you require, the next step is to install a custom certificate verifier.
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.
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:
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
If you want the default behavior of proxies to give precedence to secure endpoints, you can set this property instead:
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.
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.