X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcske%2Fsilcske.h;h=9c637de61942b32f1654f903312ed80bea8529c5;hb=52e57c880aba9c5e89f59d962eb9af75670b76e0;hp=42d9bc635648738561b30b3b36991b4171005e7f;hpb=9bccc0b6c7413815b70b4c8554a886a021f0dd83;p=silc.git diff --git a/lib/silcske/silcske.h b/lib/silcske/silcske.h index 42d9bc63..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,13 +116,15 @@ typedef enum { * * SOURCE */ -typedef struct { +typedef struct SilcSKESecurityPropertiesStruct { SilcSKESecurityPropertyFlag flags; /* Flags */ SilcSKEDiffieHellmanGroup group; /* Selected Diffie Hellman group */ SilcCipher cipher; /* Selected cipher */ 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,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; /***/ @@ -162,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 * @@ -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; @@ -207,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; /***/ @@ -243,11 +248,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, @@ -289,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); * @@ -301,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); @@ -341,7 +348,13 @@ 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. + * + * 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 * @@ -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,15 +430,15 @@ 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 * * 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 +446,10 @@ 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' 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 @@ -448,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 * @@ -469,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 @@ -478,23 +494,75 @@ 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, - SilcBuffer ke_payload, - 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_assemble_security_properties +/****f* silcske/SilcSKEAPI/silc_ske_set_keys * * SYNOPSIS * @@ -538,7 +606,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 +617,86 @@ 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_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 +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_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