IceSSL.*
On this page:
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++ and Objective-C on macOS and iOS)
- OpenSSL (C++ on Linux or Windows)
- Java
- .NET
- UWP
A property is supported by all platforms if no limitations are mentioned.
Finally, note that Ice for Objective-C 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.CAs
Synopsis
IceSSL.CAs=path (SChannel, SecureTransport, OpenSSL, .NET)
Description
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.
Platform Notes
SChannel, SecureTransport, .NET
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.
On iOS, IceSSL also attempts to open the specified CA certificate file as Resources/DefaultDir/path in the application's resource bundle if IceSSL.DefaultDir is defined or as Resources/path if not defined.
OpenSSL
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 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.
Java
See IceSSL.Truststore.
UWP
This property has no effect in UWP applications. UWP application must set the "Exclusive Trust" flag in the "Certificates" declaration of the application manifest and add the required certificates to the applications "Root" store, or unset the "Exclusive Trust" flag and rely on the system "Trusted Certificate Authorities" current user store.
IceSSL.CertificateRevocationListFiles
Synopsis
IceSSL.CertificateRevocationListFiles=file[:file] (OpenSSL)
Description
Specifies the path of a file containing the CRL info used for certificate revocation checks, the path is relative to IceSSL.DefaultDir. Multiple files can be specified in which case they must be separated using the platforms path separator.
IceSSL.CertFile
Synopsis
IceSSL.CertFile=file (SecureTransport, .NET, UWP)IceSSL.CertFile=file[;file] (SChannel)IceSSL.CertFile=file[:file] (OpenSSL)
Description
Specifies a file that contains the program's certificate and the corresponding private key, the private key can be specified separately using IceSSL.Keyfile. The file name may be specified relative to the default directory defined by IceSSL.DefaultDir.
Platform Notes
SChannel
The file must use the PFX (PKCS#12) format and contain the certificate and its private key or a PEM file containing the certificate in which case the private key must be specify using IceSSL.Keyfile. If a password is required to load the file, the application must either install a password handler or supply the password using IceSSL.Password, otherwise IceSSL will reject the certificate.
This property accepts certificates for both RSA and DSA. To specify both certificates, separate the file names using the platform's path separator character.
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.
SecureTransport
The file must use the PFX (PKCS#12) format and contain the certificate and its private key or a PEM file containing the certificate in which case the private key must be specify using IceSSL.Keyfile. If a password is required to load the file, macOS will use its default graphical password prompt unless the application has installed a password handler or supplied the password using IceSSL.Password. Define IceSSL.Keychain to import this certificate into the specified keychain.
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.
On iOS, IceSSL also attempts to open the specified certificate file as Resources/DefaultDir/file in the application's resource bundle if IceSSL.DefaultDir is defined or as Resources/file if not defined.
OpenSSL
The file must use the PFX (PKCS#12) format and contain the certificate and its private key or a PEM file containing the certificate in which case the private key must be specify using IceSSL.Keyfile. If a password is required to load the file, OpenSSL will prompt the user at the terminal unless the application has installed a password handler or supplied the password using IceSSL.Password.
This property accepts certificates for both RSA and DSA. To specify both certificates, separate the file names using the platform's path separator character.
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.
.NET
The file must use the PFX (PKCS#12) format and contain the certificate and its private key. The password for the file must be supplied 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.
Java
See IceSSL.Keystore.
UWP
The file must use the PFX (PKCS#12) format and contain the certificate and its private key. The password for the file must be supplied using IceSSL.Password. The certificate is imported into the application Personal certificate store. The file must use one of ms-appx:/// or ms-appdata:/// URIs schemes.
IceSSL.CertStore
Synopsis
IceSSL.CertStore=name (SChannel, .NET, UWP)
Description
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
Synopsis
IceSSL.CertStoreLocation=CurrentUser|LocalMachine (SChannel, .NET)
Description
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.
An Ice program running as a Windows service will typically need to set this property to LocalMachine.
IceSSL.CertVerifier
Synopsis
IceSSL.CertVerifier=classname (Java, .NET)
Description
Specifies the name of a Java or .NET class that implements the IceSSL.CertificateVerifier interface for performing application-defined certificate verification.
Platform Notes
SChannel, SecureTransport, OpenSSL and UWP
C++ applications can install a certificate verifier programmatically.
IceSSL.CheckCertName
Synopsis
IceSSL.CheckCertName=num
Description
Specifies if certificate host name verification and server name indication are enabled. The legal values are shown in the table below. If this property is not defined, the default value is 0.
| 0 | Host name verification and server name indication are disabled. |
| 1 | Host name verification is enabled, server name indication is disabled. |
| 2 | Host name verification and server name indication are enabled. |
IceSSL skips the host name verification step if the negotiated cipher does not provide authentication (such as Anonymous Diffie Hellman ciphers), or if the proxy endpoint does not specify a host and Ice.Default.Host is not defined. 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 unless IceSSL.VerifyPeer is configured to ignore verification failures.
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, Java and UWP 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 10.15 (Catalina) only matches the DNS name against the subject alternative names, it doesn't check the
CommonName
If the server name indication (SNI) extension is requested and a DNS name is used for the endpoint's host or Ice.Default.Host, this DNS name will be sent with the client's TLS handshake message. This allows servers that support the SNI extension to return different certificates based on the DNS name received with the handshake message. While IceSSL does not support SNI on the server side, this can be useful when using the WebSocket transport with an HTTP server that supports SNI.
Platform Differences for SNI
With the C# and the SChannel implementations, SNI is always enabled: when the host name is a DNS name, it is always sent with the client's TLS handshake message, regardless of the value of CheckCertName.
SNI is not supported with the Java-Compat mapping: with Java-Compat, setting CheckCertname to 2 is equivalent to setting it to 1.
IceSSL.CheckCRL
Synopsis
IceSSL.CheckCRL=num (.NET)
Description
If num is a value greater than zero, IceSSL checks the certificate revocation list (CRL) to determine if the peer's certificate has been revoked. The value for num determines the resulting behavior:
| Disables CRL checking. |
| If a certificate is revoked, IceSSL aborts the connection, logs a message and raises an exception. If a certificate's revocation status is unknown, IceSSL logs a message but accepts the certificate. |
2 | If a certificate is revoked or its revocation status is unknown, IceSSL aborts the connection, logs a message and raises an exception. |
The IceSSL.Trace.Security property must be set to a non-zero value to see CRL-related log messages. If IceSSL.CheckCRL is not defined, the default value is zero.
IceSSL.Ciphers
Synopsis
IceSSL.Ciphers=ciphers (SChannel, SecureTransport, OpenSSL, Java)
Description
Specifies the cipher suites that IceSSL is allowed to negotiate. A cipher suite is a set of algorithms that satisfies the four requirements for establishing a secure connection: signing and authentication, key exchange, secure hashing, and encryption. Some algorithms satisfy more than one requirement, and there are many possible combinations.
If not specified, the plug-in uses the security provider's default cipher suites. Enable IceSSL.Trace.Security and carefully review the application's log output to determine which cipher suites are enabled by default, or to verify your cipher suite configuration.
Platform Notes
SChannel
The value of this property is a whitespace-separated list that can include any of the following:
3DESAES_128AES_256DESRC2RC4
For example, the following setting enables AES cipher suites:
IceSSL.Ciphers=AES_128 AES_256
Anonymous Diffie Hellman ciphers are not supported on Windows.
SecureTransport
The property value is interpreted as a list of tokens delimited by white space. The plug-in executes the tokens in the order of appearance in order to assemble the list of enabled cipher suites. The table below describes the tokens:
| Reserved keyword that enables all supported cipher suites. If specified, it must be the first token in the list. Use with caution as it may enable low-security cipher suites. |
| Reserved keyword that disables all cipher suites. If specified, it must be the first token in the list. Use |
| Includes the cipher suite whose name matches NAME exactly. |
| Excludes the cipher suite whose name matches |
| Includes all cipher suites whose names contain the given regular expression |
| Excludes all cipher suites whose names contain the given regular expression |
For example, the following setting disables all cipher suites except those that support 256-bit AES with SHA256:
IceSSL.Ciphers=NONE (AES_256.*SHA256)
Note that no warning is given if an unrecognized cipher is specified.
OpenSSL
The value of this property is passed directly to the OpenSSL library and the list of supported ciphers depends on how your installation of OpenSSL was compiled. You can obtain a complete list of the supported cipher suites using the command openssl ciphers. This command will likely generate a long list. To simplify the selection process, OpenSSL supports several classes of ciphers. Classes and ciphers can be excluded by prefixing them with an exclamation point. The special keyword @STRENGTH sorts the current cipher list in order of encryption algorithm key length. The classes are:
| Enables all supported cipher suites. This class should be used with caution, as it may enable low-security cipher suites. |
| Anonymous ciphers. |
| Low bit-strength ciphers. |
| Export-crippled ciphers. |
Here is an example of a reasonable setting:
IceSSL.Ciphers=ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH
This value excludes the ciphers with low bit-strength and known problems, and orders the remaining ciphers according to their key length. Note that no warning is given if an unrecognized cipher is specified.
This property doesn't affect the ciphers used by TLS 1.3, with OpenSSL IceSSL always use the TLS 1.3 default cipher list.
Java
The property value is interpreted as a list of tokens delimited by white space. The plug-in executes the tokens in the order of appearance in order to assemble the list of enabled cipher suites. The table below describes the tokens:
| Reserved keyword that enables all supported cipher suites. If specified, it must be the first token in the list. Use with caution as it may enable low-security cipher suites. |
| Reserved keyword that disables all cipher suites. If specified, it must be the first token in the list. Use |
| Enables the cipher suite matching the given name. |
| Disables the cipher suite matching the given name. |
| Enables cipher suites whose names contain the regular expression |
| Disables cipher suites whose names contain the regular expression |
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.
Platform Notes
UWP
This property has not effect in UWP application.
IceSSL.DH.bits
Synopsis
IceSSL.DH.bits=file (OpenSSL)
Description
Specifies a file containing Diffie Hellman parameters whose key length is bits, as shown in the following example:
IceSSL.DH.1024=dhparams1024.pem
IceSSL supplies default parameters for key lengths of 512, 1024, 2048, and 4096 bits, which are used if no user-defined parameters of the desired key length are specified. The parameters must be encoded using the PEM format.
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.
Platform Notes
SecureTransport
See IceSSL.DHParams.
IceSSL.DHParams
Synopsis
IceSSL.DHParams=file (SecureTransport)
Description
Specifies a file containing Diffie Hellman parameters. The parameters must be encoded using the DER format.
This property only affects server (incoming) connections. Clients obtain their DH parameters when negotiating a SSL/TLS connection with the server.
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.
If this property is not specified, macOS will generate its own set of Diffie Hellman parameters for the process. Computing these parameters at run time can take up to 30 seconds, so we recommend generating them in advance and defining this property.
Diffie Hellman parameters are not supported on iOS, this property will be ignored.
You can generate Diffie Hellman parameters using the openssl dhparam command.
Platform Notes
OpenSSL
Use IceSSL.DH.bits.
IceSSL.EntropyDaemon
Synopsis
IceSSL.EntropyDaemon=file (OpenSSL)
Description
Specifies a Unix domain socket for the entropy gathering daemon, from which OpenSSL gathers entropy data to initialize its random number generator.
IceSSL.FindCert
Synopsis
IceSSL.FindCert=criteria (SChannel, SecureTransport, .NET)
Description
Builds a collection of certificates that will be used for authentication.
A server requires a certificate for authentication purposes, therefore IceSSL selects the first certificate in the accumulated collection. This is normally the certificate loaded via IceSSL.CertFile, if that property was defined. Otherwise, IceSSL selects one of the certificates identified by IceSSL.FindCert.
Platform Notes
SChannel, .NET
IceSSL queries a certificate store for matching certificates and adds them to the application's certificate collection. The settings for IceSSL.CertStore and IceSSL.CertStoreLocation determine the target certificate store to be queried.
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:
| Matches a substring of the issuer's name. |
| Matches the issuer's entire distinguished name. |
| Matches the certificate's serial number. |
| Matches a substring of the subject's name. |
| Matches the subject's entire distinguished name. |
| Matches the certificate's subject key identifier. |
| 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.
SecureTransport
IceSSL queries the keychain for matching certificates and adds them to the application's certificate collection. 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:
| Matches the user-visible label. |
| Matches the certificate's serial number. |
| Matches a substring of the subject's name. |
| 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.
On iOS, matching on the Subject field is not supported.
Java
Use IceSSL.Alias.
IceSSL.InitOpenSSL
Synopsis
IceSSL.InitOpenSSL=num (OpenSSL)
Description
Indicates whether IceSSL should perform the global initialization tasks for the OpenSSL library. The default value is 1, meaning IceSSL will initialize OpenSSL. An application can set this property to zero if it wishes to perform the OpenSSL initialization itself, which can be useful when the application uses multiple components that depend on OpenSSL.
IceSSL.Keychain
Synopsis
IceSSL.Keychain=name (SecureTransport)
Description
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 not defined, IceSSL uses the user's default keychain.
On iOS this property is ignored, IceSSL uses the default device keychain.
IceSSL.Keyfile
Synopsis
IceSSL.Keyfile=file (SChannel, SecureTransport, OpenSSL)
Description
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.KeychainPassword
Synopsis
IceSSL.KeychainPassword=password (SecureTransport)
Description
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.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, or might be required to use an anonymous cipher suite.
IceSSL.KeystorePassword
Synopsis
IceSSL.KeystorePassword=password (Java)
Description
Specifies the password used to verify the integrity of the key store defined by IceSSL.Keystore. The integrity check is skipped if this property is not defined.
It is a security risk to use a plain-text password in a configuration file.
IceSSL.KeystoreType
Synopsis
IceSSL.KeystoreType=type (Java)
Description
Specifies the format of the key store file defined by IceSSL.Keystore. Legal values are JKS and PKCS12. If not defined, the JVM's default value is used (normally JKS).
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, UWP
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.PasswordCallback
Synopsis
IceSSL.PasswordCallback=classname (Java, .NET)
Description
Specifies the name of a Java or .NET class that implements the IceSSL.PasswordCallback interface. Using a password callback is a more secure alternative to specifying a password in a plain-text configuration file.
Platform Notes
SChannel, SecureTransport, OpenSSL, UWP
Use setPasswordPrompt to install a password callback in the plug-in.
IceSSL.PasswordRetryMax
Synopsis
IceSSL.PasswordRetryMax=num (SChannel, SecureTransport, OpenSSL, UWP)
Description
Specifies the number of attempts IceSSL should allow the user to make when entering a password. If not defined, the default value is 3.
IceSSL.Protocols
Synopsis
IceSSL.Protocols=list (SChannel, OpenSSL, Java, .NET)
Description
Specifies the TLS protocols allowed during the SSL/TLS handshake. Legal values are as follows:
SSL3,SSLv3TLS1,TLSv1TLS1_0,TLSv1_0(aliases forTLS1)TLS1_1, TLSv1_1TLS1_2, TLSv1_2TLS1_3, TLSv1_3
Case is ignored, so for example tls1_2 is also accepted.
You can specify multiple values for this property by separating them with commas or white space. If this property is not defined, the default setting is:
IceSSL.Protocols=TLS1_0, TLS1_1, TLS1_2, TLS1_3
when the underlying TLS/SSL engine supports TLS 1.3. Otherwise, the default is:
IceSSL.Protocols=TLS1_0, TLS1_1, TLS1_2
Platform Notes
SecureTransport
Use IceSSL.ProtocolVersionMin and IceSSL.ProtocolVersionMax.
IceSSL.ProtocolVersionMax
Synopsis
IceSSL.ProtocolVersionMax=prot (SecureTransport)
Description
Specifies the maximum protocol version allowed during the TLS/SSL handshake. Legal values are the same as for IceSSL.Protocols. If this property is not defined, the system's default value is used.
Platform Notes
SChannel, OpenSSL, Java, .NET
Use IceSSL.Protocols.
IceSSL.ProtocolVersionMin
Synopsis
IceSSL.ProtocolVersionMin=prot (SecureTransport)
Description
Specifies the minimum protocol allowed during the TLS/SSL handshake. Legal values are the same as for IceSSL.Protocols. If this property is not defined, the default value is TLS1_0.
Platform Notes
SChannel, OpenSSL, Java, .NET
Use IceSSL.Protocols.
IceSSL.Random
Synopsis
IceSSL.Random=filelist (OpenSSL, Java)
Description
Specifies one or more files containing data to use when seeding the random number generator. The file names should be separated using the platform's path separator.
Platform Notes
OpenSSL
IceSSL attempts to locate each file as specified; if a given path is relative but does not exist, IceSSL also attempts to locate it relative to the default directory defined by IceSSL.DefaultDir.
Java
IceSSL first attempts to open each file as a class loader resource and then as a regular file. If a given path is relative but does not exist, IceSSL also attempts to locate it relative to the default directory defined by IceSSL.DefaultDir.
IceSSL.RevocationCheck
Synopsis
IceSSL.RevocationCheck=num (OpenSSL, SChannel, SecureTransport)
Description
Control whenever or not to check for revoked certificates:
| 0 | Certificate revocation checks are disabled (default) |
| 1 | Enable certificate revocation checks only for the leaf certificate. |
| 2 | Enable certificate revocation checks for the whole chain. |
Platform Notes
OpenSSL
IceSSL will use the CRL files specified by IceSSL.CertificateRevocationListFiles for the revocation checks, if not CRL files are specified OpenSSL doesn't check certificate revocation.
SecureTransport
With SecureTransport 1 and 2 are equivalent and in both cases the whole chain is check.
IceSSL.RevocationCheckCacheOnly
Synopsis
IceSSL.RevocationCheckCacheOnly=num (SChannel, SecureTransport)
Description
Control whenever or not the certificate revocation check is done only against the system cache without additional network calls.
| 0 | Certificate revocation checks only consult the system cache (default) |
| 1 | Certificate revocation checks can query the certificate distribution points, or the OCSP responder to obtain the certificate revocation info. |
Platform Notes
SecureTransport
The CRL distribution points are always ignored, and the AIA OCSP responder is used if present.
IceSSL.SchannelStrongCrypto
Synopsis
IceSSL.SchannelStrongCrypto=num (SChannel)
Description
If num is a value greater than zero, the IceSSL SChannel implementation will set the SCH_USE_STRONG_CRYPTO flag which instructs SChannel to disable known weak cryptographic algorithms. The default value for this property is 0 for better interoperability.
IceSSL.Trace.Security
Synopsis
IceSSL.Trace.Security=num (SChannel, SecureTransport, OpenSSL, Java, .NET)
Description
The SSL plug-in trace level:
| No security tracing (default). |
| Display diagnostic information about SSL connections. |
IceSSL.TrustOnly
Synopsis
IceSSL.TrustOnly=ENTRY[;ENTRY;...] (SChannel, SecureTransport, OpenSSL, Java, .NET, UWP)
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:
- IceSSL aborts the connection if any rejection or acceptance entries are defined and the peer does not supply a certificate.
- 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.)
- 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.
Platform Notes
UWP
UWP applications can only match the CN part of the DN, the full DN is not provided by the UWP certificate APIs.
IceSSL.TrustOnly.Client
Synopsis
IceSSL.TrustOnly.Client=ENTRY[;ENTRY;...] (SChannel, SecureTransport, OpenSSL, Java, .NET, UWP)
Description
Identifies trusted and untrusted peers for outgoing (client) connections. The entries defined in this property are combined with those of IceSSL.TrustOnly.
Platform Notes
UWP
UWP applications can only match the CN part of the DN, the full DN is not provided by the UWP certificate APIs.
IceSSL.TrustOnly.Server
Synopsis
IceSSL.TrustOnly.Server=ENTRY[;ENTRY;...] (SChannel, SecureTransport, OpenSSL, Java, .NET)
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;...] (SChannel, SecureTransport, OpenSSL, Java, .NET)
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 this property is not defined, IceSSL uses the value of IceSSL.Keystore by default. If no truststore is specified and the keystore does not contain a valid certificate chain, 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, or might be required to use an anonymous cipher suite.
Platform Notes
SChannel, SecureTransport, OpenSSL, .NET
Use IceSSL.CAs.
IceSSL.TruststorePassword
Synopsis
IceSSL.TruststorePassword=password (Java)
Description
Specifies the password used to verify the integrity of the key store defined by IceSSL.Truststore. The integrity check is skipped if this property is not defined.
It is a security risk to use a plain-text password in a configuration file.
Platform Notes
SChannel, SecureTransport, OpenSSL, .NET
Use IceSSL.Password.
IceSSL.TruststoreType
Synopsis
IceSSL.TruststoreType=type (Java)
Description
Specifies the format of the key store file defined by IceSSL.Truststore. Legal values are JKS and PKCS12. If not defined, the default value is JKS.
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.
Platform Notes
UWP
This property has no effect in UWP applications. A UWP application must set the Exclusive Trust flag in the Certificates declaration of the application manifest to decide whether or not to trust certificates from the Trusted Root Certificate Authorities user store.
IceSSL.VerifyDepthMax
Synopsis
IceSSL.VerifyDepthMax=num (SChannel, SecureTransport, OpenSSL, Java, .NET, UWP)
Description
Specifies the maximum depth of a trusted peer's certificate chain, including the peer's certificate. A value of zero accepts chains of any length. If not defined, the default value is 3.
IceSSL.VerifyPeer
Synopsis
IceSSL.VerifyPeer=num (SChannel, SecureTransport, OpenSSL, Java, .NET, UWP)
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.
| For an outgoing connection, the client verifies the server's certificate (if an anonymous cipher is not used) but does not abort the connection if verification fails. For an incoming connection, the server does not request a certificate from the client. |
| For an outgoing connection, the client verifies the server's certificate and aborts the connection if verification fails. For an incoming connection, the server requests a certificate from the client and verifies it if one is provided, aborting the connection if verification fails. |
| For an outgoing connection, the semantics are the same as for the value |
Verifications performed by IceSSL after the SSL handshake (the maximum certificate's depth or the trust checks configured with the TrustOnly properties) are not affected by the value of this property. Specifically, if one of these checks fail, the connection will still be aborted even if IceSSL.VerifyPeer=0.
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.