-SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng,
- SilcSocketConnection sock,
- SilcSKEStartPayload *start_payload,
- SilcSKESendPacketCb send_packet,
- void *context);
-SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske,
- SilcBuffer start_payload,
- SilcSKECb callback,
- void *context);
-SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske,
- SilcPublicKey public_key,
- SilcSKESendPacketCb send_packet,
- void *context);
-SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
- SilcBuffer ke2_payload,
- SilcSKEVerifyCb verify_key,
- void *verify_context,
- SilcSKECb callback,
- void *context);
-SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
- SilcSocketConnection sock,
- char *version,
- SilcBuffer start_payload,
- SilcSKECb callback,
- void *context);
-SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske,
- SilcSKEStartPayload *start_payload,
- SilcSKESendPacketCb send_packet,
- void *context);
-SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
- SilcBuffer ke1_payload,
- SilcSKECb callback,
- void *context);
-SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
- SilcPublicKey public_key,
- SilcPrivateKey private_key,
- SilcSKEPKType pk_type,
- SilcSKESendPacketCb send_packet,
- void *context);
-SilcSKEStatus silc_ske_end(SilcSKE ske,
- SilcSKESendPacketCb send_packet,
- void *context);
-SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status,
- SilcSKESendPacketCb send_packet,
- void *context);
-SilcSKEStatus
-silc_ske_assemble_security_properties(SilcSKE ske,
- unsigned char flags,
- char *version,
- SilcSKEStartPayload **return_payload);
-SilcSKEStatus
-silc_ske_select_security_properties(SilcSKE ske,
- char *version,
- SilcSKEStartPayload *payload,
- SilcSKEStartPayload *remote_payload);
-SilcSKEStatus silc_ske_create_rnd(SilcSKE ske, SilcInt n,
- unsigned int len,
- SilcInt *rnd);
-SilcSKEStatus silc_ske_make_hash(SilcSKE ske,
- unsigned char *return_hash,
- unsigned int *return_hash_len);
-SilcSKEStatus
+
+/****f* silcske/SilcSKEAPI/silc_ske_get_context
+ *
+ * SYNOPSIS
+ *
+ * void *silc_ske_get_context(SilcSKE ske);
+ *
+ * DESCRIPTION
+ *
+ * Returns the context that was given as argument to silc_ske_alloc.
+ *
+ ***/
+void *silc_ske_get_context(SilcSKE ske);
+
+/****f* silcske/SilcSKEAPI/silc_ske_set_callbacks
+ *
+ * SYNOPSIS
+ *
+ * void silc_ske_set_callbacks(SilcSKE ske,
+ * SilcSKEVerifyCb verify_key,
+ * SilcSKECompletion completed,
+ * void *context);
+ *
+ * DESCRIPTION
+ *
+ * Sets the callback functions for the SKE session.
+ *
+ * The `verify_key' callback is called to verify the received public key
+ * or certificate. The verification process is most likely asynchronous.
+ * That is why the application must call the completion callback when the
+ * verification process has been completed. If this SKE session context
+ * is used to perform rekey, this callback usually is not provided as
+ * argument since sending public key in rekey is not mandatory. Setting
+ * this callback implies that remote end MUST send its public key.
+ *
+ * The `completed' callback will be called once the protocol has completed,
+ * either successfully or with an error. The status of the protocol is
+ * delivered to application with the callback.
+ *
+ * The `context' is passed as argument to all of the above callback
+ * functions.
+ *
+ ***/
+void silc_ske_set_callbacks(SilcSKE ske,
+ SilcSKEVerifyCb verify_key,
+ SilcSKECompletionCb completed,
+ void *context);
+
+/****f* silcske/SilcSKEAPI/silc_ske_initiator
+ *
+ * SYNOPSIS
+ *
+ * SilcAsyncOperation
+ * silc_ske_initiator(SilcSKE ske,
+ * SilcPacketStream stream,
+ * SilcSKEParams params,
+ * SilcSKEStartPayload start_payload);
+ *
+ * DESCRIPTION
+ *
+ * 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. 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' 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
+ * security properties instead of using the default ones library
+ * generates. If caller provides it, it must not free it once it has
+ * been given as argument to this function.
+ *
+ * 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_initiator(SilcSKE ske,
+ SilcPacketStream stream,
+ SilcSKEParams params,
+ SilcSKEStartPayload start_payload);
+
+/****f* silcske/SilcSKEAPI/silc_ske_responder
+ *
+ * SYNOPSIS
+ *
+ * SilcAsyncOperation
+ * silc_ske_responder(SilcSKE ske,
+ * SilcPacketStream stream,
+ * SilcSKEParams params);
+ *
+ * DESCRIPTION
+ *
+ * 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. The SKE library will handle all key exchange
+ * 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
+ * for example safely abort the protocol at any point, if needed. Returns
+ * NULL on error.
+ *
+ ***/
+SilcAsyncOperation silc_ske_responder(SilcSKE ske,
+ SilcPacketStream stream,
+ SilcSKEParams params);
+
+/****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);
+
+/****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
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_ske_set_keys(SilcSKE ske,
+ * SilcSKEKeyMaterial keymat,
+ * SilcSKESecurityProperties prop,
+ * SilcCipher *ret_send_key,
+ * SilcCipher *ret_receive_key,
+ * SilcHmac *ret_hmac_send,
+ * SilcHmac *ret_hmac_receive,
+ * SilcHash *ret_hash);
+ *
+ * DESCRIPTION
+ *
+ * This function can be used after successful key exchange to take the
+ * key material `keymat' with security properties `prop' into use.
+ * This will allocate send and receive ciphers, HMACs and hash for the
+ * application. Caller must free the returned contexts. This is an
+ * utility function.
+ *
+ ***/
+SilcBool silc_ske_set_keys(SilcSKE ske,
+ SilcSKEKeyMaterial keymat,
+ SilcSKESecurityProperties prop,
+ SilcCipher *ret_send_key,
+ SilcCipher *ret_receive_key,
+ SilcHmac *ret_hmac_send,
+ SilcHmac *ret_hmac_receive,
+ SilcHash *ret_hash);
+
+/****f* silcske/SilcSKEAPI/silc_ske_parse_version
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_ske_parse_version(SilcSKE ske,
+ * SilcUInt32 *protocol_version,
+ * char **protocol_version_string,
+ * SilcUInt32 *software_version,
+ * char **software_version_string,
+ * char **vendor_version);
+ *
+ * DESCRIPTION
+ *
+ * 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,
+ SilcUInt32 *protocol_version,
+ char **protocol_version_string,
+ SilcUInt32 *software_version,
+ 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_get_key_material
+ *
+ * SYNOPSIS
+ *
+ * SilcSKEKeyMaterial silc_ske_get_key_material(SilcSKE ske);
+ *
+ * DESCRIPTION
+ *
+ * Returns the negotiated key material from the `ske' or NULL if the
+ * key material does not exist. The caller must not free the returned
+ * pointer.
+ *
+ ***/
+SilcSKEKeyMaterial silc_ske_get_key_material(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