Ice Docs

IceSSL.*

23 min read

16 min read

19 min read

11 min read

23 min read

23 min read

23 min read

23 min read

23 min read

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)
  • Java
  • .NET

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

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

IceSSL.CAs=path (SChannel, SecureTransport, OpenSSL)

Specifies the path name of a file containing the certificates of trusted certificate authorities (CAs).

If you wish to use the CA certificates bundled with your platform, leave this property unset and enable IceSSL.UsePlatformCAs.

The file can be encoded using the DER or PEM formats. When using PEM, the file can contain multiple certificates. On macOS, IceSSL loads only the CA certificates from the file.

IceSSL resolves a relative path under the default directory defined by IceSSL.DefaultDir when that property is set, and relative to the working directory otherwise.

On iOS, IceSSL first looks for path in the application's resource bundle, under the IceSSL.DefaultDir subdirectory when that property is set, before applying the rule above. It reads the file as PEM when its name contains .pem, and as DER otherwise.

The file must be encoded using the PEM format and can contain multiple certificates. The path can also refer to a directory prepared in advance using the OpenSSL utility c_rehash.

IceSSL resolves a relative path under the default directory defined by IceSSL.DefaultDir when that property is set, and relative to the working directory otherwise.

IceSSL.CertificateRevocationListFiles=file[,file...] (OpenSSL)

Specifies the PEM files containing the certificate revocation lists (CRLs) that IceSSL uses for revocation checks. Separate several files with commas or whitespace. A relative path is resolved under IceSSL.DefaultDir when that property is set, and relative to the working directory otherwise.

IceSSL reads these files only when IceSSL.RevocationCheck is greater than zero, and then requires them: communicator initialization fails with an InitializationException if a file is missing or contains no PEM-encoded CRL or certificate. During the handshake, OpenSSL looks up the CRL of each certificate it checks in these files. If the CRL is not there, the handshake fails.

IceSSL.CertFile=file (SecureTransport, SChannel, OpenSSL)

Specifies the file that contains the program's certificate and, unless IceSSL.KeyFile names a separate file, its private key. The file name may be specified relative to the default directory defined by IceSSL.DefaultDir.

