This page describes the .NET API for the IceSSL plug-in.
On this page:
The IceSSL Plugin Interface in C#
Applications can interact directly with the IceSSL plug-in using the native C# interface
IceSSL.Plugin. A reference to a
Plugin object must be obtained from the communicator in which the plug-in is installed:
Plugin interface supports the following methods:
The methods are summarized below:
These methods are for advanced use cases and rarely used in practice.
These methods install and retrieve a custom certificate verifier object that the plug-in invokes for each new connection.
getCertificateVerifierreturns null if a verifier has not been set.
These methods install and retrieve a password callback object that supplies IceSSL with passwords.
getPasswordCallbackreturns null if a callback has not been set. Using
setPasswordCallbackis a more secure alternative to setting passwords in clear-text configuration files.
Obtaining SSL Connection Information in C#
You can obtain information about any SSL connection using the
getInfo operation on a
Connection object. IceSSL defines the following type in Slice:
Ice::ConnectionInfo object can be narrowed to
IceSSL::ConnectionInfo for an SSL connection.
certs member contains the peer's certificate chain; the
cs:type metadata changes the mapping to an array of
X509Certificate2 objects. The array is structured so that the first element is the peer's certificate, followed by its signing certificates in the order they appear in the chain, with the root CA certificate as the last element. The array is empty if the peer did not present a certificate chain.
cipher member is a description of the ciphersuite that SSL negotiated for this connection. The
verified member is always true if
IceSSL.VerifyPeer > 0. Otherwise, it is false if one of these checks fail:
- the underlying SSL engine certificate verification fails,
IceSSL.CheckCertName > 0, the host name verification check failed.
underlying data member contains the connection information of the underlying transport (if SSL is based on TCP, this member will contain an instance of
Ice::TCPEndpointInfo which you can use to retrieve the remote and local addresses). The
incoming member indicates whether the connection is inbound (a server connection) or outbound (a client connection). The
connectionId data member matches the connection identifier set on the proxy. Finally, if
incoming is true, the
adapterName member supplies the name of the object adapter that hosts the endpoint.
Installing a Certificate Verifier in C#
A new connection undergoes a series of verification steps before an application is allowed to use it. The low-level SSL engine executes certificate validation procedures and, assuming the certificate chain is successfully validated, IceSSL performs additional verification as directed by its configuration properties. If a certificate verifier is installed, IceSSL invokes it to provide the application with an opportunity to decide whether to accept or reject the connection. The value of the
IceSSL.VerifyPeer property also plays an important role here. We've summarized the process in the following flow chart:
CertificateVerifier interface has only one method:
IceSSL rejects the connection if
false, and allows it to proceed if the method returns
verify method receives a
NativeConnectionInfo object that describes the connection's attributes.
The following class is a simple implementation of a certificate verifier:
In this example, the verifier rejects the connection unless the string
zeroc is present in the issuer's distinguished name of the peer's certificate. In a more realistic implementation, the application is likely to perform detailed inspection of the certificate chain.
Installing the verifier is a simple matter of calling
setCertificateVerifier on the plug-in interface:
You should install the verifier before any SSL connections are established. An alternate way of installing the verifier is to define the
IceSSL.CertVerifier property with the class name of your verifier implementation. IceSSL instantiates the class using its default constructor.
You can also install a certificate verifier using a custom plug-in to avoid making changes to the code of an existing application.
The Ice run time calls the
verify method during the connection-establishment process, therefore delays in the
verify implementation have a direct impact on the performance of the application. Do not make remote invocations from your implementation of
Converting Certificates in C#
IceSSL offers the following convenience method to create a certificate object from a PEM-encoded string:
Given a string in the PEM format,
createCertificate returns the equivalent