#

## 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.

#### 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.

### 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 (N` `oContext);`

> `};`

`# 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 |

##