The file must use the PFX (PKCS#12) format and contain the certificate and its private key, or be a PEM file containing the certificate, with the private key in a separate PEM file named by IceSSL.KeyFile. If the file requires a password, the application must supply it with IceSSL.Password; otherwise communicator initialization fails with an InitializationException.

IceSSL resolves a relative file under the default directory defined by IceSSL.DefaultDir when that property is set, and relative to the working directory otherwise.

The file must use the PFX (PKCS#12) format and contain the certificate and its private key. On macOS, it can instead be a PEM file containing the certificate, with the private key in a separate PEM file named by IceSSL.KeyFile. If the file requires a password, the application must supply it with IceSSL.Password; otherwise the import fails. On macOS, IceSSL imports the certificate and its key into the keychain named by IceSSL.Keychain, or into a temporary keychain when that property is not defined.

IceSSL resolves a relative file under the default directory defined by IceSSL.DefaultDir when that property is set, and relative to the working directory otherwise.

On iOS, IceSSL first looks for file in the application's resource bundle, under the IceSSL.DefaultDir subdirectory when that property is set, before applying the rule above.

The file must use the PFX (PKCS#12) format and contain the certificate and its private key, or be a PEM file containing the certificate. In the PEM case, IceSSL reads the private key from IceSSL.KeyFile when that property is defined, and from the certificate file itself otherwise. If the file requires a password, the application must supply it with IceSSL.Password.

IceSSL resolves a relative file under the default directory defined by IceSSL.DefaultDir when that property is set, and relative to the working directory otherwise.

IceSSL.CertStore=name (SChannel)

Specifies the name of a certificate store to use when locating certificates via IceSSL.FindCert. Legal values for name include AddressBook, AuthRoot, CertificateAuthority, Disallowed, My, Root, TrustedPeople, and TrustedPublisher. You can also use an arbitrary value for name.

If not specified, the default value is My.

IceSSL.CertStoreLocation=CurrentUser|LocalMachine (SChannel)

This property is used for two different purposes:

  • to specify the location of a certificate store to use when locating certificates via IceSSL.FindCert.
  • to specify if certificate chain validation will use the machine context (HCCE_LOCAL_MACHINE) or the current user context (HCCE_CURRENT_USER).

If not specified, the default value is CurrentUser.

IceSSL.CAs=path (.NET)

Specifies the path name of a file containing the certificates of trusted certificate authorities (CAs). The file can be encoded using the DER or PEM formats. When using PEM, the file can contain multiple certificates.

IceSSL attempts to locate path as specified; if the given path is relative but does not exist, IceSSL also attempts to locate path relative to the default directory defined by IceSSL.DefaultDir.

If you wish to use the CA certificates bundled with your platform, leave this property unset and enable IceSSL.UsePlatformCAs.

IceSSL.CertFile=file (.NET)

Specifies a file that contains the program's certificate and the corresponding private key. The file must use the PFX (PKCS#12) format. If a password is required to load the file, the application must supply the password using IceSSL.Password.

IceSSL attempts to locate file as specified; if the given path is relative but does not exist, IceSSL also attempts to locate file relative to the default directory defined by IceSSL.DefaultDir.

IceSSL imports the private key into the machine key set when IceSSL.CertStoreLocation is LocalMachine, and into the user key set otherwise.

IceSSL.CertStore=name (.NET)

Specifies the name of a certificate store to use when locating certificates via IceSSL.FindCert. Legal values for name include AddressBook, AuthRoot, CertificateAuthority, Disallowed, My, Root, TrustedPeople, and TrustedPublisher. You can also use an arbitrary value for name.

If not specified, the default value is My.

IceSSL.CertStoreLocation=CurrentUser|LocalMachine (.NET)

Specifies the location of the certificate store to use when locating certificates via IceSSL.FindCert. The location also selects the key set into which IceSSL imports the private key of the certificate loaded from IceSSL.CertFile: the machine key set for LocalMachine and the user key set for CurrentUser.

If not specified, the default value is CurrentUser.

IceSSL.Alias=alias (Java)

Selects a particular certificate from the key store specified by IceSSL.Keystore. IceSSL presents the certificate identified by alias to the peer during authentication. If the alias does not name a key entry of the key store, communicator initialization fails with an InitializationException.

If this property is not defined, IceSSL uses the first key entry of the key store that has a certificate chain.

IceSSL.CheckCertName=num

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.

ValueDescription
0
Host name verification is disabled.
1
Host name verification is enabled.
2
Host name verification is enabled. In Java, IceSSL also sends the host name with SNI.

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 SChannel, SecureTransport, OpenSSL and Java implementations only match the IP address 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

In Java, IceSSL verifies the host name only when IceSSL.VerifyPeer is greater than zero, and sends the host name to the server through the TLS server name indication (SNI) extension only when this property is set to 2. The C++ and .NET implementations always send a DNS host name with SNI.

IceSSL.CheckCRL=num (.NET)

Specifies whether IceSSL checks the revocation status of the certificates in the peer's chain, and what happens when the revocation status of a certificate cannot be determined. The legal values are shown in the table below. If IceSSL.CheckCRL is not defined, the default value is zero.

ValueDescription
0
Disables revocation checking.
1
Checks revocation online. A revoked certificate aborts the connection. A certificate whose revocation status cannot be determined is accepted.
2
Checks revocation online. A revoked certificate, or a certificate whose revocation status cannot be determined, aborts the connection.

The revocation status of a certificate cannot be determined when the certificate carries no revocation information, or when its OCSP responder or CRL distribution point cannot be reached.

If IceSSL.Trace.Security is set to a non-zero value, IceSSL logs the certificate chain status of a rejected connection.

The revocation sources are those of the platform, since .NET delegates certificate chain building to Windows CryptoAPI, to its own OpenSSL-based chain builder on Linux, and to the Security framework on macOS. Windows and Linux fetch CRLs from the distribution points and query the OCSP responders named in the certificates.

The Security framework queries OCSP responders but does not fetch CRLs from distribution points. A certificate that publishes only a CRL therefore has an undeterminable revocation status: it is accepted with the value 1 and rejected with the value 2, whether or not it is revoked.

IceSSL.DefaultDir=path

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.FindCert=criteria (SChannel, SecureTransport)

Selects the program's certificate from a certificate store or keychain instead of loading it from a file. IceSSL ignores this property when IceSSL.CertFile is defined.

IceSSL queries a certificate store for matching certificates and passes all of them to SChannel, which selects the one to present during the handshake. The settings for IceSSL.CertStore and IceSSL.CertStoreLocation determine the target certificate store to be queried. Communicator initialization fails when no certificate matches.

The value for criteria may be *, in which case all of the certificates in the store are selected. Otherwise, criteria must be one or more field:value pairs separated by white space. The valid field names are described below:

FieldDescription
Issuer
Matches a substring of the issuer's name.
IssuerDN
Matches the issuer's entire distinguished name.
Serial
Matches the certificate's serial number.
Subject
Matches a substring of the subject's name.
SubjectDN
Matches the subject's entire distinguished name.
SubjectKeyId
Matches the certificate's subject key identifier.
Thumbprint
Matches the certificate's SHA1 hash.

The field names are case-insensitive. If multiple criteria are specified, only certificates that match all criteria are selected. Values must be enclosed in single or double quotes to preserve white space.

IceSSL queries the keychain for a matching certificate and uses the first match. IceSSL uses the keychain identified in IceSSL.Keychain, or the user's default keychain if IceSSL.Keychain is not defined.

The value for criteria must be one or more field:value pairs separated by white space. The valid field names are described below:

FieldDescription
Label
Matches the user-visible label.
Serial
Matches the certificate's serial number.
Subject
Matches a substring of the subject's name.
SubjectKeyId
Matches the certificate's subject key identifier.

The field names are case-insensitive. If multiple criteria are specified, only certificates that match all criteria are selected. Values must be enclosed in single or double quotes to preserve white space.

IceSSL.Keychain=name (SecureTransport)

Specifies the name of a keychain in which to import the certificate identified by IceSSL.CertFile. Set IceSSL.KeychainPassword if the specified keychain has a password.

A relative path name is opened relative to the current working directory. If the specified keychain file does not exist, a new file is created. If this property is not defined, IceSSL creates a private temporary keychain in the per-user temporary directory with a random password. The temporary keychain and its enclosing directory are removed when the communicator is destroyed.

On iOS this property is ignored, IceSSL uses the default device keychain.

IceSSL.KeyFile=file (SChannel, SecureTransport, OpenSSL)

Specifies a file that contains the program's private key. The file name may be specified relative to the default directory defined by IceSSL.DefaultDir. The corresponding certificate must be specified using IceSSL.CertFile.

IceSSL.KeychainPassword=password (SecureTransport)

Specifies the password for the keychain identified by IceSSL.Keychain. If not defined, IceSSL attempts to open the keychain without a password.

On iOS, this property is ignored.

IceSSL.FindCert=criteria (.NET)

Selects the program's certificate from a certificate store instead of loading it from a file. IceSSL ignores this property when IceSSL.CertFile is defined.

IceSSL queries a certificate store for matching certificates. The settings for IceSSL.CertStore and IceSSL.CertStoreLocation determine the target certificate store to be queried. Communicator initialization fails when no certificate matches.

A server presents the first matching certificate. A client with several matching certificates presents the first one whose issuer is among the issuers the server accepts, or the first one when none matches.

The value for criteria may be *, in which case all of the certificates in the store are selected. Otherwise, criteria must be one or more field:value pairs separated by white space. The valid field names are described below:

FieldDescription
Issuer
Matches a substring of the issuer's name.
IssuerDN
Matches the issuer's entire distinguished name.
Serial
Matches the certificate's serial number.
Subject
Matches a substring of the subject's name.
SubjectDN
Matches the subject's entire distinguished name.
SubjectKeyId
Matches the certificate's subject key identifier.
Thumbprint
Matches the certificate's SHA1 hash.

The field names are case-insensitive. If multiple criteria are specified, only certificates that match all criteria are selected. Values must be enclosed in single or double quotes to preserve white space.

IceSSL.Keystore=file (Java)

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=password (Java)

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=type (Java)

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.

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

Key store typePassword passed to KeyStore.load
PKCS12 or BKS, in upper case
the empty string
any other value
null

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 of public CA certificates; openssl pkcs12 -export -passout pass: creates one. On an OpenJDK-based runtime, an empty-password PKCS12 store therefore loads only with IceSSL.KeystoreType=PKCS12, in upper case.

After loading the key store, Ice checks that the selected key entry has a certificate chain. If it doesn't, communicator initialization fails with an InitializationException that points at IceSSL.KeystorePassword and, for an empty-password PKCS12 store, at 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=password

Specifies the password necessary to decrypt the private key.

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

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.

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

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

IceSSL.RevocationCheck=num (OpenSSL, SChannel, SecureTransport)

Specifies whether IceSSL checks the certificates of the peer's chain for revocation:

ValueDescription
0
Revocation checks are disabled (default).
1
Checks the revocation status of the peer's own certificate.
2
Checks the revocation status of the whole chain.

IceSSL aborts the connection when it finds a revoked certificate or cannot determine the revocation status of a certificate.

The revocation status is looked up in the CRL files listed in IceSSL.CertificateRevocationListFiles, which must be set when this property is greater than zero; otherwise communicator initialization fails. OpenSSL reports an error when it finds no CRL for a certificate it checks, so with the value 2 the files must cover every issuer in the chain.

The value 2 checks the whole chain except the root CA certificate. Revocation data is fetched from the CRL distribution points and OCSP responders named in the certificates, subject to IceSSL.RevocationCheckCacheOnly.

The values 1 and 2 are equivalent: the revocation policy applies to the whole chain. See IceSSL.RevocationCheckCacheOnly for the revocation sources. The value 0 only leaves out IceSSL's revocation policy: the macOS trust evaluation still performs its own best-effort check and rejects a certificate it finds revoked.

IceSSL.RevocationCheckCacheOnly=num (SChannel, SecureTransport)

Specifies whether revocation checks may access the network:

ValueDescription
0
Revocation checks may fetch CRLs from the distribution points and query the OCSP responders named in the certificates.
1
Revocation checks consult only the system's revocation cache (default).

With the default value, IceSSL rejects a certificate whose revocation status is not already in the system cache.

The value 1 also disables the retrieval of intermediate certificates through the Authority Information Access extension, so the whole chain must be available locally.

IceSSL requests any available revocation method. In practice, the macOS trust evaluation queries the OCSP responder named in a certificate's Authority Information Access extension and does not fetch CRLs from distribution points, so IceSSL cannot determine the revocation status of a certificate that publishes only a CRL, and rejects it.

IceSSL.Trace.Security=num

The SSL plug-in trace level:

ValueDescription
0
No security tracing (default).
1
Displays a summary of each SSL connection, the reason a connection is rejected, and the peer's distinguished name when an IceSSL.TrustOnly* property applies.
2
Additionally displays the IceSSL.TrustOnly* entries evaluated against the peer's distinguished name. .NET displays these at level 1.

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

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.

IceSSL on iOS cannot read the distinguished name of a peer certificate, so any IceSSL.TrustOnly* entry fails every connection it applies to with a FeatureNotSupportedException.

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:

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

Use a semicolon to separate multiple entries in a property:

Properties
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:

Properties
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:

Properties
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=ENTRY[;ENTRY;...]

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=ENTRY[;ENTRY;...]

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=ENTRY[;ENTRY;...]

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=file (Java)

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=password (Java)

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 to 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 upper case, and null for any other value, including the OpenJDK default pkcs12. See IceSSL.KeystoreType for 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=type (Java)

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.

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 upper case, and null for any other value. See IceSSL.KeystoreType for what each password means. An empty-password PKCS12 trust store therefore loads only with IceSSL.TruststoreType=PKCS12, in upper case.

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, and communicator initialization fails with an InitializationException that points at IceSSL.TruststorePassword and, for an empty-password PKCS12 store, at 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=num

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=num

Specifies whether an object adapter accepting an incoming connection requests a certificate from the client, and whether the client must supply one. The legal values are shown in the table below; any other value causes communicator initialization to fail with an InitializationException. If this property is not defined, the default value is 2.

ValueDescription
0
The server does not request a certificate from the client.
1
The server requests a certificate from the client and accepts a client that supplies none. If the client supplies one, the server verifies it and aborts the connection if verification fails.
2
The server requires a certificate from the client and aborts the connection if the client supplies none or if verification fails.

This property has no effect on outgoing connections (except in Java, see below): a client always requires and verifies the server's certificate.

With the value 0, a client accepts a server that does not present a certificate and does not check the server's host name (see IceSSL.CheckCertName). A certificate the server does present is still verified.