Merged silc_1_1_branch to trunk.

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

diff --git a/lib/silcske/silcske.h b/lib/silcske/silcske.h
index 92bf621856a5c28c9f8e8c9ad7c11cd05ac1c711..9c637de61942b32f1654f903312ed80bea8529c5 100644 (file)
--- a/lib/silcske/silcske.h
+++ b/lib/silcske/silcske.h
@@ -116,7 +116,7 @@ typedef enum {
  *
  * SOURCE
  */
-typedef struct {
+typedef struct SilcSKESecurityPropertiesStruct {
   SilcSKESecurityPropertyFlag flags;    /* Flags */
   SilcSKEDiffieHellmanGroup group;      /* Selected Diffie Hellman group */
   SilcCipher cipher;                    /* Selected cipher */
@@ -142,16 +142,16 @@ typedef struct {
  *
  * SOURCE
  */
-typedef struct {
+typedef struct SilcSKEKeyMaterialStruct {
   unsigned char *send_iv;
   unsigned char *receive_iv;
   SilcUInt32 iv_len;
   unsigned char *send_enc_key;
   unsigned char *receive_enc_key;
-  SilcUInt32 enc_key_len;
+  SilcUInt32 enc_key_len;             /* Key length in bits */
   unsigned char *send_hmac_key;
   unsigned char *receive_hmac_key;
-  SilcUInt32 hmac_key_len;
+  SilcUInt32 hmac_key_len;            /* Key length in bytes */
 } *SilcSKEKeyMaterial;
 /***/
 
@@ -171,7 +171,7 @@ typedef struct {
  *    function.
  *
  ***/
-typedef struct {
+typedef struct SilcSKERekeyMaterialStruct {
   unsigned char *send_enc_key;
   char *hash;
   unsigned int enc_key_len  : 23;
@@ -192,7 +192,7 @@ typedef struct {
  *
  * SOURCE
  */
-typedef struct {
+typedef struct SilcSKEParamsObject {
   /* The SKE version string that is sent to the remote end.  This field
      must be set.  Caller must free the pointer. */
   char *version;
@@ -352,6 +352,10 @@ typedef void (*SilcSKECompletionCb)(SilcSKE ske,
  *    SILC_SKE_SP_FLAG_MUTUAL is not set and you are initiator.  For
  *    responder both `public_key' and `private_key' must be set.
  *
+ *    When allocating SKE session for rekey, the `repository' and `private_key'
+ *    pointers must be NULL and the SilcSKEVerifyCb callback must not be
+ *    set with silc_ske_set_callbacks.
+ *
  * EXMPALE
  *
  *    // Initiator example
@@ -359,7 +363,7 @@ typedef void (*SilcSKECompletionCb)(SilcSKE ske,
  *    params.flags = SILC_SKE_SP_FLAG_PFS | SILC_SKE_SP_FLAG_MUTUAL;
  *    ske = silc_ske_alloc(rng, scheduler, NULL, pk, prv, app);
  *    silc_ske_set_callbacks(ske, verify_public_key, completion, app);
- *    silc_ske_initiator_start(ske, stream, &params, NULL);
+ *    silc_ske_initiator(ske, stream, &params, NULL);
  *
  ***/
 SilcSKE silc_ske_alloc(SilcRng rng, SilcSchedule schedule,
@@ -426,7 +430,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
  *
@@ -434,7 +438,7 @@ void silc_ske_set_callbacks(SilcSKE ske,
  *    silc_ske_initiator(SilcSKE ske,
  *                       SilcPacketStream stream,
  *                       SilcSKEParams params,
-                         SilcSKEStartPayload start_payload);
+ *                       SilcSKEStartPayload start_payload);
  *
  * DESCRIPTION
  *
@@ -443,8 +447,9 @@ void silc_ske_set_callbacks(SilcSKE ske,
  *    the protocol has completed.  The `stream' is the network connection
  *    to the remote host.  The SKE library will handle all key exchange
  *    packets sent and received in the `stream' connection.  The library will
- *    also set the remote host's ID automatically to the `stream'.  The
- *    `params' include SKE parameters, and it must be provided.
+ *    also set the remote host's ID automatically to the `stream' if it is
+ *    present in the exchanged packets.  The `params' include SKE parameters,
+ *    and it must be provided.
  *
  *    If the `start_payload' is NULL the library will generate it
  *    automatically.  Caller may provide it if it wants to send its own
@@ -458,11 +463,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
  *
@@ -479,8 +483,10 @@ silc_ske_initiator(SilcSKE ske,
  *    callback that was set in silc_ske_set_callbacks will be called once
  *    the protocol has completed.  The `stream' is the network connection
  *    to the remote host.  The SKE library will handle all key exchange
- *    packets sent and received in the `stream' connection.  The `params'
- *    include SKE parameters, and must be provided.
+ *    packets sent and received in the `stream' connection.  The library will
+ *    also set the remote hosts's ID automatically to the `stream' if it is
+ *    present in the exchanged packets.  The `params' include SKE parameters,
+ *    and must be provided.
  *
  *    This function returns SilcAsyncOperation operation context which can
  *    be used to control the protocol from the application.  Application may
@@ -488,20 +494,73 @@ 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.  When the rekey is completed the
+ *    SKE library will automatically update the new keys into `stream'.  The
+ *    completion callback is called after the new keys has been taken into
+ *    use.
+ *
+ *    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,
+ *                             SilcPacket packet);
+ *
+ * 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.
+ *    When the rekey is completed the SKE library will automatically update
+ *    the new keys into `stream'.  The completion callback is called after
+ *    the new keys has been taken into use.
+ *
+ *    The `packet' is the SILC_PACKET_REKEY received to start the rekey
+ *    protocol.  If `packet' is NULL it is assumed that the packet will be
+ *    received from the `stream'.
+ *
+ *    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,
+                                           SilcPacket packet);
 
 /****f* silcske/SilcSKEAPI/silc_ske_set_keys
  *
@@ -624,7 +683,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
  *