tfSslRegisterCertificateCB

Table of Contents >> SSL Programmer's Reference

#include <trsocket.h>

int tfSslRegisterCertificateCB	(
	int sessionId,
	ttSslCertCallbackFuncPtr certCBFuncPtr
	);

Function Description

This function is provided so that users have access to the client/server certificates during SSL session negotiation. If no callback function is registered, the stack itself determines how to treat a certificate using the default rules, for example: deny any certificate without known CA, deny any certificate without valid lifetime, deny the leaf certificate which doesn’t have the same common name as we expected. If callback function is registered, all certificates will be passed to user in a ttCertificateEntry array, and user determines how to handle the certificates, and let the stack know the decision by the return value of this call back function. Note that, if the certificate is determined by the stack to be a bad one (fatal error), user’s instruction will be ignored by the stack.

Parameters

• sessionId

  The session Id which the callback function will bind to

• certCBFuncPtr

  Callback function pointer, of type ttSslCertCallbackFuncPtr

Related Structures

 
typedef int (TM_CODE_FAR *ttSslCertCallbackFuncPtr)(
                        int                         sessionId,
                        int                         sockDescriptor,
                        ttCertificateEntryPtr       entryArray,
                        int                         arraySize);
 

Description: The callback function will take a ttCertificateEntryPtr type pointer entryArray which points to the start of certificate array. Each item in the array corresponds to one certificate, and arraySize tells how many items (certificates) in the array. All certificates in the certificate chain will be passed to user all at once. Return Value: The callback function returns either TM_ENOERROR to indicate ignoring any uncritical error, or TM_EINVAL to indicate denying this certificate chain. Note that, the return value applies to the whole certificate chain, not to any individual one.

Important Note: The call back function will be triggered in TCP receiving path, and the stack waits for user’s response regarding how to process the certificates. The sessionId and sockDescriptor are passed in just for the convenience of user so that user may associate this call back to the right sessionId/sockDescriptor. We don’t support any function call, or socket API calls using the sessionId/sockDescriptor in this call back function.

 
typedef struct tsCertificateEntry{
    const char TM_FAR * certDataPtr;/* points to the start point of raw certificate, user can only read on this buffer or copy to user’s own buffer. When the call back function 
                                     returns, user should not assume the persistence of this buffer pointer */
    int		      certLength;   /* length of raw certificate */
    int		      certFlags	    /* flag to indicate status of this certificate */
}ttCertificateEntry;
typedef ttCertificateEntry TM_FAR * ttCertificateEntryPtr;
 

Description: For certFlags, currently, we support the following value

   TM_CERTFLAG_BADCERT      /* critical error! */
   TM_CERTFLAG_REVOKED	     /* revoked cert    */
   TM_CERTFLAG_EXPIRED	     /* expired cert    */
   TM_CERTFLAG_UNMATCHED    /* the certificate doesn’t belong to the identity we are used to verify*/
   TM_CERTFLAG_UNKNOWNCA    /* CA unknown      */

Returns

• TM_ENOERROR

  Callback function is successfully registered

• TM_EINVAL

  Invalid session Id.

Table of Contents >> SSL Programmer's Reference