X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcske%2Fsilcske.h;h=9c637de61942b32f1654f903312ed80bea8529c5;hb=52e57c880aba9c5e89f59d962eb9af75670b76e0;hp=92bf621856a5c28c9f8e8c9ad7c11cd05ac1c711;hpb=26c4ca7fbbc1e3afaa28d561f4b873a06879797e;p=silc.git diff --git a/lib/silcske/silcske.h b/lib/silcske/silcske.h index 92bf6218..9c637de6 100644 --- 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, ¶ms, NULL); + * silc_ske_initiator(ske, stream, ¶ms, 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 *