Added support for SilcSKR in SKE for finding public keys.

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

diff --git a/lib/silcske/silcske.h b/lib/silcske/silcske.h
index ffe9f7c4d521ca7fa9eb3ac933b8ab9e5539e616..04c69986643208a98bd75a5d10584ec52e87471e 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 - 2005 Pekka Riikonen
+  Copyright (C) 2000 - 2006 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
@@ -228,7 +228,6 @@ typedef void (*SilcSKEVerifyCbCompletion)(SilcSKE ske,
  * SYNOPSIS
  *
  *    typedef void (*SilcSKEVerifyCb)(SilcSKE ske,
- *                                    SilcSKEPKType pk_type,
  *                                    SilcPublicKey public_key,
  *                                    void *context,
  *                                    SilcSKEVerifyCbCompletion completion,
@@ -243,9 +242,11 @@ typedef void (*SilcSKEVerifyCbCompletion)(SilcSKE ske,
  *    arugment to silc_ske_set_callbacks.  See silc_ske_set_callbacks for
  *    more information.
  *
+ *    If the key repository was provided in silc_ske_alloc this callback
+ *    is called only if the public key was not found from the repository.
+ *
  ***/
 typedef void (*SilcSKEVerifyCb)(SilcSKE ske,
-                               SilcSKEPKType pk_type,
                                SilcPublicKey public_key,
                                void *context,
                                SilcSKEVerifyCbCompletion completion,
@@ -288,7 +289,7 @@ typedef void (*SilcSKECompletionCb)(SilcSKE ske,
  * SYNOPSIS
  *
  *    SilcSKE silc_ske_alloc(SilcRng rng, SilcSchedule schedule,
- *                           SilcPublicKey public_key,
+ *                           SilcSKR repository, SilcPublicKey public_key,
  *                           SilcPrivateKey private_key, void *context);
  *
  * DESCRIPTION
@@ -302,21 +303,30 @@ typedef void (*SilcSKECompletionCb)(SilcSKE ske,
  *    SKE session context is allocated application must call the
  *    silc_ske_set_callbacks.
  *
+ *    If the `repository' is non-NULL then the remote's public key will be
+ *    verified from the repository.  If it is not provided then the
+ *    SilcSKEVerifyCb callback must be set, and it will be called to
+ *    verify the key.  If both `repository' and the callback is provided the
+ *    callback is called only if the key is not found from the repository.
+ *
+ *    The `public_key' and `private_key' is the caller's identity used
+ *    during the key exchange.
+ *
  * EXMPALE
  *
  *    // Initiator example
- *    ske = silc_ske_alloc(rng, scheduler, app);
+ *    ske = silc_ske_alloc(rng, scheduler, NULL, pk, prv, app);
  *    silc_ske_set_callbacks(ske, verify_public_key, completion, app);
  *    start_payload =
  *      silc_ske_assemble_security_properties(ske, SILC_SKE_SP_FLAG_PFS |
  *                                            SILC_SKE_SP_FLAG_MUTUAL,
  *                                            version);
- *    silc_ske_initiator_start(ske);
+ *    silc_ske_initiator_start(ske, stream, start_payload);
  *
  ***/
 SilcSKE silc_ske_alloc(SilcRng rng, SilcSchedule schedule,
-                      SilcPublicKey public_key, SilcPrivateKey private_key,
-                      void *context);
+                      SilcSKR repository, SilcPublicKey public_key,
+                      SilcPrivateKey private_key, void *context);
 
 /****f* silcske/SilcSKEAPI/silc_ske_free
  *
@@ -391,13 +401,9 @@ void silc_ske_set_callbacks(SilcSKE ske,
  *
  *    Starts the SILC Key Exchange protocol as initiator.  The completion
  *    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.  Note that
- *    SKE library will take over the packet stream `stream' while the
- *    protocol is in process.  The application will not receive any packets
- *    for `stream' after this function is called.  The `stream' is turned
- *    over to application once the completion callback is called.
+ *    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 `start_payload' includes all configured security properties that
  *    will be sent to the responder.  The `start_payload' must be provided.
@@ -431,13 +437,9 @@ silc_ske_initiator(SilcSKE ske,
  *
  *    Starts SILC Key Exchange protocol as responder.  The completion
  *    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.  Note that
- *    SKE library will take over the packet stream `stream' while the
- *    protocol is in process.  The application will not receive any packets
- *    for `stream' after this function is called.  The `stream' is turned
- *    over to application once the completion callback is called.
+ *    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 `version' is the responder's SILC protocol version that will be
  *    sent in reply to the initiator.  The `flags' indicates the