tfSslServerUserCreate

Table of Contents >> SSL Programmer's Reference

#include <trsocket.h>

int tfSslServerUserCreate

(int socketDescriptor);

Function Description

tfSslServerUserCreate() is used to create SSL server states. If user sets socket option to enable SSL server functionality BEFORE the TCP handshake, (by calling setsockopt() on the listening socket with TCP options TM_TCP_SSL_SERVER and TM_TCP_ SSLSESSION), user does NOT need to make this call, because after the TCP handshake SSL server states will be automatically created.

tfSslServerUserCreate() must be called if user wants to enable SSL server functionality AFTER the TCP handshake. The calling sequence is that, after TCP handshake finishes, user calls setsockopt() on the accepted socket with TCP options TM_TCP_SSL_SERVER and TM_TCP_SSLSESSION, and then user needs to call tfSslServerUserCreate().

This function is only valid when TM_USE_SSL_SERVER is defined. And please note that if the user sets SSL functionality before TCP handshake, LISTENING socket should be used when calling setsockopt(); if user sets SSL functionality after TCP handshake, the ACCEPTED socket should be used when calling setsockopt() and tfSslServerUserCreate().

Parameters

• socketDescriptor

  socket number

Returns

• TM_ENOERROR

  Success

• TM_ENOBUFS

  No more buffer available

• TM_EPERM

  Function call not permitted, check if TM_TCP_SSLSESSION and TM_TCP_SSL_SERVER are both set on this socket

• TM_EPROTONOTSUPP

  The socket is not a TCP socket

• TM_EBADF

  Socket pointer is not found

• TM_SOCKET_ERROR

  Error.

Note:

TM_SOCKET_ERROR means that this socket call has failed and the errorCode has been set on the socket itself. To retrieve the socket error the user must call tfGetSocketError(socketDescriptor).

Example

 
{
...
    int         value;
/*1. Add certificate to server */
    errorCode = tfUsePki();
    assert(errorCode == TM_ENOERROR);
 
    errorCode = AddServerCertificateFunction();
assert( errorCode == TM_ENOERROR);
 
/*2. Enable SSL */
    errorCode = tfUseSsl(16);
    assert(errorCode == TM_ENOERROR);
 
/*3. Open a new server session, if ephemeral RSA key is needed, we need to add ephemeral RSA key pair to this session
 */
    serverSessionId = tfSslNewSession(
                            serverCertId,
                            16,
                            serverVersion,
                            option);
    assert(serverSessionId != -1);
 
/*4. Create IPv4 server listening socket, make a normal TCP connection. A normal TCP connection has been made on socket acceptSd. Note that, so far, no SSL option is enabled on these sockets.  
    GetATcpConnection(&serverListeningSd, &acceptSd, AF_INET);
 
/*5. A normal TCP channel has been established. You already have an accepted socket: acceptSd, you should be able to send and recv normal TCP data through socket acceptSd*/
    tfxExcerciseChannel(acceptSd, ...    );
 
/*6. Enable SSL server on socket acceptSd */
    value = 1;
    errorCode = setsockopt (acceptSd, IP_PROTOTCP, TM_TCP_SSL_SERVER,
                           (const char TM_FAR *) &value, sizeof (int));
    assert(errorCode == TM_ENOERROR); 
 
    value = serverSessionId;
    errorCode = setsockopt (acceptSd, IP_PROTOTCP, TM_TCP_SSLSESSION,
                           (const char TM_FAR *) &value, sizeof (int));
    assert(errorCode == TM_ENOERROR); 
 
/*7. Create an SSL server state on a given socket on which TM_TCP_SSL_SERVER and TM_TCP_SSLSESSION must have been set */
    errorCode = tfSslServerUserCreate(acceptSd);
    assert(errorCode == TM_ENOERROR); 
 
/*8. You need to do similar things on your client part to enhance a normal TCP client socket to be SSL-enabled client socket. For the Treck product, the SSL negotiation happens when you call tfSslClientUserStart on this SSL client socket */
 
/*9. SSL negotiation finished... Now you should be able to send and recv SSL encrypted data in this socket. Note that Treck uses the same send(), recv() api to send and receive SSL data and normal TCP data
 */
    tfxExcerciseChannel(acceptSd, ...    );
 
/*10. After a while, you may want to close SSL layer */
    tfSslConnectUserClose(acceptSd);
/*11. You need to do similar things on your client part to disable SSL so that you downgrade an SSL-enabled client socket to normal TCP socket)
 */
 
/*12. You should be able to send and recv normal TCP data again. */
    tfxExcerciseChannel(acceptSd, ...);
 
/*13. go back to step 7 to call tfSslServerUserCreate if you want to enable SSL again ...*/
…
}
 

Table of Contents >> SSL Programmer's Reference