Chapter 17 Creating CORBA C++ Clients

Establishing a secure session

A C++ client can use IIOP tunnelled within SSL (also called IIOPS) to establish a secure session with a Jaguar server.

For more information about security, including issuing certificates, see the chapter on security configuration in the Jaguar CTS System Administration Guide.

To establish a secure session with a Jaguar server, follow these steps:

Step	What It Does	Detailed Explanation
1	Initialize the SSL security service as an ORB.	"Initializing the SSL security service"
2	Initialize the client ORB and create an ORB reference.	"ORB properties for secure sessions"
3	Use the ORB reference to create a Manager instance for the Jaguar server.	"ORB properties for secure sessions"
4	Use the Session instance to create stub component instances. This step is the same regardless of whether the application uses SSL.	"Creating sessions" and "Creating stub instances"
5	Optionally, you can retrieve security information about the session.	"Retrieving session security information"

An example that illustrates all of these steps is provided in the sample/ClientSSL subdirectory of your Jaguar server installation.

Initializing the SSL security service

To initialize the SSL security service, you must retrieve the SSL security service context and set the quality of security services as well as any global properties for that context.

You must decide:

Whether you want to respond to any authentication request by the server
Whether you want to use the Sybase PKCS #11 token (the default) or an Entrust ID.

Retrieve the SSL security service context

In this example, you use CORBA::ORB_init to initialize the ORB as an instance, orb1.

CORBA::ORB_var orb1 =

CORBA::ORB_init(argc,argv, "");

Use resolve_initial_references to obtain the initial context from the SSL security service URL string (SSLServiceProvider ) as an object reference, object, on orb1. You must use SSLServiceProvider as the URL string. You use CtsSecurity::SSLServiceProvider::_narrow to convert object to the sslServProv instance (an instance of the SSLServiceProvider interface).

object = orb1->resolve_initial_references
    ("SSLServiceProvider");
sslServProv = CtsSecurity::SSLServiceProvider
    ::_narrow(object);

Set the quality of security services and global properties

To return the available qualities of security services from the availableQop property, call getGlobalProperty on the sslServProv instance. The qualities of security services refer to the security profile characteristic, which specifies the supported CipherSuites.

// query Available quality of services and set

// whatever we want. 
CtsSecurity::StringSeq_var * availQop = 
  sslServProv->getGlobalProperty("availableQop");

At this time, you can also set any global properties, such as the callback component with the callbackImpl property. You specify the callback component using the setGlobalProperty method. The setGlobalProperty method takes the name of the global property, callbackImpl, and the name of the callback component. The name of the component is the DLL name (without file extension) followed by a forward slash, and the package and component name separated by forward slashes as shown in this example:

// Set callbacks. sslServProv->setGlobalProperty

    ("callbackImpl", "myDLL/myPackage/myComponent");

Enable client authentication

To respond to a server's request for client authentication, you can:

Use the setGlobalProperty method to set the certificateLabel property to the client certificate to use when the server asks for one, or
Use the callback interface to provide a dialog box (GUI- or text-based) where the user can enter a certificate to be sent back to the server.

ORB properties for secure sessions

You must set the ORBqop property when initializing the client ORB in order to use one of the available security profile characteristics. The security profile characteristic lists the CipherSuites the client uses when negotiating an SSL connection. The client sends the list of CipherSuites that it uses to the server, and the server selects a CipherSuite from that list. The server must choose the first CipherSuite in the list that it can use.

In this example, the ORBqop property is specified as sybpks_strong (strong 128-bit encryption) and the ORBuserdata property is specified as myUserData . The CORBA::ORB_init method initializes the client ORB (orb2) with these properties.

// Now configure a specific ORB instance,

// overriding the default Quality of // service. Might want to connect to a server

// only using 128bit encryption. Properties props(argc, argv); props.put("ORBqop", "sybpks_strong"); props.put("ORBuserData", myUserData); orb2 = CORBA::ORB_init(props.argc(),

      props.argv(), "");

You can also set these properties when initializing the client ORB:

ORBcertificateLabel Specifies the client certificate to use, if the server requests mutual authentication. The label is a simple name that identifies an X.509 certificate/private key in a PKCS #11 token. You must set this property if the server will request the client's certificate. If this property is not set and the server requests client authentication, credentialCallback is invoked. If you set this property to the value any , then the getCertificateLabel method in the SSLCallback interface is invoked. If client authentication is requested and neither the certificateLabel property nor the credentialCallback is set, the SSL session fails.
ORBpin Specifies the PKCS #11 token PIN. This is required for logging in to a PKCS #11 token for client authentication and for retrieving trust information. If this property is not set and the server requests client authentication, the Login callback implementation is invoked to get the PKCS #11 PIN. If this property is set to the value any , then the getPin method in SSLCallback interface is invoked. If a PKCS #11 token login is required and neither the Login callback property nor the PIN property are set, the SSL session fails. This property can be set application-wide using the SSLServiceProvider context. This property cannot be retrieved once it has been set.
ORBuserData Specifies user data (string datatype). This is an optional property. Client code can set user data during ORB initialization and access it using SSLSessionInfo::getProperty method in the SSL callback implementation. This may be useful as a mechanism to store ORB-level context information that is otherwise not available through the SSLSessionInfo interface.
ORBuseEntrustID Specifies whether to use the Entrust ID or the Sybase PKCS #11 token for authentication. This is a Boolean (true or false) property. If this property is set to false, Sybase PKCS #11 token properties are valid and Entrust-specific properties are ignored. If this property is set to true, Entrust-specific properties are valid and Sybase PKCS #11 token properties are ignored.
ORBentrustPassword Specifies the password for logging in to Entrust with the specified user profile. This property is a null-terminated string, which is optional when the Entrust single-login feature is available and required when this feature is not available. If the password is required but not set, the getPin method in CtsSecurity::SSLCallback is invoked to get the Entrust password. If there is no callback or if the callback does not return a password, the SSL session fails.
ORBentrustIniFile Specifies the path name for the Entrust INI file that provides information on how to access Entrust. This is required when the useEntrustID property is set to true.
ORBentrustUserProfile Specifies an Entrust user profile path name. This property is optional when the Entrust single-login feature is available and required when this feature is not available.

Creating a Manager instance

Creating the manager instance for an SSL session is exactly like creating a manager instance for a non-SSL session, except that instead of specifying an IIOP port for the manager session in the string_to_object method, you specify the secure IIOP (specify iiops ) port (the IIOPS default port number for mutual client-server authentication is 9002 ). You must specify a port that supports the at least the level of security specified by the QOP setting.

Retrieving session security information

To retrieve security information about the session, narrow the component object reference, typeObj, to an SSL session, sslSession. Then use the getSessionInfo method to retrieve the session information from the SSL session and create an object reference for the session information. Use individual get methods to retrieve information about each SSL session property.

You cannot use the getName, getPassword, getAuthenticationStatus, getListener, getPeerAddress, getHostName. These methods are inherited from the SessionInfo interface.

// Obtain SSLSession information from

// typesObj. CtsSecurity::SSLSession_var sslSession =     CtsSecurity::SSLSession::

    _narrow(typesObj); CtsSecurity::SSLSessionInfo_var 
    sslSessionInfo = sslSession->getSessionInfo();

// Obtain user data (similar usage in user's

// SSL callback implementation) String_var currentUserData =

    sslSessionInfo->getProperty("userData");

// Obtain details about server's certificate. CtsSecurity::X509Certificate_var serverX509=    sslSessionInfo->getPeerCertificate(); cout << "Connected to server: <<

    serverX509->getSubjectDN() << endl"; // get details about my certificate CtsSecurity::X509Certificate_var clientX509=

    sslSessionInfo->getCertificate();

Creating an SSL callback component

An SSL callback component is a component that the client uses to execute callback methods. A callback method is a method that responds to SSL requests from a Jaguar server. An SSL callback component resides on the client machine. To create an SSL callback, you must create a component DLL and deploy it on the client machine in a directory specified by the PATH environment variable. You can create a component DLL in the same manner that you would create any other server-side component--using Jaguar Manager and a C++ IDE.

You must specify the component DLL by using the setGlobalProperty method in the CtsSecurity::SSLServiceProvider interface to set the callbackImpl global property. For information, see "Set the quality of security services and global properties".

Implementing callback methods

Although default implementation of the following callback methods are included with the Jaguar client ORB, you can implement your own logic for these callback methods. To implement the default response for callback methods, code them to return the CORBA::NO_IMPLEMENT exception.

getCertificateLabel The user is prompted with the available certificate labels and asked to choose one of them for client authentication.
getCredentialAttribute The Jaguar SSL client runtime engine retrieves credential attributes from the user on request.
getPin The user is prompted with the PKCS11 token or Entrust password information and asked to provide a PIN for logging into the PKCS11 token or Entrust.
trustVerify The user is prompted with server certificate information and asked to determine if the server certificate chain can be trusted and if the SSL session can proceed.

For more information about these callback methods, see the CtsSecurity::SSLCallback interface in the interface repository documentation. The interface repository documentation can be viewed in a Web browser by connecting to your server with this URL:

http://yourhost:yourport/ir/

where yourhost is the Jaguar server's host name and yourport is the HTTP port number.

Example

The sample/ClientSSL subdirectory in your Jaguar server installatation contains an example program that installs an SSL callback to interact with the user.