IceSSL.*

IceSSL Property Overview

The IceSSL implementations for our supported platforms use many of the same configuration properties. However, there are some properties that are specific to certain platforms or languages. For properties with such limitations, we list the supported platforms or underlying SSL libraries in the synopsis and provide additional platform-specific notes if necessary. You'll see the following platforms, languages and SSL libraries listed in the property reference:

• SChannel (C++ on Windows)

• SecureTransport (C++ on macOS and iOS)

• OpenSSL (C++ on Linux or Windows)

• Java

• .NET

A property is supported by all platforms if no limitations are mentioned.

Finally, note that Ice for Swift and the Ice extensions for Python, Ruby and PHP use IceSSL for C++, therefore they use the IceSSL properties for SChannel, SecureTransport or OpenSSL as appropriate for the target platform.

JavaScript

These IceSSL properties have no effect on JavaScript.

IceSSL.Alias

Synopsis

IceSSL.Alias=alias (Java)

Description

Selects a particular certificate from the key store specified by IceSSL.Keystore. The certificate identified by alias is presented to the peer request during authentication.

IceSSL.CheckCertName

Synopsis

IceSSL.CheckCertName=num

Description

Specifies if certificate host name verification is enabled. The legal values are shown in the table below. If this property is not defined, the default value is 0.

This property has no effect on a server's validation of a client's certificate.

If the host name verification is performed and fails, IceSSL aborts the connection attempt and raises an exception.

The verification ensures the host name matches the certificate's subject alternative names or the subject's CommonName if no subject alternative names are provided. Note the following difference in behavior for this check depending on the platform or language:

• if the endpoint uses an IP address: the SecureTransport, and Java implementations only match the IP against the subject alternative names, they don't check the CommonName

• if the endpoint uses a DNS name: SecureTransport on macOS only matches the DNS name against the subject alternative names, it doesn't check the CommonName

IceSSL.DefaultDir

Synopsis

IceSSL.DefaultDir=path

Description

Specifies the default directory in which to look for certificates, key stores, and other files. See the descriptions of the relevant properties for more information.

IceSSL.Keystore

Synopsis

IceSSL.Keystore=file (Java)

Description

Specifies a key store file containing certificates and their private keys. If the key store contains multiple certificates, you should specify a particular one to use for authentication using IceSSL.Alias. IceSSL first attempts to open file as a class loader resource and then as a regular file. If the given path is relative but does not exist, IceSSL also attempts to locate it relative to the default directory defined by IceSSL.DefaultDir. The format of the file is determined by IceSSL.KeystoreType.

If this property is not defined, the application will not be able to supply a certificate during SSL handshaking. As a result, the application may not be able to negotiate a secure connection.

IceSSL.KeystorePassword

Synopsis

IceSSL.KeystorePassword=password (Java)

Description

Specifies the password used to load the key store defined by IceSSL.Keystore. Depending on the key store type and security provider, this password can be used to verify the store's integrity and to decrypt its contents, including certificates and certificate chains.

This property is distinct from IceSSL.Password, which Ice uses to recover private keys. One property does not default to the other.

If this property is not defined, the value of IceSSL.KeystoreType determines the password Ice passes to KeyStore.load: the empty string for PKCS12 and BKS in upper case, and null for any other value, including the OpenJDK default pkcs12. See IceSSL.KeystoreType for what each password means.

If IceSSL.Keystore and IceSSL.Truststore have the same value, Ice uses IceSSL.KeystorePassword to load the shared store; IceSSL.TruststorePassword is not used.

IceSSL.KeystoreType

Synopsis

IceSSL.KeystoreType=type (Java)

Description

Specifies the type of the key store file defined by IceSSL.Keystore. Ice passes this value unchanged to KeyStore.getInstance(String), so it must name a key store type supplied by an installed security provider, such as PKCS12, JKS, or BKS on Android.

KeyStore.getInstance matches type names case-insensitively: PKCS12 and pkcs12 select the same implementation.

If this property is not defined, Ice uses KeyStore.getDefaultType(), which returns the value of the Java security property keystore.type:

• OpenJDK-based runtimes have configured keystore.type=pkcs12 since Java 9. OpenJDK's PKCS12 implementation also reads JKS files, thanks to the keystore.type.compat security property, which is enabled by default. On such a runtime, you can leave this property unset for a JKS file and for a PKCS12 file loaded with IceSSL.KeystorePassword.

• Android configures keystore.type=BKS.

Store type and store password

When IceSSL.KeystorePassword is not defined, the key store type determines the password Ice passes to KeyStore.load:

