TAO -- Using SSLIOP

Using SSLIOP

Loading and Configuring the SSLIOP Pluggable Protocol
Using the SSLIOP::Current Object

Loading and Configuring the SSLIOP Pluggable Protocol

TAO implements SSL as a pluggable protocol. As such, it must be dynamically loaded into the ORB. You must use a service configurator file to do this. The service configurator options for the ORB are described in detail in Options for TAO Components. In this case you have to create a svc.conf file that includes:

     dynamic SSLIOP_Factory Service_Object *
       TAO_SSLIOP:_make_TAO_SSLIOP_Protocol_Factory() ""
     static Resource_Factory "-ORBProtocolFactory SSLIOP_Factory"

Note that "TAO_SSLIOP:_make..." is part of the first line. This will load the SSLIOP protocol from the library called TAO_SSL and then use that protocol in the ORB. The SSLIOP protocol has a number of configuration options that we describe below.

SSLIOP Options

Once the SSLIOP protocol is loaded you may want to setup the private key and certificate files, the authentication level and similar features. This is done by setting more options in the service configurator file, for example:

dynamic SSLIOP_Factory Service_Object *
  TAO_SSLIOP:_make_TAO_SSLIOP_Protocol_Factory()"-SSLAuthenticate SERVER"

will enforce validation of the server certificate on each SSL connection. Note that "TAO_SSLIOP:_make..." is part of the first line. The complete list of options is:

Option Description

-SSLNoProtection
On the client side, this option forces request invocations to use the standard insecure IIOP protocol.

On the server side, use of this option allows invocations on the server to be made through the standard insecure IIOP protocol. Request invocations through SSL may still be made.

This option will be deprecated once the SecurityLevel2::SecurityManager interface as defined in the CORBA Security Service is implemented.

-SSLCertificate FORMAT:filename Set the name of the file that contains the certificate for this process. The file can be in Privacy Enhanced Mail (PEM) format or ASN.1 (ASN1). Remember that the certificate must be signed by a Certificate Authority recognized by the client.

-SSLPrivateKey FORMAT:filename Set the name of the file that contains the private key for this process. The private key and certificate files must match. It is extremely important that you secure your private key! By default the OpenSSL utilities will generate pass phrase protected private key files. The password is prompted when you run the CORBA application.

-SSLAuthenticate which Control the level of authentication. The argument can be NONE, SERVER, CLIENT or SERVER_AND_CLIENT. Due to limitations in the SSL protocol CLIENT implies that the server is authenticated too.

-SSLAcceptTimeout which Set the maximum amount of time to allow for establishing a SSL/TLS passive connection, i.e. for accepting a SSL/TLS connection. The default value is 10 seconds.
See the discussion in Bug 1348 in our bug tracking system for the rationale behind this option.

-SSLDHParams filename Set the filename containing the Diffie-Hellman parameters to be used when using DSS-based certificates. The specified file may be a file containing only Diffie-Hellman parameters created by "openssl dhparam", or it can be a certificate containing a PEM encoded set of Diffie-Hellman parameters.

-SSLCipherList cipher-spec Sets the list of available ciphers. The cipher specification string should be formatted per the openssl ciphers(1) man page.

-SSLServerCipherOrder When choosing a cipher, use the server's preferences instead of the client preferences. When not set, the SSL server will always follow the clients preferences.

-SSLCAfile filename Provide a file containing a trusted certificate, overriding the file named by SSL_CERT_FILE environment variable.

-SSLCApath directory Provide a directory from which all files are read for trusted certificates overriding the directory named by SSL_CERT_DIR environment variable.<

-SSLrand filelist Provide additional entropy from the named sources. Works in conjuction with any value supplied via SSL_RAND_FILE environment variable.

-SSLVersionList versions Unlike the cipher list option, this takes a list of SSL versions to support. List is a comma separated string containing SSLv23. If -SSLVersionList is not supplied, SSL will support all of these versions.

-SSLPassword specifier if the supplied -SSLPrivateKey is password protected, this option enables overriding the default password entry. The supplied specifier can be prompt:message to prompt a user for entry, file:filename reads a plain text file, env:envvarname, or simply thepassword. Clearly using any option apart from prompt: weakens the protection.

-SSLCheckHost Adds a verification of the peer address to the connection completion process. This feature requires OpenSSL 1.0.2 or newer and performs a reverse DNS lookup to find the originating hostname. If the version of ssl used does not support X509_check_host(), the peer address does not map to a cannonical host name, or the peer did not provide an X.509 certificate, the connection will fail.

