Send correct context in completion callback.

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

diff --git a/lib/silcske/silcske.h b/lib/silcske/silcske.h
index 42d9bc635648738561b30b3b36991b4171005e7f..98d3f63a5c983319a8dfe293fafd3d86720f808a 100644 (file)
--- a/lib/silcske/silcske.h
+++ b/lib/silcske/silcske.h
@@ -122,6 +122,8 @@ typedef struct {
   SilcHmac hmac;                        /* Selected HMAC */
   SilcHash hash;                        /* Selected hash algorithm */
   SilcPublicKey public_key;              /* Remote public key */
+  SilcUInt16 remote_port;               /* Remote port, set when IV Included
+                                           set and using UDP/IP */
 } *SilcSKESecurityProperties;
 /***/
 
@@ -134,7 +136,7 @@ typedef struct {
  * DESCRIPTION
  *
  *    This is the key material structure, and is passed as argument by the
- *    application to silc_ske_process_key_material* functions. It includes
+ *    application to silc_ske_process_key_material_data function. It includes
  *    the processed key material which can be used as SILC session keys.
  *
  * SOURCE
@@ -243,11 +245,7 @@ typedef enum {
  *
  *    Completion callback that will be called when the public key
  *    has been verified.  The `status' will indicate whether the public
- *    key were trusted or not. If the `status' is PENDING then the status
- *    is not considered to be available at this moment. In this case the
- *    SKE libary will assume that the caller will call this callback again
- *    when the status is available. See silc_ske_set_callbacks for more
- *    information.
+ *    key were trusted or not.
  *
  ***/
 typedef void (*SilcSKEVerifyCbCompletion)(SilcSKE ske,
@@ -341,7 +339,9 @@ typedef void (*SilcSKECompletionCb)(SilcSKE ske,
  *    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.
+ *    during the key exchange.  Giving `private_key' is optional if the
+ *    SILC_SKE_SP_FLAG_MUTUAL is not set and you are initiator.  For
+ *    responder both `public_key' and `private_key' must be set.
  *
  * EXMPALE
  *
@@ -422,10 +422,10 @@ void silc_ske_set_callbacks(SilcSKE ske,
  * SYNOPSIS
  *
  *    SilcAsyncOperation
- *    silc_ske_initiator_start(SilcSKE ske,
- *                             SilcPacketStream stream,
- *                             SilcSKEParams params,
- *                             SilcSKEStartPayload start_payload);
+ *    silc_ske_initiator(SilcSKE ske,
+ *                       SilcPacketStream stream,
+ *                       SilcSKEParams params,
+                         SilcSKEStartPayload start_payload);
  *
  * DESCRIPTION
  *
@@ -433,8 +433,9 @@ void silc_ske_set_callbacks(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 it must be provided.
+ *    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.
  *
  *    If the `start_payload' is NULL the library will generate it
  *    automatically.  Caller may provide it if it wants to send its own
@@ -459,9 +460,9 @@ silc_ske_initiator(SilcSKE ske,
  * SYNOPSIS
  *
  *    SilcAsyncOperation
- *    silc_ske_responder_start(SilcSKE ske,
- *                             SilcPacketStream stream,
- *                             SilcSKEParams params);
+ *    silc_ske_responder(SilcSKE ske,
+ *                       SilcPacketStream stream,
+ *                       SilcSKEParams params);
  *
  * DESCRIPTION
  *
@@ -494,7 +495,7 @@ silc_ske_rekey_responder(SilcSKE ske,
                         SilcBuffer ke_payload,
                         SilcSKERekeyMaterial rekey);
 
-/****f* silcske/SilcSKEAPI/silc_ske_assemble_security_properties
+/****f* silcske/SilcSKEAPI/silc_ske_set_keys
  *
  * SYNOPSIS
  *
@@ -538,7 +539,8 @@ SilcBool silc_ske_set_keys(SilcSKE ske,
  *
  * DESCRIPTION
  *
- *    Utility function to parse the remote host's version string.
+ *    Utility function to parse the remote host's version string.  This can
+ *    be called after the key exchange has been completed.
  *
  ***/
 SilcBool silc_ske_parse_version(SilcSKE ske,
@@ -548,6 +550,57 @@ SilcBool silc_ske_parse_version(SilcSKE ske,
                                char **software_version_string,
                                char **vendor_version);
 
+/****f* silcske/SilcSKEAPI/silc_ske_get_security_properties
+ *
+ * SYNOPSIS
+ *
+ *    SilcSKESecurityProperties silc_ske_get_security_properties(SilcSKE ske);
+ *
+ * DESCRIPTION
+ *
+ *    Returns negotiated security properties from the `ske' or NULL if they
+ *    have not yet been negotiated.  This may be called to retrieve the
+ *    security properties after the SilcSKECompletionCb has been called.
+ *
+ ***/
+SilcSKESecurityProperties silc_ske_get_security_properties(SilcSKE ske);
+
+/****f* silcske/SilcSKEAPI/silc_ske_process_key_material_data
+ *
+ * SYNOPSIS
+ *
+ *    const char *silc_ske_map_status(SilcSKEStatus status);
+ *
+ * DESCRIPTION
+ *
+ *    Utility function to process key data `data' in the way specified
+ *    by the SILC Key Exchange protocol.  This returns the processed key
+ *    material or NULL on error.  Caller must free the returned key
+ *    material context by calling silc_ske_free_key_material.
+ *
+ ***/
+SilcSKEKeyMaterial
+silc_ske_process_key_material_data(unsigned char *data,
+                                  SilcUInt32 data_len,
+                                  SilcUInt32 req_iv_len,
+                                  SilcUInt32 req_enc_key_len,
+                                  SilcUInt32 req_hmac_key_len,
+                                  SilcHash hash);
+
+/****f* silcske/SilcSKEAPI/silc_ske_free_key_material
+ *
+ * SYNOPSIS
+ *
+ *    void silc_ske_free_key_material(SilcSKEKeyMaterial key)
+ *
+ * DESCRIPTION
+ *
+ *    Utility function to free the key material created by calling
+ *    silc_ske_process_key_material_data.
+ *
+ ***/
+void silc_ske_free_key_material(SilcSKEKeyMaterial key);
+
 /****f* silcske/SilcSKEAPI/silc_ske_map_status
  *
  * SYNOPSIS