void vortex_tls_start_negotiation ( VortexConnection connection,
const char *  serverName,
VortexTlsActivation  process_status,
axlPointer  user_data 
)

Starts the TLS transport security negotiation on 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 from any profile implemented on top of the BEEP stack. TLS profile allows to secure 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):

1 // simple function with triggers the TLS process
2 void activate_tls (VortexCtx * ctx, VortexConnection * connection)
3 {
4  // initialize and check if current vortex library supports TLS
5  if (! vortex_tls_init (ctx)) {
6  printf ("Unable to activate TLS, Vortex is not prepared\n");
7  return;
8  }
9 
10  // start the TLS profile negotiation process
11  vortex_tls_start_negotiation (ctx, connection, NULL,
12  process_tls_status, NULL);
13 }
14 
15 // simple function with process the TLS status
16 void process_tls_status (VortexConnection * connection,
17  VortexStatus status,
18  char * status_message,
19  axlPointer user_data)
20 {
21  switch (status) {
22  case VortexOk:
23  printf ("TLS negotiation OK! over the new connection %d\n",
24  vortex_connection_get_id (connection));
25 
26  // use the new connection reference provided by
27  // this function. Connection provided at
28  // vortex_tls_start_negotiation have been unrefered.
29  // In this case, my_server_connection have been
30  // already unrefered by the TLS activation
31  my_server_connection = connection;
32 
33  break;
34  case VortexError:
35  printf ("TLS negotiation have failed, message: %s\n",
36  status_message);
37  // ok, TLS process have failed but, do we have a connection
38  // still working?. This is checked using
39  if (vortex_connection_is_ok (connection, axl_false)) {
40  // well we don't have TLS activated but the connection
41  // still works
42  my_server_connection = connection;
43  }
44  break;
45  }
46  return;
47 }

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 a particular 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 associated socket. This means that the connection provided to this function must be no longer used, closed or unrefered. No transfer operation must take place during the TLS activation.

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 TLS is activated on a connection the function just returns without doing nothing, if an attempt to secure the connection is made again. You could check TLS status for a given connection using vortex_connection_is_tlsficated.

A call to vortex_tls_init is required to start the TLS context inside the provided VortexCtx. Next calls won't perform any operation more than returning axl_true (signaling the library is/was initialized).

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_negotiation.

Additionally, you can also consider to make Vortex Library to automatically handle TLS profile negotiation for every connection created. This is done by using vortex_tls_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.

NOTE2: The connection provided will be unrefered and a new connection will be provided by this function, but using the same associated transport descriptor (socket). 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.

NOTE3: Note also that any data configured with vortex_connection_set_data and vortex_connection_set_data_full is transferred transparently from the old to the new connection so this application level data is available into the new connection. Consider that this internal storage is also used by the vortex engine itself so it is required to do this transfer.

Parameters
connectionThe connection where the secure transport will be started.
serverNameA 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. You can free the passed in value just after the function returns. Keep in mind that this value will be ignored by remote BEEP peer in the case the serverName was already declared/setup by a previous channel opened in this BEEP connection (VortexConnection). If your protocol design has a channel creation that goes first to TLS profile activation, then pass NULL to this function to leave control to serverName selection to the first channel created on this connection.
process_statusA handler to be executed once the process have finished, no matter its result. This handler is required. Note that not provided this handler the function will return without doing nothing silently.
user_dataA user defined data to be passed in to the process_status handler.

References vortex_connection_get_ctx(), vortex_connection_is_ok(), vortex_connection_is_profile_supported(), vortex_connection_is_tlsficated(), vortex_thread_pool_new_task(), VORTEX_TLS_PROFILE_URI, VortexError, and VortexOk.

Referenced by vortex_tls_start_negotiation_sync().