-SSLEcName curve_name Provide the name of the Elliptic Curve to use for ECDH cipher. To see a list of the available curve names use the command openssl ecparam -list_curves

Option	Description
`-SSLNoProtection`	On the client side, this option forces request invocations to use the standard insecure IIOP protocol. On the server side, use of this option allows invocations on the server to be made through the standard insecure IIOP protocol. Request invocations through SSL may still be made. This option will be deprecated once the `SecurityLevel2::SecurityManager` interface as defined in the CORBA Security Service is implemented.
`-SSLCertificate` FORMAT:filename	Set the name of the file that contains the certificate for this process. The file can be in Privacy Enhanced Mail (`PEM`) format or ASN.1 (`ASN1`). Remember that the certificate must be signed by a Certificate Authority recognized by the client.
`-SSLPrivateKey` FORMAT:filename	Set the name of the file that contains the private key for this process. The private key and certificate files must match. It is extremely important that you secure your private key! By default the `OpenSSL` utilities will generate pass phrase protected private key files. The password is prompted when you run the CORBA application.
`-SSLAuthenticate` which	Control the level of authentication. The argument can be `NONE`, `SERVER`, `CLIENT` or `SERVER_AND_CLIENT`. Due to limitations in the SSL protocol `CLIENT` implies that the server is authenticated too.
`-SSLAcceptTimeout` which	Set the maximum amount of time to allow for establishing a SSL/TLS passive connection, i.e. for accepting a SSL/TLS connection. The default value is `10` seconds. See the discussion in Bug 1348 in our bug tracking system for the rationale behind this option.
`-SSLDHParams` filename	Set the filename containing the Diffie-Hellman parameters to be used when using DSS-based certificates. The specified file may be a file containing only Diffie-Hellman parameters created by "`openssl dhparam`", or it can be a certificate containing a PEM encoded set of Diffie-Hellman parameters.
`-SSLCipherList` cipher-spec	Sets the list of available ciphers. The cipher specification string should be formatted per the openssl ciphers(1) man page.
`-SSLServerCipherOrder`	When choosing a cipher, use the server's preferences instead of the client preferences. When not set, the SSL server will always follow the clients preferences.
`-SSLCAfile` filename	Provide a file containing a trusted certificate, overriding the file named by SSL_CERT_FILE environment variable.
`-SSLCApath` directory	Provide a directory from which all files are read for trusted certificates overriding the directory named by SSL_CERT_DIR environment variable.<
`-SSLrand` filelist	Provide additional entropy from the named sources. Works in conjuction with any value supplied via SSL_RAND_FILE environment variable.
`-SSLVersionList` versions	Unlike the cipher list option, this takes a list of SSL versions to support. List is a comma separated string containing SSLv23. If `-SSLVersionList` is not supplied, SSL will support all of these versions.
`-SSLPassword` specifier	if the supplied `-SSLPrivateKey` is password protected, this option enables overriding the default password entry. The supplied specifier can be `prompt:`message to prompt a user for entry, `file:`filename reads a plain text file, `env:`envvarname, or simply thepassword. Clearly using any option apart from prompt: weakens the protection.
`-SSLCheckHost`	Adds a verification of the peer address to the connection completion process. This feature requires OpenSSL 1.0.2 or newer and performs a reverse DNS lookup to find the originating hostname. If the version of ssl used does not support `X509_check_host()`, the peer address does not map to a cannonical host name, or the peer did not provide an X.509 certificate, the connection will fail.
`-SSLEcName` curve_name	Provide the name of the Elliptic Curve to use for ECDH cipher. To see a list of the available curve names use the command openssl ecparam -list_curves

Environment variables

The SSLIOP protocol uses the following environment variables to control its behavior.

Environment Variable Description

SSL_CERT_FILE filename The name of the file that contains all the trusted certificate authority self-signed certificates. By default it is set to the value of the ACE_DEFAULT_SSL_CERT_FILE macro.

SSL_CERT_DIR directory The name of the directory that contains all the trusted certificate authority self-signed certificates. By default it is set to the value of the ACE_DEFAULT_SSL_CERT_DIR macro. This directory must be indexed using the OpenSSL format, i.e. each certificate is aliased with the following link:
$ ln -s cacert.pem `openssl x509 -noout -hash < cacert.pem`.0
Consult the documentation of your SSL implementation for more details.
SSL_EGD_FILE filename The name of the UNIX domain socket that the Entropy Gathering Daemon (EGD) is listening on.
SSL_RAND_FILE filename The file that contains previously saved state from OpenSSL's pseudo-random number generator.

