707394 - Document which libssl functions give correct results from within which libssl callback

Status: RESOLVED INACTIVE

(NSS :: Libraries, defect, P5)

Description

[Brian Smith (:briansmith, :bsmith, use NEEDINFO?)]

(In reply to Brian Smith (:bsmith) from Bug 681839 comment 4)
> (In reply to Wan-Teh Chang from comment #3)
> > For example, when calling SSL_HandshakeNegotiatedExtension in the client
> > authentication callback, the caller knows the handshake is still in 
> > progress based on the knowledge of the SSL handshake process.
> 
> What about uses outside of the callback functions? Should we just consider
> that to be misuse of the API? If so, then I think we should document which
> functions are only allowed to be called from within callbacks.

Now I see that it is definitely the case that SSL_HandshakeNegotiatedExtension, SSL_GetChannelInfo, SSL_PeerCertificate, etc. should only be called from within callbacks. That is why these functions don't and can't take locks; in callbacks, these locks are already taken. (The various "need locks" comments in the source for these functions are misleading.) Plus, if you were to call these functions when a renegotiation takes place (or could take place), outside of a callback, then you will get undefined results--sometimes you will get results from the previous handshake, and sometimes you will get results from the current renegotiation handshake.

We should document which callbacks can call which functions (e.g. SSL_HandshakeNegotiatedExtension can be called from the AuthCertificate callback, the HandshakeCallback, or the GetClientAuthData callback; SSL_GetChannelInfo can only be called from within the HandshakeCallback), that they return undefined results when called from outside of these documented callbacks, and that they can't be relied upon to figure out if a handshake has been completed.

I think the current situation is something like this:

SSL_PeerCertificate:
Only gives reliable results when called by the auth certificate callback, the bad cert hook, the client auth data callback, and/or the handshake callback.

SSL_RevealCert: this should be deprecated; it is the same exact logic as SSL_PeerCertificate.

SSL_SecurityStatus:
Only gives reliable results when called by the handshake callback.

SSL_GetChannelInfo:
Only gives reliable results when called by the handshake callback.

SSL_GetNegotiatedHostInfo: For clients, this is basically just like SSL_RevealURL; for servers, it should give reliable when called by the auth certificate callback, the bad cert hook, the client auth data callback, and/or the handshake callback.

SSL_LocalCertificate: This function is documented to return the "most recently sent" certificate, so technically it can return reliable results for all callbacks, but practically it returns reliable results only in the handshake callback for clients, and in the handshake callback, auth certificate callback, or bad cert hook for servers.

SSL_HandshakeNegotiatedExtension: This function can (be made to) return reliable results when called by the auth certificate callback, the client auth data callback, the bad cert hook, or the handshake callback.