X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcske%2Fsilcske.h;h=9c637de61942b32f1654f903312ed80bea8529c5;hb=52e57c880aba9c5e89f59d962eb9af75670b76e0;hp=e1c25b8539afac74ba0c4ae0044bdf329a1820f4;hpb=c27a4ecc3e616e8a5ee09b8ca888ed6ff3e501f7;p=silc.git diff --git a/lib/silcske/silcske.h b/lib/silcske/silcske.h index e1c25b85..9c637de6 100644 --- a/lib/silcske/silcske.h +++ b/lib/silcske/silcske.h @@ -4,7 +4,7 @@ Author: Pekka Riikonen - Copyright (C) 2000 - 2005 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 @@ -17,9 +17,6 @@ */ -#ifndef SILCSKE_H -#define SILCSKE_H - /****h* silcske/SILC SKE Interface * * DESCRIPTION @@ -30,37 +27,57 @@ * server SKE is performed to exchange public keys, and to generate the key * that is then used as session key. Two clients can execute SKE as well * two create secret key material for securing for example file transfer - * stream. - * - * This SKE implementation provides easy interface for application - * that wants to use SKE. In fact, the interface is designed to be - * application independent, and does not expect that the application using - * SKE would actually relate in any way to SILC. Hence, the interface - * can be used in any kind of application needing to perform key exchange - * protocol with two parties. The network connection is also handled - * outside the SKE interface. - * - * The protocol has initiator and responder. The initiator is the one - * that starts the protocol, and the responder is the one that receives - * negotiation request. The protocol has phases, and the interface is - * split into several phases that the application may call when - * needed. Heavy operations has been splitted so that application may - * call next phase with a timeout to give processing times to other - * things in the application. On the other hand, if application does - * not care about this it may call the phases immediately without any - * timeout. + * stream. This SKE implementation provides easy interface for application + * that wants to use SKE. * ***/ -#include "silcske_status.h" - -/* Length of cookie in Start Payload */ -#define SILC_SKE_COOKIE_LEN 16 +#ifndef SILCSKE_H +#define SILCSKE_H /* Forward declarations */ typedef struct SilcSKECallbacksStruct *SilcSKECallbacks; typedef struct SilcSKEStruct *SilcSKE; +/****d* silcske/SilcSKEAPI/SilcSKEStatus + * + * NAME + * + * typedef enum { ... } SilcSKEStatus; + * + * DESCRIPTION + * + * Status types returned in SKE callbacks. This tell the status of + * the SKE session, and if an error occurred. Application can map the + * status to human readable string with silc_ske_map_status function. + * + * SOURCE + */ +typedef enum { + /* These are defined by the protocol */ + SILC_SKE_STATUS_OK = 0, /* No error */ + SILC_SKE_STATUS_ERROR = 1, /* Unknown error */ + SILC_SKE_STATUS_BAD_PAYLOAD = 2, /* Malformed payload */ + SILC_SKE_STATUS_UNKNOWN_GROUP = 3, /* Unsupported DH group */ + SILC_SKE_STATUS_UNKNOWN_CIPHER = 4, /* Unsupported cipher */ + SILC_SKE_STATUS_UNKNOWN_PKCS = 5, /* Unsupported PKCS algorithm */ + SILC_SKE_STATUS_UNKNOWN_HASH_FUNCTION = 6, /* Unsupported hash function */ + SILC_SKE_STATUS_UNKNOWN_HMAC = 7, /* Unsupported HMAC */ + SILC_SKE_STATUS_UNSUPPORTED_PUBLIC_KEY = 8, /* Unsupported/not trusted PK */ + SILC_SKE_STATUS_INCORRECT_SIGNATURE = 9, /* Incorrect signature */ + SILC_SKE_STATUS_BAD_VERSION = 10, /* Unsupported version */ + SILC_SKE_STATUS_INVALID_COOKIE = 11, /* Cookie was modified */ + + /* Implementation specific status types */ + SILC_SKE_STATUS_PUBLIC_KEY_NOT_PROVIDED, /* Remote did not send PK */ + SILC_SKE_STATUS_BAD_RESERVED_FIELD, /* Reserved field was not 0 */ + 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; +/***/ + #include "silcske_groups.h" #include "silcske_payload.h" @@ -94,18 +111,20 @@ typedef enum { * * Security Properties negotiated between key exchange parties. This * structure is filled from the Key Exchange Start Payload which is used - * to negotiate what security properties should be used in the + * to negotiate what security properties must be used in the * communication. * * SOURCE */ -typedef struct { +typedef struct SilcSKESecurityPropertiesStruct { SilcSKESecurityPropertyFlag flags; /* Flags */ SilcSKEDiffieHellmanGroup group; /* Selected Diffie Hellman group */ - SilcPKCS pkcs; /* Selected PKCS algorithm */ SilcCipher cipher; /* Selected cipher */ - SilcHash hash; /* Selected hash algorithm */ 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; /***/ @@ -118,20 +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; /***/ @@ -145,20 +165,54 @@ 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. - * - * Application may save application specific data to `user_context'. + * 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. * - */ -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 + * + * NAME + * + * typedef struct { ... } *SilcSKEParams, SilcSKEParamsStruct; + * + * DESCRIPTION + * + * SKE parameters structure. This structure is given as argument to + * silc_ske_initiator and silc_ske_responder functions. + * + * SOURCE + */ +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; + + /* Security property flags. When initiator sets these it requests them + from the responder. Responder may set here the flags it supports + and wants to enforce for the initiator. */ + SilcSKESecurityPropertyFlag flags; + + /* SILC Session port when using UDP/IP and SILC_SKE_SP_FLAG_IV_INCLUDED + flag. It is the port the remote will use as SILC session port after + 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; /***/ /****d* silcske/SilcSKEAPI/SilcSKEPKType @@ -194,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, @@ -210,9 +260,7 @@ typedef void (*SilcSKEVerifyCbCompletion)(SilcSKE ske, * SYNOPSIS * * typedef void (*SilcSKEVerifyCb)(SilcSKE ske, - * const unsigned char *pk_data, - * SilcUInt32 pk_len, - * SilcSKEPKType pk_type, + * SilcPublicKey public_key, * void *context, * SilcSKEVerifyCbCompletion completion, * void *completion_context); @@ -226,136 +274,52 @@ typedef void (*SilcSKEVerifyCbCompletion)(SilcSKE ske, * arugment to silc_ske_set_callbacks. See silc_ske_set_callbacks for * more information. * + * If the key repository was provided in silc_ske_alloc this callback + * is called only if the public key was not found from the repository. + * ***/ typedef void (*SilcSKEVerifyCb)(SilcSKE ske, - const unsigned char *pk_data, - SilcUInt32 pk_len, - SilcSKEPKType pk_type, + SilcPublicKey public_key, void *context, SilcSKEVerifyCbCompletion completion, void *completion_context); -/****f* silcske/SilcSKEAPI/SilcSKECheckVersion - * - * SYNOPSIS - * - * typedef SilcSKEStatus - * (*SilcSKECheckVersionCb)(SilcSKE ske, - * const unsigned char *version, - * SilcUInt32 len, void *context); - * - * DESCRIPTION - * - * Callback function used to check the version of the remote SKE server. - * The SKE library will call this function so that the appliation may - * check its version against the remote host's version. This returns - * SILC_SKE_STATUS_OK if the version string is Ok, and returns - * SILC_SKE_STATUS_BAD_VERSION if the version was not acceptable. - * - ***/ -typedef SilcSKEStatus (*SilcSKECheckVersionCb)(SilcSKE ske, - const unsigned char *version, - SilcUInt32 len, void *context); - /****f* silcske/SilcSKEAPI/SilcSKECompletionCb * * SYNOPSIS * + * typedef void (*SilcSKECompletionCb)(SilcSKE ske, + * SilcSKEStatus status, + * const SilcSKESecurityProperties prop, + * const SilcSKEKeyMaterial keymat, + * SilcSKERekeyMaterial rekey, + * void *context); * * DESCRIPTION * + * Completion callback. This is called after the key exchange protocol + * has been completed. It delivers the status of the protocol, and if + * 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' 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); -/****s* silcske/SilcSKEAPI/SilcSKEStruct - * - * NAME - * - * struct SilcSKEStruct { ... }; - * - * DESCRIPTION - * - * This structure is the SKE session context, and has a type definition - * to SilcSKE. The structure includes the network connection socket, - * security properties collected during the SKE negotiation, payloads - * sent and received during the negotiation, and the actual raw key - * material too. The application usually does not need to reference - * to the inside of this structure. However, checking the current - * status of the session can easily be checked with ske->status. - * - * SOURCE - */ -struct SilcSKEStruct { - /* The network socket connection stream. Set by application. */ - SilcPacketStream stream; - - /* Negotiated Security properties. May be NULL in case of error. */ - SilcSKESecurityProperties prop; - - /* Key Exchange payloads filled during key negotiation with - remote data. Responder may save local data here as well. */ - SilcSKEStartPayload start_payload; - SilcSKEKEPayload ke1_payload; - SilcSKEKEPayload ke2_payload; - unsigned char *remote_version; - - /* Temporary copy of the KE Start Payload used in the - HASH computation. */ - SilcBuffer start_payload_copy; - - /* Random number x, 1 < x < q. This is the secret exponent - used in Diffie Hellman computations. */ - SilcMPInt *x; - - /* The secret shared key */ - SilcMPInt *KEY; - - /* The hash value HASH of the key exchange */ - unsigned char *hash; - SilcUInt32 hash_len; - - /* Random Number Generator. This is set by the caller and must - be free'd by the caller. */ - SilcRng rng; - - /* Pointer to the what ever user data. This is set by the caller - and is not touched by the SKE. The caller must also free this one. */ - void *user_data; - - /* Current status of SKE */ - SilcSKEStatus status; - - /* Reference counter. This is used when SKE library is performing async - operations, like public key verification. */ - int users; - - /* SKE callbacks. */ - SilcSKECallbacks callbacks; - - /* Backwards support version indicator */ - SilcUInt32 backward_version; - - char *version; - SilcPublicKey public_key; - SilcPrivateKey private_key; - SilcSKEPKType pk_type; - SilcBuffer packet_buf; - SilcSKESecurityPropertyFlag flags; - SilcSKEKeyMaterial keymat; - SilcSKERekeyMaterial rekey; - SilcSchedule schedule; - SilcFSMStruct fsm; - SilcAsyncOperationStruct op; - SilcBool aborted; -}; -/***/ - /* Prototypes */ /****f* silcske/SilcSKEAPI/silc_ske_alloc @@ -363,7 +327,8 @@ struct SilcSKEStruct { * SYNOPSIS * * SilcSKE silc_ske_alloc(SilcRng rng, SilcSchedule schedule, - * void *context); + * SilcSKR repository, SilcPublicKey public_key, + * SilcPrivateKey private_key, void *context); * * DESCRIPTION * @@ -376,19 +341,34 @@ struct SilcSKEStruct { * SKE session context is allocated application must call the * silc_ske_set_callbacks. * + * If the `repository' is non-NULL then the remote's public key will be + * verified from the repository. If it is not provided then the + * SilcSKEVerifyCb callback must be set, and it will be called to + * verify the key. If both `repository' and the callback is provided the + * 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. 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 * * // Initiator example - * ske = silc_ske_alloc(rng, scheduler, app); - * silc_ske_set_callbacks(ske, verify_public_key, check_version, app); - * start_payload = - * silc_ske_assemble_security_properties(ske, SILC_SKE_SP_FLAG_PFS | - * SILC_SKE_SP_FLAG_MUTUAL, - * version); - * silc_ske_initiator_start(ske); + * params.version = version; + * 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(ske, stream, ¶ms, NULL); * ***/ -SilcSKE silc_ske_alloc(SilcRng rng, SilcSchedule schedule, void *context); +SilcSKE silc_ske_alloc(SilcRng rng, SilcSchedule schedule, + SilcSKR repository, SilcPublicKey public_key, + SilcPrivateKey private_key, void *context); /****f* silcske/SilcSKEAPI/silc_ske_free * @@ -422,7 +402,6 @@ void *silc_ske_get_context(SilcSKE ske); * * void silc_ske_set_callbacks(SilcSKE ske, * SilcSKEVerifyCb verify_key, - * SilcSKECheckVersion check_version, * SilcSKECompletion completed, * void *context); * @@ -438,11 +417,6 @@ void *silc_ske_get_context(SilcSKE ske); * argument since sending public key in rekey is not mandatory. Setting * this callback implies that remote end MUST send its public key. * - * The `check_version' callback is called to verify the remote host's - * version. The application may check its own version against the remote - * host's version and determine whether supporting the remote host - * is possible. - * * 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. @@ -453,36 +427,66 @@ void *silc_ske_get_context(SilcSKE ske); ***/ void silc_ske_set_callbacks(SilcSKE ske, SilcSKEVerifyCb verify_key, - SilcSKECheckVersionCb check_version, 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, - * SilcSKEStartPayload start_payload); + * 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 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. * - * The `stream' is the network connection to the remote host. Note that - * SKE library will take over the packet stream `stream' while the - * protocol is in process. The application will not receive any packets - * for `stream' after this function is called. The `stream' is turned - * over to application once the completion callback is called. + * 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. * - * The `start_payload' includes all configured security properties that - * will be sent to the responder. The `start_payload' must be provided. - * It can be created by calling silc_ske_assemble_security_properties - * function. The caller must not free the payload once it has been - * given as argument to this function. + ***/ +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 @@ -490,42 +494,62 @@ void silc_ske_set_callbacks(SilcSKE ske, * NULL on error. * ***/ -SilcAsyncOperation -silc_ske_initiator_start(SilcSKE ske, - SilcPacketStream stream, - SilcSKEStartPayload start_payload); +SilcAsyncOperation silc_ske_responder(SilcSKE ske, + SilcPacketStream stream, + SilcSKEParams params); -/****f* silcske/SilcSKEAPI/silc_ske_responder_start +/****f* silcske/SilcSKEAPI/silc_ske_rekey_initiator * * SYNOPSIS * * SilcAsyncOperation - * silc_ske_responder_start(SilcSKE ske, + * silc_ske_rekey_initiator(SilcSKE ske, * SilcPacketStream stream, - * const char *version, - * SilcBuffer start_payload, - * SilcSKESecurityPropertyFlag flags); + * SilcSKERekeyMaterial rekey); * * 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. Note that - * SKE library will take over the packet stream `stream' while the - * protocol is in process. The application will not receive any packets - * for `stream' after this function is called. The `stream' is turned - * over to application once the completion callback is called. - * - * The application has received initiator's first packet from network - * and it must provide it as `start_payload' argument to this function. - * The function processes the packet and makes security property selection - * from the initiator's proposal. The `version' is the responder's version - * that will be sent in reply to the initiator. The `flags' indicates - * SilcSKESecurityPropertyFlag flags that responder supports and enforces - * for the initiator. Responder may, for example, enforce that the PFS - * will be performed in rekey. + * 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 @@ -533,74 +557,159 @@ silc_ske_initiator_start(SilcSKE ske, * NULL on error. * ***/ -SilcAsyncOperation -silc_ske_responder_start(SilcSKE ske, - SilcPacketStream stream, - const char *version, - SilcBuffer start_payload, - SilcSKESecurityPropertyFlag flags); - -SilcAsyncOperation -silc_ske_rekey_initiator_start(SilcSKE ske, - SilcPacketStream stream, - SilcSKERekeyMaterial rekey); - -SilcAsyncOperation -silc_ske_rekey_responder_start(SilcSKE ske, - SilcPacketStream stream, - SilcBuffer ke_payload, - SilcSKERekeyMaterial rekey); - -/****f* silcske/SilcSKEAPI/silc_ske_assemble_security_properties +SilcAsyncOperation silc_ske_rekey_responder(SilcSKE ske, + SilcPacketStream stream, + SilcSKERekeyMaterial rekey, + SilcPacket packet); + +/****f* silcske/SilcSKEAPI/silc_ske_set_keys * * SYNOPSIS * - * SilcSKEStartPayload - * silc_ske_assemble_security_properties(SilcSKE ske, - * SilcSKESecurityPropertyFlag flags, - * const char *version); + * 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 * - * Assembles security properties to Key Exchange Start Payload to be - * sent to the remote end. This checks system wide (SILC system, that is) - * settings and chooses from those. However, if other properties - * should be used this function is easy to replace by another function, - * as, this function is called by the caller of the library and not - * by the SKE library itself. Returns NULL on error. + * 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. * ***/ -SilcSKEStartPayload -silc_ske_assemble_security_properties(SilcSKE ske, - SilcSKESecurityPropertyFlag flags, - const char *version); +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); + * SilcUInt32 *protocol_version, + * char **protocol_version_string, + * SilcUInt32 *software_version, + * char **software_version_string, + * char **vendor_version); * * DESCRIPTION * - * This utility function can be used to parse the remote host's version - * string. This returns the protocol version, and software version into - * the `protocol_version', `software_version' and `vendor_version' pointers - * if they are provided. The string versions of the versions are saved - * in *_string pointers if they are provided. Returns TRUE if the version - * string was successfully parsed. + * 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); + 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 +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 + * + * const char *silc_ske_map_status(SilcSKEStatus status); + * + * DESCRIPTION + * + * Utility function to map the `status' into human readable message. + * + ***/ +const char *silc_ske_map_status(SilcSKEStatus status); + +#include "silcske_i.h" #endif /* !SILCSKE_H */