An omitted type is therefore pkcs12 on an OpenJDK-based runtime, which takes the null path, and BKS on Android, which takes the empty-string path. Since an empty IceSSL.KeystorePassword means “not defined,” the type spelling is the only way to make Ice pass the empty string.

A null password and an empty password mean different things to KeyStore.load.

With null, the provider skips the integrity check and reads only what it can read without a password. For OpenJDK's PKCS12 provider, that leaves out the certificates, which a PKCS12 store encrypts with the store password: the key entries load without their certificate chains. A JKS store uses the store password only for its integrity check, so null loads everything.

The empty string is a password like any other. It opens an empty-password PKCS12 store—that is, a store created with the empty string as its password. Such a store is the usual way to ship a PKCS12 file that needs no secret, such as a trust store containing public CA certificates. For example:

openssl pkcs12 -export -passout pass:

On an OpenJDK-based runtime, an empty-password PKCS12 store therefore loads only with:

IceSSL.KeystoreType=PKCS12

The value PKCS12 must be uppercase.

After loading the key store, Ice checks that the selected key entry has a certificate chain. If it does not, communicator initialization fails with an InitializationException that points to IceSSL.KeystorePassword and, for an empty-password PKCS12 store, to:

IceSSL.KeystoreType=PKCS12

If IceSSL.Keystore and IceSSL.Truststore have the same value, Ice loads the file once using IceSSL.KeystoreType and IceSSL.KeystorePassword. In this case, IceSSL.TruststoreType and IceSSL.TruststorePassword are not used.

IceSSL.Password

Synopsis

IceSSL.Password=password

Description

Specifies the password necessary to decrypt the private key.

It is a security risk to use a plain-text password in a configuration file.

Platform Notes

SChannel, SecureTransport, OpenSSL

This property supplies the password that was used to secure the private key contained in the file defined by IceSSL.CertFile.

Java

This property supplies the password that was used to secure the private key contained in the key store defined by IceSSL.Keystore. All of the keys in the key store must use the same password.

.NET

This property supplies the password that was used to secure the file defined by IceSSL.CertFile.

iOS

This property supplies the password that was used to secure the file defined by IceSSL.CertFile.

IceSSL.Trace.Security

Synopsis

IceSSL.Trace.Security=num

Description

The SSL plug-in trace level:

IceSSL.TrustOnly

Synopsis

IceSSL.TrustOnly=ENTRY[;ENTRY;...]

Description

Identifies trusted and untrusted peers. This family of properties provides an additional level of authentication by using the peer certificate's distinguished name (DN) to decide whether to accept or reject a connection.

Each ENTRY in the property value consists of relative distinguished name (RDN) components, formatted according to the rules in RFC 2253. Specifically, the components must be separated by commas, and any component that contains a comma must be escaped or enclosed in quotes. For example, the following two property definitions are equivalent:

IceSSL.TrustOnly=O="Acme, Inc.",OU=Sales
IceSSL.TrustOnly=O=Acme\, Inc.,OU="Sales"

Use a semicolon to separate multiple entries in a property:

IceSSL.TrustOnly=O=Acme\, Inc.,OU=Sales;O=Acme\, Inc.,OU=Marketing

By default, each entry represents an acceptance entry. A ! character appearing at the beginning of an entry signifies a rejection entry. The order of the entries in a property is not important.

After the SSL engine has successfully completed its authentication process, IceSSL evaluates the relevant IceSSL.TrustOnly properties in an attempt to find an entry that matches the peer certificate's DN. For a match to be successful, the peer DN must contain an exact match for all of the RDN components in an entry. An entry may contain as many RDN components as you wish, depending on how narrowly you need to restrict access. The order of the RDN components in an entry is not important.

The connection semantics are described below:

1. IceSSL aborts the connection if any rejection or acceptance entries are defined and the peer does not supply a certificate.

2. IceSSL aborts the connection if the peer DN matches any rejection entry. (This is true even if the peer DN also matches an acceptance entry.)

3. IceSSL accepts the connection if the peer DN matches any acceptance entry, or if no acceptance entries are defined.

Our original example limits access to people in the sales and marketing departments:

IceSSL.TrustOnly=O=Acme\, Inc.,OU=Sales;O=Acme\, Inc.,OU=Marketing

If it later becomes necessary to deny access to certain individuals in these departments, you can add a rejection entry and restart the program:

IceSSL.TrustOnly=O=Acme\, Inc.,OU=Sales; O=Acme\, Inc.,OU=Marketing; !O=Acme\, Inc.,CN=John Smith

While testing your trust configuration, you may find it helpful to set the IceSSL.Trace.Security property to a non-zero value, which causes IceSSL to display the DN of each peer during connection establishment.

