After installing IceSSL, an application typically needs to define a handful of additional properties to configure settings such as the location of certificate and key files. This page provides an introduction to configuring the plug-in for iOS and macOS applications.
On this page:
Configuring IceSSL for macOS
Our first example shows the properties that are sufficient in many situations:
IceSSL.DefaultDir property is a convenient way to specify the default location of your certificate files. The properties that follow it define the files containing the program's certificate with private key, and trusted CA certificate, respectively. Finally, the
IceSSL.Password property specifies the password necessary to open
It is a security risk to define a password in a plain text file, such as an Ice configuration file, because anyone who can gain read access to your configuration file can obtain your password. IceSSL also supports alternate ways to supply a password.
Keychain Examples for macOS
If the specified keychain file does not exist, IceSSL will create it. The file name is opened relative to the user's current working directory unless an absolute path name is provided.
The user's default keychain is normally unlocked after logging into the system, so IceSSL doesn't usually require a password to import a certificate into this keychain. However, if your keychain is not unlocked automatically, or if you've selected a different keychain, you can supply a password using the
It is a security risk to define a password in a plain text file, such as an Ice configuration file, because anyone who can gain read access to your configuration file can obtain your password.
If you don't define
IceSSL.KeychainPassword and a password is required to open the keychain, macOS will prompt the user for the password.
To use a certificate that's already in a keychain, you can omit the
IceSSL.Password properties and use
Here we've instructed IceSSL to locate the certificate in the default keychain labeled
Client and use that as the program's identity.
ADH Example for macOS
The following example uses ADH (the Anonymous Diffie-Hellman cipher). ADH is not a good choice in most cases because, as its name implies, there is no authentication of the communicating parties, and it is vulnerable to man-in-the-middle attacks. However, it still provides encryption of the session traffic and requires very little administration and therefore may be useful in certain situations. The configuration properties shown below demonstrate how to use ADH:
IceSSL.VerifyPeer property changes the plug-in's default behavior with respect to certificate verification. Without this setting, IceSSL rejects a connection if the peer does not supply a certificate (as is the case with ADH).
Configuring IceSSL for iOS
An iOS application first needs to load the IceSSL plug-in and ensures the communicator initializes this plug-in during the
In C++, you need to call
Ice::registerIceSSL(true) prior to communicator initialization. You can alternatively call
Ice::registerIceSSL(false) and include
Ice.Plugin.IceSSL=1 in your communicator's configuration. Likewise in Objective-C, you need to call
ICEregisterIceSSL(YES) prior to communicator initialization. You can alternatively call
ICEregisterIceSSL(NO) and include
Ice.Plugin.IceSSL=1 in your communicator's configuration. See Using Plugins with Static Libraries for additional information on these functions.
In Swift, you just need to include
Ice.Plugin.IceSSL=1 in your communicator's configuration.
With iOS applications, certificate files are loaded from the application's resource bundle. Consider the following properties:
IceSSL.DefaultDir property is a convenient way to specify the location of your certificate files. Defining
IceSSL.DefaultDir means IceSSL searches for certificate files relative to the specified directory. For the properties in the example above, IceSSL composes the pathnames
IceSSL.DefaultDir is not defined, IceSSL uses the certificate file pathnames exactly as they are supplied.
As mentioned earlier, IceSSL has different semantics for locating certificate files depending on the target platform. For the iPhone and iPhone simulator, IceSSL attempts to open a certificate file in the application's resource bundle as
IceSSL.DefaultDir is defined, or as simply
Resources/file otherwise. If the target platform is macOS and the certificate file cannot be found in the resource bundle, IceSSL also attempts to open the file in the file system as
DefaultDir/file if a default directory is specified, or as simply
IceSSL requires that the CA certificate file specified by
IceSSL.CAs use the DER format. The certificate file in
IceSSL.CertFile must use the Personal Information Exchange (PFX, also known as PKCS#12) format and contain both a certificate and its corresponding private key. The
IceSSL.Password property specifies the password used to secure the certificate file.
Keychain Examples for iOS
login keychain is the user's default keychain, which is normally unlocked after logging into the system. IceSSL does not usually require a password to import a certificate into the
login keychain. However, if your
login keychain is not unlocked automatically, or if you have selected a different keychain, you can supply a password using the
IceSSL Diagnostics for macOS
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.
macOS also includes a TLS logging facility. To enable it, run the following command in Terminal:
To see the log entries you must enable logging for warnings in syslog:
Then run syslog in 'wait' mode: