Chapter 6 Using SSL in C++ Clients

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