This represents the SSL user callback interface. User (application builder tool/user application) provides an implementation of a portion or all of this interface and sets the property in the SSLProvider context. Note that, these callbacks are optional. Client ORB will provide a default implementation of these callbacks.
Sample Java code to set callbacks using the SSLProvider context.
...
CtsSecurity::SSLServiceProvider sslServiceProv;
.. code to obtain SSLServiceProvider context. See CtsSecurity::SSLServiceProvider ..
...
sslServiceProv.setGlobalProperty("callbackImpl", "mypackage.mySSLCallbackImpl");
...
Sample C++ code to set callbacks:
...
CtsSecurity::SSLServiceProvider_var sslServiceProv;
... code to obtain SSLProviderProvider context. See CtsSecurity::SSLServiceProvider ...
sslServiceProv->setGlobalProperty("callbackImpl", "MySSLCallbackImplDLLName/MyPackage/MySSLCallbackComponent");
...
In this callback, interactive end-user should be prompted with the available certificate labels and asked to choose one of them for client authentication. User can be shown additional session information by retrieving necessary information (such as server certificate) from the supplied SSLSessionInfo object. This callback is invoked if the client program has not set a certificate label for client authentication and the server has requested for client authentication.
string getCertificateLabel
(
in CtsSecurity::SSLSessionInfo si,
in CtsSecurity::StringSeq labels
)
raises (CtsSecurity::NoCertificateException, CtsSecurity::UserAbortedException);
This method should return the certificate label selected by the user for the client authentication. If this method returns NoCertificateException, it is upto the server to respond. In most cases in such a situation, server might reject the SSL connection (this is the behavior with Jaguar servers if the listener is configured to request client authentication and user fails to respond with a certificate). These certificate labels correpond to the matching privateKey-Certificate pairs found in the Sybase PKCS11 token sorted in the decreasing order of preference with respect to the acceptable CAs from the server.
If this method is not implemented, it should raise CORBA::NO_IMPLEMENT exception.
If user wants to terminate the SSL handshake which is in progress, this method should raise the UserAbortedException exception.
Default implementation of this callback always returns the first certificate in the list of labels and if there are no labels supplied, it raises CtsSecurity::NoCertificateException. Default implementation will be used if this method in the user callback implementation returns CORBA::NO_IMPLEMENT exception.
This callback is used by the Jaguar SSL client runtime engine to get credential attributes from the interactive user on demand. Currently, these attributes are Entrust PKI specific and are used only when the application enables useEntrustId property at the ORB or SSLServiceProvider level. In this callback, interactive end-user should be prompted with the available attribute values and asked to choose one of them. User can be provided with additional session information by retrieving necessary information (such as server certificate) from the supplied SSLSessionInfo object. This callback is invoked if the client program has not set the necessary credential attributes. Note that, this may be required for client authentication and/or server authentication (for instance, Entrust login is required to get trust information for server authentication).
string getCredentialAttribute
(
in CtsSecurity::SSLSessionInfo si,
in CtsSecurity::CredentialAttribute attr,
in CtsSecurity::StringSeq attrValues
)
raises (CtsSecurity::NoValueException, CtsSecurity::UserAbortedException);
| Credential Attribute | Meaning |
|---|---|
| CRED_ATTR_ENTRUST_INIFILE | Select Entrust INI File path name for accessing Entrust. Interactive user should be able to supply a new INI file path name (i.e. user interface typically would be a combo box -- edit with a drop down list box) |
| CRED_ATTR_ENTRUST_USERPROFILE | Select an Entrust User profile path name. User interface in this case typically would be a combo box (edit with a drop down list box). Entrust profiles (if any) supplied as input argument in this callback will be of the following format.
<Entrust Token Info>:<Profile Name> Examples: <Litronic Token>:<E:\Entrust\Profiles\Litronic.epf> <Vendor2 Token>:<E:\Entrust\Profiles\hw\Vendor2.epf> These will be the profiles associated with the tokens (if any) supported by Entrust in the current execution environment. Interactive user should be provided with the ability to change the profile path name associated with Entrust token if the user wishes select one of these token profiles. This method can return the selected user profile in one of the following three forms. User selected Profile Path Name <Entrust Token Info>:<Profile Name> <Entrust Token Info>:<Profile Name>:<New Profile Path Name> Examples: E:\Entrust\Profiles\MyProfile.epf Above free format string is used for user profiles that do not correspond to Entrust tokens. <Litronic Token>:<E:\Entrust\Profiles\Litronic.epf> <Litronic Token>:<E:\Entrust\Profiles\Litronic.epf>:<E:\Users\MyName\EntrustProfiles\Litronic.epf> |
This method should return the attribute value selected by the user. If this method returns NoValueException, it is possible that the SSL session will fail.
If this method is not implemented, it should raise CORBA::NO_IMPLEMENT exception.
If user wants to terminate the SSL handshake which is in progress, this method should raise the UserAbortedException exception.
Default implementation of this callback always returns the first value in the list of values supplied and if there are no values supplied, it raises CtsSecurity::NoValueException. Default implementation will be used if this method in the user callback implementation returns CORBA::NO_IMPLEMENT exception.
In this callback, interactive end-user should be prompted with the PKCS11 token information and asked to provide PIN for logging into PKCS11 token. User can be shown additional session information by retrieving necessary properties (such as token name) from the supplied SSLSessionInfo object. This callback is invoked if the pkcs11 token is not logged in and the pin is not supplied as a ORB/global property. PKCS11 login can also expire after the user specified loginTimeout period. PKCS11 login is required in the case of client authentication to access private key and to access the trust information during the server authentication.
CtsSecurity::OctetSeq getPin
(
in CtsSecurity::SSLSessionInfo si,
in boolean timedOut
)
raises (CtsSecurity::UserAbortedException);
This method should return the passphrase typed in by the end-user (null terminator if any is ignored). Appropriate care should be taken to ensure that the user's PIN is not made visible on the user interface and not copied anywhere.
If this method is not implemented, it should return CORBA::NO_IMPLEMENT exception.
If user wants to terminate the SSL handshake which is in progress, this method should raise the UserAbortedException exception.
Default implementation of this callback always returns empty string as the password. Default implementation will be used if this method in the user callback implementation returns CORBA::NO_IMPLEMENT exception.
In this callback, interactive end-user should be prompted with the server certificate information and asked to determine if the server certificate chain can be trusted and if SSL session can proceed. User can be shown additional session information by retrieving necessary properties (such as server host, port number etc.) from the supplied SSLSessionInfo object. This callback is invoked when the internal SSL trust verification check fails to verify server's certificate chain. Internal SSL trust verification procedure performs signature verification, validity check of the entire certificate chain and verifies trust by using the trusted CA information in the Sybase PKCS11 Token (this is managed by the end-user using the Security Manager GUI). If any of the internal checks fails, this method will be invoked to determine if the interactive user would like to override the internal check and wishes to proceed with the SSL connection to the server.
CtsSecurity::TrustValue trustVerify
(
in CtsSecurity::SSLSessionInfo si,
in CtsSecurity::Reason reas
);
| Reason | Meaning |
|---|---|
| REASON_CHAIN_INCOMPLETE | Server's certificate chain is incomplete. ORB is unable to complete the chain using the CA certificates in the Sybase PKCS11 Token. |
| REASON_CHAIN_EXPIRED | Server's certificate chain expired. One or more of the certificates in the chain are not valid any more. |
| REASON_UNKNOWN_CA | Server's certificate chain contains an unknown root CA. This CA is not found in the trust data in the Sybase PKCS11 Token. |
| REASON_TRUSTDBPINNOTSET | Pin required to login into the Sybase PKCS11 token to access the trust database not supplied. Hence, trust verification not performed. |
| REASON_TRUSTDBLOGINFAILED | Pin supplied to login into Sybase PKCS11 token was incorrect. Hence trust verification not performed. |
| Return Value | Meaning |
|---|---|
| TRUST_ONCE | Server certificate chain is trusted only for this SSL connection. |
| TRUST_FAIL | Rejects the server certificate chain and terminates this SSL connection. |
| TRUST_ALWAYS | Server certificate chain is trusted always. Mark the root CA of this chain as trusted in the PKCS11 Token. |
| TRUST_NEVER | Server certificate chain is not trusted for all sessions.Reject this ssl connection and mark the root CA of this chain as not trusted in the PKCS11 token |
| TRUST_SESSION | Trust the Server certificate chain only during this client's sessions. If the client program is restarted, the certificate chain is not trusted. |
| TRUST_FAIL_SESSION | Server certificate chain is not trusted only during this client's session. The SSL connection is rejected. |
If this method is not implemented, it should raise CORBA::NO_IMPLEMENT exception.
Default implementation of this callback always returns TRUST_FAIL rejecting the server certificate chain and hence this ssl connection. Default implementation will be used if this method in the user callback implementation returns CORBA::NO_IMPLEMENT exception.