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
*
* SOURCE
*/
-typedef struct {
+typedef struct SilcSKESecurityPropertiesStruct {
SilcSKESecurityPropertyFlag flags; /* Flags */
SilcSKEDiffieHellmanGroup group; /* Selected Diffie Hellman group */
SilcCipher cipher; /* Selected cipher */
*
* 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;
/***/
* function.
*
***/
-typedef struct {
+typedef struct SilcSKERekeyMaterialStruct {
unsigned char *send_enc_key;
char *hash;
unsigned int enc_key_len : 23;
*
* 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;
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;
/***/
* 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
* 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, ¶ms, NULL);
+ * silc_ske_initiator(ske, stream, ¶ms, NULL);
*
***/
SilcSKE silc_ske_alloc(SilcRng rng, SilcSchedule schedule,
SilcSKECompletionCb completed,
void *context);
-/****f* silcske/SilcSKEAPI/silc_ske_initiator_start
+/****f* silcske/SilcSKEAPI/silc_ske_initiator
*
* SYNOPSIS
*
* silc_ske_initiator(SilcSKE ske,
* SilcPacketStream stream,
* SilcSKEParams params,
- SilcSKEStartPayload start_payload);
+ * SilcSKEStartPayload start_payload);
*
* DESCRIPTION
*
* 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
* 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
*
* 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
* 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
*
***/
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
*