Developer

API Reference

NegotiateHandler

Brew Release
Brew MP 1.0.2
See Also
ISSL_Negotiate(), ISSL_Renegotiate()
Description
The Negotiate handler is a function set by the client, which is called when ISSL needs more information to continue.
During the SSL handshake, ISSL may need more information such as 1. Trust checking Options (overriding certain errors, etc.) 2. Client certificate based upon the server supplied list of CA DNs
The Negotiate handler is called with appropriate error code in the SSLInfo to inform the user. Once the client supplies relevant information (through setting WebOpts on the given piOpts interface), the handshake is continued after the client resumes the given callback pcb.
The Negotiate handler is also called sometimes to inform the client of the progress. When called as such, the pcb and pnResultCode are NULL, as there is no need to resume the ISSL operation. For example, when ISSL successfully completes a handshake, it informs the client by the handler.
The negotiation handler may also be called when the server triggers a renegotiation, or a negotiation is initiated by reading or writing directly to the secure socket/port instead of calling ISSL_Negotiate. Since this type of negotiation happens independently from a ISSL_Negotiation call, none of the WebOpts which might have been supplied in the ISSL_Negotiation is available. The negotiation handler must be able to provide the WebOpts, or the WebOpts may be provided before the negotiation using ISSL_AddOpt. If the negotiation hander may change the trust settings or add root certs, it is necessary that WEBOPT_SSL_TRUST_MODE is set with ISSL_AddOpt, otherwise the default value of SSL_TRUST_MODE_FAIL will prevent the negotiation handler from being called for more information.
If the client would like to continue the ISSL operation (by supplying more information or just to continue), set the ResultCode to SUCCESS. Any error code set here, aborts the ISSL operation.
Members
  • pv:               User data as supplied by the web opt 
                         WEBOPT_SSL_NEGOTIATE_HANDLER_DATA
  • SSLInfo:          The current result SSL negotiation
  • piOpts:           Any new webopts will be added to this object
  • pnResultCode:     The error code set by the user.  
                         Set to SUCCESS to continue negotiation
  • pcb:              Callback that needs to be resumed to 
                         continue with the negotiation
    
Definition
   typedef void (*PFNNEGHANDLER)( void *pv, SSLInfo *psi, IWebOpts *piOpts, 
                                  int *pnResultCode, AEECallback *pcb);
Comment

NegotiateHandler is a function that is called by ISSL, when it needs more information from the user or a particular error needs to be overridden. This function is set by WEBOPT_SSL_NEGOTIATE_HANDLER and its data argument(pv) is set by WEBOPT_SSL_NEGOTIATE_HANDLER_DATA.
Currently, this functions gets called for trust overrides and client authentication. On client authentication, the supplied IWebOpts contains the server's Certificate Authorities Distinguished Names list (see WEBOPT_SSL_CA_DN_CERT_TYPES and WEBOPT_SSL_CA_DN or WEBOPT_SSL_CA_DN_LIST) and the negotiation handler always gets called so as to give a chance to the client to supply the correct client certificate based on the DN list.
If the error is successfully handled, set the *pnResult code to SUCCESS. If client wishes to abort the handshake, set the *pnResultCode to EFAILED. Always resume the pcb when it is given (is non-null).
This function is also called during renegotiation.
  • Follow