Comment changes.

[silc.git] / lib / silcske / silcske.h

diff --git a/lib/silcske/silcske.h b/lib/silcske/silcske.h
index 62880540918541e8a8ce4359e9b3d47db16921ea..50ae1d9edb440931c396393d3d5ba01c1e71cdaa 100644 (file)
--- a/lib/silcske/silcske.h
+++ b/lib/silcske/silcske.h
@@ -4,7 +4,7 @@
 
   Author: Pekka Riikonen <priikone@silcnet.org>
 
-  Copyright (C) 2000 - 2006 Pekka Riikonen
+  Copyright (C) 2000 - 2007 Pekka Riikonen
 
   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
@@ -207,6 +207,11 @@ typedef struct {
      the key exchange protocol.  Ignored without SILC_SKE_SP_FLAG_IV_INCLUDED
      flag. */
   SilcUInt16 session_port;
+
+  /* Key exchange timeout in seconds.  If key exchange is not completed in
+     this time it will timeout.  If not specified (zero), default value
+     (30 seconds) will be used. */
+  SilcUInt16 timeout_secs;
 } *SilcSKEParams, SilcSKEParamsStruct;
 /***/
 
@@ -421,7 +426,7 @@ void silc_ske_set_callbacks(SilcSKE ske,
                            SilcSKECompletionCb completed,
                            void *context);
 
-/****f* silcske/SilcSKEAPI/silc_ske_initiator_start
+/****f* silcske/SilcSKEAPI/silc_ske_initiator
  *
  * SYNOPSIS
  *
@@ -429,7 +434,7 @@ void silc_ske_set_callbacks(SilcSKE ske,
  *    silc_ske_initiator(SilcSKE ske,
  *                       SilcPacketStream stream,
  *                       SilcSKEParams params,
-                         SilcSKEStartPayload start_payload);
+ *                       SilcSKEStartPayload start_payload);
  *
  * DESCRIPTION
  *
@@ -453,11 +458,10 @@ void silc_ske_set_callbacks(SilcSKE ske,
  *    NULL on error.
  *
  ***/
-SilcAsyncOperation
-silc_ske_initiator(SilcSKE ske,
-                  SilcPacketStream stream,
-                  SilcSKEParams params,
-                  SilcSKEStartPayload start_payload);
+SilcAsyncOperation silc_ske_initiator(SilcSKE ske,
+                                     SilcPacketStream stream,
+                                     SilcSKEParams params,
+                                     SilcSKEStartPayload start_payload);
 
 /****f* silcske/SilcSKEAPI/silc_ske_responder
  *
@@ -483,20 +487,61 @@ silc_ske_initiator(SilcSKE ske,
  *    NULL on error.
  *
  ***/
-SilcAsyncOperation
-silc_ske_responder(SilcSKE ske,
-                  SilcPacketStream stream,
-                  SilcSKEParams params);
+SilcAsyncOperation silc_ske_responder(SilcSKE ske,
+                                     SilcPacketStream stream,
+                                     SilcSKEParams params);
 
-SilcAsyncOperation
-silc_ske_rekey_initiator(SilcSKE ske,
-                        SilcPacketStream stream,
-                        SilcSKERekeyMaterial rekey);
+/****f* silcske/SilcSKEAPI/silc_ske_rekey_initiator
+ *
+ * SYNOPSIS
+ *
+ *    SilcAsyncOperation
+ *    silc_ske_rekey_initiator(SilcSKE ske,
+ *                             SilcPacketStream stream,
+ *                             SilcSKERekeyMaterial rekey);
+ *
+ * DESCRIPTION
+ *
+ *    Starts SILC Key Exchange key regeneration (rekey) protocol.  The `rekey'
+ *    is the rekey material received earlier in SilcSKECompletionCb.  That
+ *    same callback is called after the rekey protocol is over to deliver new
+ *    key material and new rekey material.
+ *
+ *    This function returns SilcAsyncOperation operation context which can
+ *    be used to control the protocol from the application.  Application may
+ *    for example safely abort the protocol at any point, if needed.  Returns
+ *    NULL on error.
+ *
+ ***/
+SilcAsyncOperation silc_ske_rekey_initiator(SilcSKE ske,
+                                           SilcPacketStream stream,
+                                           SilcSKERekeyMaterial rekey);
 
-SilcAsyncOperation
-silc_ske_rekey_responder(SilcSKE ske,
-                        SilcPacketStream stream,
-                        SilcSKERekeyMaterial rekey);
+/****f* silcske/SilcSKEAPI/silc_ske_rekey_responder
+ *
+ * SYNOPSIS
+ *
+ *    SilcAsyncOperation
+ *    silc_ske_rekey_responder(SilcSKE ske,
+ *                             SilcPacketStream stream,
+ *                             SilcSKERekeyMaterial rekey);
+ *
+ * DESCRIPTION
+ *
+ *    Starts SILC Key Exchange key regeneration (rekey) protocol as responder.
+ *    The `rekey' is the rekey material received earlier in
+ *    SilcSKECompletionCb.  That same callback is called after the rekey
+ *    protocol is over to deliver new key material and new rekey material.
+ *
+ *    This function returns SilcAsyncOperation operation context which can
+ *    be used to control the protocol from the application.  Application may
+ *    for example safely abort the protocol at any point, if needed.  Returns
+ *    NULL on error.
+ *
+ ***/
+SilcAsyncOperation silc_ske_rekey_responder(SilcSKE ske,
+                                           SilcPacketStream stream,
+                                           SilcSKERekeyMaterial rekey);
 
 /****f* silcske/SilcSKEAPI/silc_ske_set_keys
  *
@@ -619,7 +664,7 @@ silc_ske_process_key_material_data(unsigned char *data,
  ***/
 void silc_ske_free_key_material(SilcSKEKeyMaterial key);
 
-/****f* silcske/SilcSKEAPI/silc_ske_free_key_material
+/****f* silcske/SilcSKEAPI/silc_ske_free_rekey_material
  *
  * SYNOPSIS
  *