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.
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
typedef void (*PFNNEGHANDLER)( void *pv, SSLInfo *psi, IWebOpts *piOpts, int *pnResultCode, AEECallback *pcb);