This property affects incoming and outgoing connections. IceSSL also supports similar properties that affect only incoming connections or only outgoing connections.

IceSSL.TrustOnly.Client

Synopsis

IceSSL.TrustOnly.Client=ENTRY[;ENTRY;...]

Description

Identifies trusted and untrusted peers for outgoing (client) connections. The entries defined in this property are combined with those of IceSSL.TrustOnly.

IceSSL.TrustOnly.Server

Synopsis

IceSSL.TrustOnly.Server=ENTRY[;ENTRY;...]

Description

Identifies trusted and untrusted peers for incoming ("server") connections. The entries defined in this property are combined with those of IceSSL.TrustOnly. To configure trusted and untrusted peers for a particular object adapter, use IceSSL.TrustOnly.Server.AdapterName.

IceSSL.TrustOnly.Server.AdapterName

Synopsis

IceSSL.TrustOnly.Server.AdapterName=ENTRY[;ENTRY;...]

Description

Identifies trusted and untrusted peers for incoming (server) connections to the object adapter AdapterName. The entries defined in this property are combined with those of IceSSL.TrustOnly and IceSSL.TrustOnly.Server.

IceSSL.Truststore

Synopsis

IceSSL.Truststore=file (Java)

Description

Specifies a key store file containing the certificates of trusted certificate authorities. IceSSL first attempts to open file as a class loader resource and then as a regular file. If the given path is relative but does not exist, IceSSL also attempts to locate it relative to the default directory defined by IceSSL.DefaultDir. The format of the file is determined by IceSSL.TruststoreType.

If no truststore is specified the application will not be able to authenticate the peer's certificate during SSL handshaking. As a result, the application may not be able to negotiate a secure connection.

IceSSL.TruststorePassword

Synopsis

IceSSL.TruststorePassword=password (Java)

Description

Specifies the password used to load the trust store defined by IceSSL.Truststore. Depending on the key store type and security provider, this password can be used to verify the store's integrity and decrypt its contents, including trusted CA certificates.

If this property is not defined, the value of IceSSL.TruststoreType determines the password Ice passes to KeyStore.load:

• The empty string for PKCS12 and BKS in uppercase.

• null for any other value, including the OpenJDK default, pkcs12.

See IceSSL.KeystoreType for an explanation of what each password means.

If IceSSL.Truststore and IceSSL.Keystore have the same value, Ice loads the shared store using IceSSL.KeystorePassword; IceSSL.TruststorePassword is not used.

IceSSL.TruststoreType

Synopsis

IceSSL.TruststoreType=type (Java)

Description

Specifies the type of the trust store file defined by IceSSL.Truststore. Ice passes this value unchanged to KeyStore.getInstance(String), so it must name a key store type supplied by an installed security provider, such as PKCS12, JKS, or BKS on Android.

KeyStore.getInstance matches type names case-insensitively: PKCS12 and pkcs12 select the same implementation.

If this property is not defined, Ice uses KeyStore.getDefaultType(), as described under IceSSL.KeystoreType.

Store type and store password

When IceSSL.TruststorePassword is not defined, the trust store type determines the password Ice passes to KeyStore.load:

• The empty string for PKCS12 or BKS in uppercase.

• null for any other value.

See IceSSL.KeystoreType for an explanation of what each password means.

An empty-password PKCS12 trust store therefore loads only with:

IceSSL.TruststoreType=PKCS12

The value PKCS12 must be uppercase.

After loading the trust store, Ice checks that it contains at least one certificate. A store loaded without its certificates, such as a PKCS12 trust store loaded with a null password, fails this check. Communicator initialization then fails with an InitializationException that points to IceSSL.TruststorePassword and, for an empty-password PKCS12 store, to:

IceSSL.TruststoreType=PKCS12

If IceSSL.Truststore and IceSSL.Keystore have the same value, Ice loads the file once using IceSSL.KeystoreType. In this case, IceSSL.TruststoreType and IceSSL.TruststorePassword are not used.

IceSSL.UsePlatformCAs

Synopsis

IceSSL.UsePlatformCAs=num

Description

If num is a value greater than zero, IceSSL uses the platform's bundled Root Certificate Authorities. This setting is ignored if IceSSL.CAs is defined.

If not defined, the default value is zero.

IceSSL.VerifyPeer

Synopsis

IceSSL.VerifyPeer=num

Description

Specifies the verification requirements to use during SSL handshaking. The legal values are shown in the table below. If this property is not defined, the default value is 2.

Platform Notes

.NET

This property has no effect on outgoing connections, since .NET always uses the semantics of value 2. For an incoming connection, the value 0 has the same semantics as the value 1.