void vortex_tls_start_negociation VortexConnection connection,
gchar *  serverName,
VortexTlsActivation  process_status,
gpointer  user_data
 

Starts the TLS underlying transport security negotiation for the given connection.

This function implements the client side for the TLS profile. Inside the BEEP protocol definition, the TLS profile provides a way to secure peer to peer data transmission, allowing to take advantage of it for any profile implemented on top of the BEEP stack. TLS profile allows to secure underlying network connection using the TLS v1.0 protocol.

Here is an example on how to activate the TLS profile (details are explained after the example):

 // simple function with triggers the TLS process
 void activate_tls (VortexConnection * connection) 
 {
     // initialize and check if current vortex library supports TLS
     if (! vortex_tls_is_enabled ()) {
         g_print ("Unable to activate TLS, Vortex is not prepared\n");
         return;
     }

     // start the TLS profile negotiation process
     vortex_tls_start_negociation (connection, NULL, 
                                   process_tls_status, NULL);
 }

 // simple function with process the TLS status
 void process_tls_status (VortexConnection * connection,
                          VortexStatus       status,
                          gchar            * status_message,
                          gpointer           user_data)
 {
      switch (status) {
      case VortexOk:
           g_print ("TLS negotiation OK! over the new connection %d\n",
                    vortex_connection_get_id (connection));

           // use the new connection reference provided by 
           // this function. Connection provided at 
           // vortex_tls_start_negociation have been unrefered.
           // In this case, my_server_connection have been 
           // already unrefered by the TLS activation
           my_server_connection = connection;           

           break;
      case VortexError: 
           g_print ("TLS negotiation have failed, message: %s\n",
                    status_message);
           // ok, TLS process have failed but, do we have a connection
           // still working?. This is checked using
           if (vortex_connection_is_ok (connection, FALSE)) {
              // well we don't have TLS activated but the connection
              // still works
              my_server_connection = connection;
           } 
           break;
      }
      return;
 }

As the previous example shows, the function requires the connection where the TLS process will take place, a handler to notify the TLS status, an optional serverName string to notify listener side to act as server name and an optional user data.

While the TLS negotiation is running, user application could still perform other tasks because this function doesn't block the caller. Once the TLS process have finished, no matter its result, the status will be notified using process_status handler.

Because the TLS negotiation involves a tuning reset, the connection provided to this function will be unrefered without closing the underlying socket. This means that the connection provided at this function must be no longer used, closed or unrefered.

The connection provided at process_status handler is the one to be used once the TLS process have finished properly.

Because the TLS negotiation could fail user code placed at the process function should check if the new connection provided on that function is still working. This is because many things could fail while TLS negotiation takes place. Some of them represents protocol violation involving the connection to be closed, the others just means the TLS have failed but the connection is still valid not only to try again the TLS activation but to use it without secure transmission.

Once a connection is TLS-ficated the function just return without doing nothing, if an attempt to secure the connection is made. You could check TLS status for a given connection using vortex_connection_is_tlsficated.

Vortex Library TLS design allows to build the library enabling/disabling the TLS support. User space code doesn't need to perform any especial check than calling to vortex_tls_is_enabled function.

If previous function returns FALSE means that the Vortex Library being used have no TLS support and any call to the TLS API will perform no operation. This allows to write the same source code without worry about Vortex Library TLS built-in support.

If you need to know more about how to activate TLS support on server side (well, actually for the listener role) check out this function: vortex_tls_accept_negociation.

Additionally, you can also consider to make Vortex Library to automatically handle TLS profile negociation for every connection created. This is done by using vortex_connection_set_auto_tls function. Once activated, every call to vortex_connection_new will automatically negotiate the TLS profile once connected before notifying user space code for the connection creation. *

NOTE: As part of the TLS negotiation, all channels inside the given connection will be closed.

NOTE: The connection provided will be unrefered and a new connection will be provided by this function, but using the same underlying transport descriptor. This means the connection passed to this function and the connection created by this function will both link to the same peer but being different instances.

Parameters:
connection The connection where the secure underlying transport will be started.
serverName A server name value to be notified to the remote peer so it could react in a different way depending on this value. Function will perform a copy from the given value if it is not a NULL one. You can free the passed in value just after the function returns.
process_status A handler to be executed once the process have finished, no matter its result. This handler is required.
user_data A user defined data to be passed in to the process_status handler.