X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcske%2Fsilcske.h;h=9c637de61942b32f1654f903312ed80bea8529c5;hb=52e57c880aba9c5e89f59d962eb9af75670b76e0;hp=92b803f440bf05b38f08aef1d9c8ee426413ebb1;hpb=7f3be13a00555390d6b3362d18ce460953397e73;p=silc.git diff --git a/lib/silcske/silcske.h b/lib/silcske/silcske.h index 92b803f4..9c637de6 100644 --- a/lib/silcske/silcske.h +++ b/lib/silcske/silcske.h @@ -4,7 +4,7 @@ Author: Pekka Riikonen - 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 @@ -74,6 +74,7 @@ typedef enum { SILC_SKE_STATUS_BAD_PAYLOAD_LENGTH, /* Payload includes garbage */ SILC_SKE_STATUS_SIGNATURE_ERROR, /* Error computing signature */ SILC_SKE_STATUS_OUT_OF_MEMORY, /* System out of memory */ + SILC_SKE_STATUS_TIMEOUT, /* Timeout */ } SilcSKEStatus; /***/ @@ -115,7 +116,7 @@ typedef enum { * * SOURCE */ -typedef struct { +typedef struct SilcSKESecurityPropertiesStruct { SilcSKESecurityPropertyFlag flags; /* Flags */ SilcSKEDiffieHellmanGroup group; /* Selected Diffie Hellman group */ SilcCipher cipher; /* Selected cipher */ @@ -136,21 +137,21 @@ 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 */ -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; /***/ @@ -164,22 +165,19 @@ typedef struct { * * This context is returned after key exchange protocol to application * in the completion callback. Application may save it and use it later - * to perform the rekey with silc_ske_rekey_initiator_start and/or - * silc_ske_rekey_responder_start functions. If application does not - * need the context, it may free it with silc_free function. + * to perform the rekey with silc_ske_rekey_initiator and/or + * silc_ske_rekey_responder functions. If application does not + * need the context, it may free it with silc_ske_free_rekey_material + * function. * - * Application may save application specific data to `user_context'. - * - * SOURCE - */ -typedef struct { - void *user_context; /* Application specific data */ + ***/ +typedef struct SilcSKERekeyMaterialStruct { unsigned char *send_enc_key; + char *hash; unsigned int enc_key_len : 23; unsigned int ske_group : 8; unsigned int pfs : 1; } *SilcSKERekeyMaterial; -/***/ /****s* silcske/SilcSKEAPI/SilcSKEParams * @@ -194,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; @@ -209,6 +207,11 @@ typedef struct { 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; /***/ @@ -287,8 +290,8 @@ typedef void (*SilcSKEVerifyCb)(SilcSKE ske, * * typedef void (*SilcSKECompletionCb)(SilcSKE ske, * SilcSKEStatus status, - * SilcSKESecurityProperties prop, - * SilcSKEKeyMaterial keymat, + * const SilcSKESecurityProperties prop, + * const SilcSKEKeyMaterial keymat, * SilcSKERekeyMaterial rekey, * void *context); * @@ -299,15 +302,21 @@ typedef void (*SilcSKEVerifyCb)(SilcSKE ske, * successful the security properties `prop' that was negotiated in the * protocol and the key material `keymat' that can be set into use by * calling silc_ske_set_keys, and the rekey key material `rekey' which - * can be used later to start rekey protocol. The `prop' will remain - * valid as long as `ske' is valid. After `ske' is freed `prop' will - * become invalid. + * can be used later to start rekey protocol. The `prop' and `keymat' + * will remain valid as long as `ske' is valid. The `rekey' will remain + * valid until silc_ske_free_rekey_material is called. The application + * must call it to free the `rekey'. + * + * When doing rekey, this completion callback delivers the `keymat' and + * new `rekey'. The `prop' is ignored. The `keymat' has already been set + * to the packet stream associated with the `ske'. Thus, after this + * is called the new keys are in use. * ***/ typedef void (*SilcSKECompletionCb)(SilcSKE ske, SilcSKEStatus status, - SilcSKESecurityProperties prop, - SilcSKEKeyMaterial keymat, + const SilcSKESecurityProperties prop, + const SilcSKEKeyMaterial keymat, SilcSKERekeyMaterial rekey, void *context); @@ -343,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 @@ -350,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, @@ -417,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 * @@ -425,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 * @@ -434,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 @@ -449,20 +463,19 @@ 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_start +/****f* silcske/SilcSKEAPI/silc_ske_responder * * SYNOPSIS * * SilcAsyncOperation - * silc_ske_responder_start(SilcSKE ske, - * SilcPacketStream stream, - * SilcSKEParams params); + * silc_ske_responder(SilcSKE ske, + * SilcPacketStream stream, + * SilcSKEParams params); * * DESCRIPTION * @@ -470,8 +483,73 @@ 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 + * 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 @@ -479,21 +557,10 @@ silc_ske_initiator(SilcSKE ske, * NULL on error. * ***/ -SilcAsyncOperation -silc_ske_responder(SilcSKE ske, - SilcPacketStream stream, - SilcSKEParams params); - -SilcAsyncOperation -silc_ske_rekey_initiator(SilcSKE ske, - SilcPacketStream stream, - SilcSKERekeyMaterial rekey); - -SilcAsyncOperation -silc_ske_rekey_responder(SilcSKE ske, - SilcPacketStream stream, - SilcBuffer ke_payload, - SilcSKERekeyMaterial rekey); +SilcAsyncOperation silc_ske_rekey_responder(SilcSKE ske, + SilcPacketStream stream, + SilcSKERekeyMaterial rekey, + SilcPacket packet); /****f* silcske/SilcSKEAPI/silc_ske_set_keys * @@ -565,6 +632,21 @@ SilcBool silc_ske_parse_version(SilcSKE ske, ***/ 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 @@ -601,6 +683,20 @@ silc_ske_process_key_material_data(unsigned char *data, ***/ void silc_ske_free_key_material(SilcSKEKeyMaterial key); +/****f* silcske/SilcSKEAPI/silc_ske_free_rekey_material + * + * SYNOPSIS + * + * void silc_ske_free_rekey_material(SilcSKERekeyMaterial rekey); + * + * DESCRIPTION + * + * Utility function to free the rekey material returned in the + * SilcSKECompletionCb callback. + * + ***/ +void silc_ske_free_rekey_material(SilcSKERekeyMaterial rekey); + /****f* silcske/SilcSKEAPI/silc_ske_map_status * * SYNOPSIS