Environment Variable	Description
`SSL_CERT_FILE` filename	The name of the file that contains all the trusted certificate authority self-signed certificates. By default it is set to the value of the `ACE_DEFAULT_SSL_CERT_FILE` macro.
`SSL_CERT_DIR` directory	The name of the directory that contains all the trusted certificate authority self-signed certificates. By default it is set to the value of the `ACE_DEFAULT_SSL_CERT_DIR` macro. This directory must be indexed using the OpenSSL format, i.e. each certificate is aliased with the following link: $ ln -s cacert.pem `openssl x509 -noout -hash < cacert.pem`.0 Consult the documentation of your SSL implementation for more details.
`SSL_EGD_FILE` filename	The name of the UNIX domain socket that the Entropy Gathering Daemon (EGD) is listening on.
`SSL_RAND_FILE` filename	The file that contains previously saved state from OpenSSL's pseudo-random number generator.

Using the `SSLIOP::Current` Object

TAO's SSLIOP pluggable protocol allows an application to gain access to the SSL session state for the current request. For example, it allows an application to obtain the SSL peer certificate chain associated with the current request so that the application can decide whether or not to reject the request. This is achieved by invoking certain operations on the SSLIOP::Current object. The interface for SSLIOP::Current object is:

module SSLIOP {

# pragma prefix "omg.org"

/// A DER encoded X.509 certificate. typedef sequence<octet> ASN_1_Cert;

/// A chain of DER encoded X.509 certificates. The chain /// is actually a sequence. The sender's certificate is /// first, followed by any Certificate Authority /// certificates proceeding sequentially upward. typedef sequence<ASN_1_Cert> SSL_Cert;

/// The following are TAO extensions. # pragma prefix "ssliop.tao"

/// The SSLIOP::Current interface provides methods to /// gain access to the SSL session state for the current /// execution context. local interface Current : CORBA::Current {

/// Exception that indicates a SSLIOP::Current /// operation was invoked outside of an SSL /// session. exception NoContext {};

/// Return the certificate chain associated with /// the current execution context. If no SSL /// session is being used for the request or /// upcall, then the NoContext exception is /// raised. SSL_Cert get_peer_certificate_chain () raises (NoContext);

};

# pragma prefix "omg.org"

};

Obtaining a Reference to the `SSLIOP::Current` Object

A reference to the SSLIOP::Current object may be obtained using the standard CORBA::ORB::resolve_initial_references() mechanism with the argument "SSLIOPCurrent". Here is an example:

int argc = 0;

CORBA::ORB_var orb =    CORBA::ORB_init (argc, "", "my_orb");

CORBA::Object_var obj =    orb->resolve_initial_references ("SSLIOPCurrent");

SSLIOP::Current_var ssliop =   SSLIOP::Current::_narrow (obj.in ());

Examining the Peer Certificate for the Current Request Using OpenSSL

Once a reference to the SSLIOP::Current object has been retrieved, the peer certificate for the current request may be obtained by invoking the SSLIOP::get_peer_certificate method, as follows:

// This method can throw a SSLIOP::Current::NoContext // exception if it is not invoked during a request being // performed over SSL. SSLIOP::ASN_1_Cert_var cert = ssliop->get_peer_certificate ();

The retrieved X.509 peer certificate is in DER (a variant of ASN.1) format. DER is the on-the-wire format used to transmit certificates between peers.

OpenSSL can be used to examine the certificate. For example, to extract and display the certificate issuer from the DER encoded X.509 certificate, the following can be done:

#include <openssl/x509.h> #include <iostream>. . . // Obtain the underlying buffer from the // SSLIOP::ASN_1_Cert. CORBA::Octet *der_cert = cert->get_buffer (); char buf[BUFSIZ]; // Convert the DER encoded X.509 certificate into // OpenSSL's internal format. X509 *peer = ::d2i_X509 (0, &der_cert, cert->length ()); ::X509_NAME_oneline ( ::X509_get_issuer_name (peer), buf, BUFSIZ); std::cout << "Certificate issuer: " << buf << std::endl; ::X509_free (peer);

Ossama Othman
Carlos O'Ryan