X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcske%2Fsilcske.h;h=389b5532237705efcc76c354205537692a52b5fc;hb=0f26cf62f47f8f882c942f947aec6588c7f6ba3d;hp=554da9e71bc7cf66cd2dd688ada5a8b779c48cd9;hpb=633acf9c988113d56c68c5023ebba31a4d3b7023;p=silc.git diff --git a/lib/silcske/silcske.h b/lib/silcske/silcske.h index 554da9e7..389b5532 100644 --- a/lib/silcske/silcske.h +++ b/lib/silcske/silcske.h @@ -1,10 +1,10 @@ /* - silcske.h + silcske.h Author: Pekka Riikonen - Copyright (C) 2000 - 2002 Pekka Riikonen + Copyright (C) 2000 - 2005 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 @@ -24,7 +24,7 @@ * * DESCRIPTION * - * Implementation of the SILC Key Exchange Protocol (SKE). The SKE protocol + * The SILC Key Exchange (SKE) protocol interface. The SKE protocol * is used to negotiate secret key material between two parties, to be used * as session key or some other key. For example, when client connects to * server SKE is performed to exchange public keys, and to generate the key @@ -32,20 +32,13 @@ * two create secret key material for securing for example file transfer * stream. * - * SKE is based on Diffie-Hellman, and it derives its functionality from - * SSH2 Key Exchange protocol, OAKLEY Key Determination protocol and - * Station-To-Station (STS) protocols. - * * This SKE implementation provides easy interface for application - * that wants to use SKE. In fact, the interface is designed to be + * 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. For the interface application must provide - * a packet sending function which SKE library can call when it wants - * to send packet to the remote host. The actual network connection - * therefore is handled in the application and not by the SKE library. + * 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 @@ -61,98 +54,133 @@ #include "silcske_status.h" -/****s* silcske/SilcSKEAPI/SilcSKE +/* Length of cookie in Start Payload */ +#define SILC_SKE_COOKIE_LEN 16 + +/* Forward declarations */ +typedef struct SilcSKECallbacksStruct *SilcSKECallbacks; +typedef struct SilcSKEStruct *SilcSKE; + +#include "silcske_groups.h" +#include "silcske_payload.h" + +/****d* silcske/SilcSKEAPI/SilcSKESecurityPropertyFlag * * NAME * - * typedef struct SilcSKEStruct *SilcSKE; + * typedef enum { ... } SilcSKESecurityPropertyFlag * * DESCRIPTION * - * This context is forward declaration for the SilcSKEStruct. - * This is allocated by the silc_ske_alloc and freed by the - * silc_ske_free function. This context represents the SKE session. + * SKE security property flags as defined by the SK protocol. * - ***/ -typedef struct SilcSKEStruct *SilcSKE; + * SOURCE + */ +typedef enum { + SILC_SKE_SP_FLAG_NONE = 0x00, /* No flags */ + SILC_SKE_SP_FLAG_IV_INCLUDED = 0x01, /* IV included in packet */ + SILC_SKE_SP_FLAG_PFS = 0x02, /* Perfect Forward Secrecy */ + SILC_SKE_SP_FLAG_MUTUAL = 0x04, /* Mutual authentication */ +} SilcSKESecurityPropertyFlag; +/***/ /****s* silcske/SilcSKEAPI/SilcSKESecurityProperties * * NAME * - * typedef struct SilcSKESecurityPropertiesStruct - * *SilcSKESecurityProperties; + * typedef struct { ... } *SilcSKESecurityProperties; * * DESCRIPTION * - * This context is forward declaration for the - * SilcSKESecurityPropertiesStruct structure. It is allocated by the - * library, and it represents the security properties selected during - * the SKE negotiation. + * 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 + * communication. * - ***/ -typedef struct SilcSKESecurityPropertiesStruct *SilcSKESecurityProperties; - -/* Forward declaration for SKE callbacks structure, which is internal. */ -typedef struct SilcSKECallbacksStruct *SilcSKECallbacks; + * SOURCE + */ +typedef struct { + 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 */ +} *SilcSKESecurityProperties; +/***/ -/****d* silcske/SilcSKEAPI/SilcSKEPKType +/****s* silcske/SilcSKEAPI/SilcSKEKeyMaterial * * NAME * - * typedef enum { ... } SilcSKEPKType; + * typedef struct { ... } *SilcSKEKeyMaterial; * * DESCRIPTION * - * Public key and certificate types defined by the SKE protocol. + * This is the key material structure, and is passed as argument by the + * application to silc_ske_process_key_material* functions. It includes + * the processed key material which can be used as SILC session keys. * - * SOURCE */ -typedef enum { - SILC_SKE_PK_TYPE_SILC = 1, /* Mandatory type */ - /* Optional types. These are not implemented currently */ - SILC_SKE_PK_TYPE_SSH2 = 2, - SILC_SKE_PK_TYPE_X509V3 = 3, - SILC_SKE_PK_TYPE_OPENPGP = 4, - SILC_SKE_PK_TYPE_SPKI = 5 -} SilcSKEPKType; +typedef struct { + 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; + unsigned char *send_hmac_key; + unsigned char *receive_hmac_key; + SilcUInt32 hmac_key_len; +} *SilcSKEKeyMaterial; /***/ -/****f* silcske/SilcSKEAPI/SilcSKESendPacketCb +/****s* silcske/SilcSKEAPI/SilcSKERekeyMaterial * - * SYNOPSIS + * NAME * - * typedef void (*SilcSKESendPacketCb)(SilcSKE ske, SilcBuffer packet, - * SilcPacketType type, void *context); + * typedef struct { ... } *SilcSKERekeyMaterial; * * DESCRIPTION * - * Packet sending callback. Caller of the SKE routines must provide - * a routine to send packets to negotiation parties. See the - * silc_ske_set_callbacks for more information. + * 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. * - ***/ -typedef void (*SilcSKESendPacketCb)(SilcSKE ske, SilcBuffer packet, - SilcPacketType type, void *context); + * Application may save application specific data to `user_context'. + * + */ +typedef struct { + void *user_context; /* Application specific data */ + unsigned char *send_enc_key; + unsigned int enc_key_len : 23; + unsigned int ske_group : 8; + unsigned int pfs : 1; +} *SilcSKERekeyMaterial; +/***/ -/****f* silcske/SilcSKEAPI/SilcSKECb +/****d* silcske/SilcSKEAPI/SilcSKEPKType * - * SYNOPSIS + * NAME * - * typedef void (*SilcSKECb)(SilcSKE ske, void *context); + * typedef enum { ... } SilcSKEPKType; * * DESCRIPTION * - * Generic SKE callback function. This is called in various SKE - * routines. The SilcSKE object sent as argument provides all the data - * callers routine might need (payloads etc). This is usually called - * to indicate that the application may continue the execution of the - * SKE protocol. The application should check the ske->status in this - * callback function. This callback is also called when Start Payload - * is processed. See silc_ske_set_callbacks function for more information. + * Public key and certificate types defined by the SKE protocol. * - ***/ -typedef void (*SilcSKECb)(SilcSKE ske, void *context); + * SOURCE + */ +typedef enum { + SILC_SKE_PK_TYPE_SILC = 1, /* SILC Public Key, mandatory */ + SILC_SKE_PK_TYPE_SSH2 = 2, /* SSH2 Public key, not supported */ + SILC_SKE_PK_TYPE_X509V3 = 3, /* X.509v3 certificate, not supported */ + SILC_SKE_PK_TYPE_OPENPGP = 4, /* OpenPGP certificate, not supported */ + SILC_SKE_PK_TYPE_SPKI = 5 /* SPKI certificate, not supported */ +} SilcSKEPKType; +/***/ /****f* silcske/SilcSKEAPI/SilcSKEVerifyCbCompletion * @@ -182,7 +210,7 @@ typedef void (*SilcSKEVerifyCbCompletion)(SilcSKE ske, * SYNOPSIS * * typedef void (*SilcSKEVerifyCb)(SilcSKE ske, - * unsigned char *pk_data, + * const unsigned char *pk_data, * SilcUInt32 pk_len, * SilcSKEPKType pk_type, * void *context, @@ -192,16 +220,15 @@ typedef void (*SilcSKEVerifyCbCompletion)(SilcSKE ske, * DESCRIPTION * * Callback function used to verify the received public key or certificate. - * The verification process is most likely asynchronous. That's why the + * The verification process is most likely asynchronous. That's why the * application must call the `completion' callback when the verification - * process has been completed. The library then calls the user callback - * (SilcSKECb), if it was provided for the function that takes this callback - * function as argument, to indicate that the SKE protocol may continue. - * See silc_ske_set_callbacks for more information. + * process has been completed. The `context' is the context given as + * arugment to silc_ske_set_callbacks. See silc_ske_set_callbacks for + * more information. * ***/ typedef void (*SilcSKEVerifyCb)(SilcSKE ske, - unsigned char *pk_data, + const unsigned char *pk_data, SilcUInt32 pk_len, SilcSKEPKType pk_type, void *context, @@ -212,98 +239,39 @@ typedef void (*SilcSKEVerifyCb)(SilcSKE ske, * * SYNOPSIS * - * typedef SilcSKEStatus (*SilcSKECheckVersion)(SilcSKE ske, - * unsigned char *version, - * SilcUInt32 len, void *context); + * 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 + * 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 (*SilcSKECheckVersion)(SilcSKE ske, - unsigned char *version, - SilcUInt32 len, void *context); +typedef SilcSKEStatus (*SilcSKECheckVersionCb)(SilcSKE ske, + const unsigned char *version, + SilcUInt32 len, void *context); -/****s* silcske/SilcSKEAPI/SilcSKEKeyMaterial +/****f* silcske/SilcSKEAPI/SilcSKECompletionCb * - * NAME + * SYNOPSIS * - * typedef struct { ... } SilcSKEKeyMaterial; * * DESCRIPTION * - * This is the key material structure, and is passed as argument by the - * application to silc_ske_process_key_material* functions. It includes - * the processed key material which can be used as SILC session keys. * ***/ -typedef struct { - 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; - unsigned char *send_hmac_key; - unsigned char *receive_hmac_key; - SilcUInt32 hmac_key_len; -} SilcSKEKeyMaterial; - -/* Length of cookie in Start Payload */ -#define SILC_SKE_COOKIE_LEN 16 - -#include "silcske_groups.h" -#include "silcske_payload.h" - -/****d* silcske/SilcSKEAPI/SilcSKESecurityPropertyFlag - * - * NAME - * - * typedef enum { ... } SilcSKESecurityPropertyFlag - * - * DESCRIPTION - * - * SKE security property flags as defined by the SK protocol. - * - * SOURCE - */ -typedef enum { - SILC_SKE_SP_FLAG_NONE = 0x00, /* No flags */ - SILC_SKE_SP_FLAG_IV_INCLUDED = 0x01, /* IV included in ciphertexts */ - SILC_SKE_SP_FLAG_PFS = 0x02, /* Perfect Forward Secrecy */ - SILC_SKE_SP_FLAG_MUTUAL = 0x04, /* Mutual authentication */ -} SilcSKESecurityPropertyFlag; -/***/ - -/****s* silcske/SilcSKEAPI/SilcSKESecurityPropertiesStruct - * - * NAME - * - * struct SilcSKESecurityPropertiesStruct { ... }; - * - * DESCRIPTION - * - * 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 - * communication. - * - * SOURCE - */ -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 */ -}; -/***/ +typedef void (*SilcSKECompletionCb)(SilcSKE ske, + SilcSKEStatus status, + SilcSKESecurityProperties prop, + SilcSKEKeyMaterial keymat, + SilcSKERekeyMaterial rekey, + void *context); /****s* silcske/SilcSKEAPI/SilcSKEStruct * @@ -315,7 +283,7 @@ struct SilcSKESecurityPropertiesStruct { * * This structure is the SKE session context, and has a type definition * to SilcSKE. The structure includes the network connection socket, - * securit properties collected during the SKE negotiation, payloads + * 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 @@ -324,19 +292,17 @@ struct SilcSKESecurityPropertiesStruct { * SOURCE */ struct SilcSKEStruct { - /* The connection object. This is initialized by the caller. */ -#if 0 - SilcSocketConnection sock; -#endif + /* The network socket connection stream. Set by application. */ + SilcPacketStream stream; - /* Security properties negotiated */ + /* 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; + SilcSKEStartPayload start_payload; + SilcSKEKEPayload ke1_payload; + SilcSKEKEPayload ke2_payload; unsigned char *remote_version; /* Temporary copy of the KE Start Payload used in the @@ -346,7 +312,7 @@ struct SilcSKEStruct { /* Random number x, 1 < x < q. This is the secret exponent used in Diffie Hellman computations. */ SilcMPInt *x; - + /* The secret shared key */ SilcMPInt *KEY; @@ -374,6 +340,19 @@ struct SilcSKEStruct { /* 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; + bool aborted; }; /***/ @@ -383,21 +362,33 @@ struct SilcSKEStruct { * * SYNOPSIS * - * SilcSKE silc_ske_alloc(SilcRng rng, void *context); + * SilcSKE silc_ske_alloc(SilcRng rng, SilcSchedule schedule, + * void *context); * * DESCRIPTION * * Allocates the SKE session context and returns it. The `rng' is * the random number generator the SKE is going to use when it needs * random number generation during the SKE session. The `context' is - * user context that the libary will not touch. The application can - * access that context with the ske->user_context if needed. The + * user context that the libary will not touch. Application can get the + * context by calling the fuction silc_ske_get_context function. The * application is responsible of freeing the `context'. After the * SKE session context is allocated application must call the * 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); + * ***/ -SilcSKE silc_ske_alloc(SilcRng rng, void *context); +SilcSKE silc_ske_alloc(SilcRng rng, SilcSchedule schedule, void *context); /****f* silcske/SilcSKEAPI/silc_ske_free * @@ -412,501 +403,186 @@ SilcSKE silc_ske_alloc(SilcRng rng, void *context); ***/ void silc_ske_free(SilcSKE ske); +/****f* silcske/SilcSKEAPI/silc_ske_get_context + * + * SYNOPSIS + * + * void *silc_ske_get_context(SilcSKE ske); + * + * DESCRIPTION + * + * Returns the context that was given as argument to silc_ske_alloc. + * + ***/ +void *silc_ske_get_context(SilcSKE ske); + /****f* silcske/SilcSKEAPI/silc_ske_set_callbacks * * SYNOPSIS * * void silc_ske_set_callbacks(SilcSKE ske, - * SilcSKESendPacketCb send_packet, - * SilcSKECb payload_receive, * SilcSKEVerifyCb verify_key, - * SilcSKECb proto_continue, * SilcSKECheckVersion check_version, + * SilcSKECompletion completed, * void *context); * * DESCRIPTION * * Sets the callback functions for the SKE session. * - * The `send_packet' callback is a function that sends the packet to - * network. The SKE library will call it at any time packet needs to - * be sent to the remote host. - * - * The `payload_receive' callback is called when the remote host's Key - * Exchange Start Payload has been processed. The payload is saved - * to ske->start_payload if the application would need it. The application - * must also provide the payload to the next state of the SKE. - * * The `verify_key' callback is called to verify the received public key * or certificate. The verification process is most likely asynchronous. * That is why the application must call the completion callback when the - * verification process has been completed. The library then calls the user - * callback (`proto_continue'), if it is provided to indicate that the SKE - * protocol may continue. If this SKE session context is used to perform - * rekey, this callback usually is not provided as argument since sending - * public key in rekey is not mandatory. Setting this callback implies - * that remote end MUST send its public key, and this could cause - * problems when performing rekey. When doing normal SKE session this - * callback should be set. - * - * The `proto_continue' callback is called to indicate that it is - * safe to continue the execution of the SKE protocol after executing - * an asynchronous operation, such as calling the `verify_key' callback - * function, which is asynchronous. The application should check the - * ske->status in this function to check whether it is Ok to continue - * the execution of the protocol. + * verification process has been completed. If this SKE session context + * is used to perform rekey, this callback usually is not provided as + * 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 + * 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. + * * The `context' is passed as argument to all of the above callback * functions. * ***/ void silc_ske_set_callbacks(SilcSKE ske, - SilcSKESendPacketCb send_packet, - SilcSKECb payload_receive, SilcSKEVerifyCb verify_key, - SilcSKECb proto_continue, - SilcSKECheckVersion check_version, + SilcSKECheckVersionCb check_version, + SilcSKECompletionCb completed, void *context); /****f* silcske/SilcSKEAPI/silc_ske_initiator_start * * SYNOPSIS * - * SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng, - * SilcSocketConnection sock, - * SilcSKEStartPayload - * *start_payload); + * SilcAsyncOperation + * silc_ske_initiator_start(SilcSKE ske, + * SilcPacketStream stream, + * SilcSKEStartPayload start_payload); * * DESCRIPTION * - * Starts the SILC Key Exchange protocol for initiator. The connection - * to the responder end must be established before calling this function - * and the connecting socket must be sent as argument. This function - * creates the Key Exchange Start Payload which includes all our - * configured security properties. This payload is then sent to the - * responder end for further processing. This payload must be sent as - * argument to the function, however, it must not be encoded - * already, it is done by this function. The caller must not free - * the `start_payload' since the SKE library will save it. + * 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. * - * Before calling this function application calls the - * silc_ske_assemble_security_properties which returns the `start_payload' - * which application must provide for 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. * - * After calling this function the application must wait for reply - * from the responder. + * 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. * - ***/ -SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng, -#if 0 - SilcSocketConnection sock, -#endif - SilcSKEStartPayload *start_payload); - -/****f* silcske/SilcSKEAPI/silc_ske_initiator_phase_1 - * - * SYNOPSIS - * - * SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske, - * SilcBuffer start_payload); - * - * DESCRIPTION - * - * Function called after ske_initiator_start fuction. This receives - * the responder's Key Exchange Start payload which includes the - * security properties selected by the responder from our payload - * sent in the silc_ske_initiator_start function. The `start_payload' - * is the received payload and the application must send it as argument. - * - * After calling this function the application must call immediately, - * or with short timeout, the silc_ske_initiator_phase_2 function. + * 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. * ***/ -SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske, - SilcBuffer start_payload); - -/****f* silcske/SilcSKEAPI/silc_ske_initiator_phase_2 - * - * SYNOPSIS - * - * SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske, - * SilcPublicKey public_key, - * SilcPrivateKey private_key, - * SilcSKEPKType pk_type) - * - * DESCRIPTION - * - * This function continues the SKE session after the initiator has - * called the silc_ske_initiator_phase_1. After that function returns - * the application should call immediately, or with short timeout, this - * function which will continue with the session, and sends next phase - * packet to the responder. The caller must provide the caller's - * public key and private key as argument, since the public key is - * sent to the responder, and the private key is be used to generate - * digital signature. - * - * After this function the application must wait for reply from the - * responder. - * - ***/ -SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske, - SilcPublicKey public_key, - SilcPrivateKey private_key, - SilcSKEPKType pk_type); - -/****f* silcske/SilcSKEAPI/silc_ske_initiator_finish - * - * SYNOPSIS - * - * SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske, - * SilcBuffer ke_payload); - * - * DESCRIPTION - * - * Receives the reply from the responder and processes it. The - * `ke_payload' is the reply and application must provide it as argument. - * This function will verify the responder's public key, by calling - * the `verify_key' callback that was set with silc_ske_set_callbacks - * function. - * - * If this function returns error, no callbacks will be called. If - * this function needs to verify remote end's public key, this will - * return SILC_SKE_STATUS_PENDING, which indicates application that - * SKE is performing asynchronous operation and is in pending status. - * When in this status application must not continue with calling - * any other SKE routine. The asynchronous operation is the `verify_key' - * callback, which application completes by calling its completion - * callback. After completion the SKE libary will call the - * `proto_continue' callback, to indicate application that pending - * status is over and it is safe to continue the execution of SKE, - * which application does by calling the silc_ske_end function. - * - * If this function returns SILC_SKE_STATUS_OK, it will not call the - * `verify_key' callback, however, it will or has already called the - * `proto_continue' callback. - * - * Application must not continue execution of the SKE before library - * has called the `proto_continue' callback. After it is called - * the application finishes SKE session by calling silc_ske_end - * function. - * - ***/ -SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske, - SilcBuffer ke_payload); +SilcAsyncOperation +silc_ske_initiator_start(SilcSKE ske, + SilcPacketStream stream, + SilcSKEStartPayload start_payload); /****f* silcske/SilcSKEAPI/silc_ske_responder_start * * SYNOPSIS * - * SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng, - * SilcSocketConnection sock, - * const char *version, - * SilcBuffer start_payload, - * SilcSKESecurityPropertyFlag - * flags); - * - * DESCRIPTION - * - * Starts Key Exchange protocol for responder. 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 enforces for the - * initiator. Responder may, for example, enforce that the PFS - * will be performed in rekey. This example can be done by providing - * SILC_SKE_SP_FLAG_PFS as `flags'. The `flags' is a bit mask of - * enforced flags. - * - * After this function the responder calls immediately, or with short - * timeout the silc_ske_responder_phase_1 function. - * - ***/ -SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng, -#if 0 - SilcSocketConnection sock, -#endif - const char *version, - SilcBuffer start_payload, - SilcSKESecurityPropertyFlag flags); - -/****f* silcske/SilcSKEAPI/silc_ske_responder_phase_1 - * - * SYNOPSIS - * - * SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske); - * - * DESCRIPTION - * - * This function is called after the silc_ske_responder_start, and - * is used to send our reply to the initiator. This function is - * called either immediately, or with short timeout, after the - * silc_ske_responder_start function returned. - * - * After this function the responder must wait for reply from the - * initiator. - * - ***/ -SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske); - -/****f* silcske/SilcSKEAPI/silc_ske_responder_phase_2 - * - * SYNOPSIS - * - * SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske, - * SilcBuffer ke_payload); - * - * DESCRIPTION - * - * Receives the reply from the initiator and procedses it. The - * `ke_payload' is the reply and application must provide it as argument. - * This function will verify the remote host's public key, by calling - * the `verify_key' callback that was set with silc_ske_set_callbacks - * function. - * - * If this function returns error, no callbacks will be called. If - * this function needs to verify remote end's public key, this will - * return SILC_SKE_STATUS_PENDING, which indicates application that - * SKE is performing asynchronous operation and is in pending status. - * When in this status application must not continue with calling - * any other SKE routine. The asynchronous operation is the `verify_key' - * callback, which application completes by calling its completion - * callback. After completion the SKE libary will call the - * `proto_continue' callback, to indicate application that pending - * status is over and it is safe to continue the execution of SKE, - * which application does by calling the silc_ske_responder_finish - * function. - * - * If this function returns SILC_SKE_STATUS_OK, it will not call the - * `verify_key' callback, however, it will or has already called the - * `proto_continue' callback. - * - * Application must not continue execution of the SKE before library - * has called the `proto_continue' callback. After it is called - * the application calls the silc_ske_responder_finish function. - * - ***/ -SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske, - SilcBuffer ke_payload); - -/****f* silcske/SilcSKEAPI/silc_ske_responder_finish - * - * SYNOPSIS - * - * SilcSKEStatus silc_ske_responder_finish(SilcSKE ske, - * SilcPublicKey public_key, - * SilcPrivateKey private_key, - * SilcSKEPKType pk_type); - * - * DESCRIPTION - * - * This function finishes the responder's SKE session, and this function - * is called either immediately, or with short timeout, after the - * silc_ske_responder_phase_2 returned. This will send our reply to - * the initiator. The caller must provide the caller's public key and - * private key as argument, since the public key is sent to the responder, - * and the private key is be used to generate digital signature. - * - * After this function the application must wait for the end indication - * from the intiator, and when it is received the silc_ske_end is called. - * - ***/ -SilcSKEStatus silc_ske_responder_finish(SilcSKE ske, - SilcPublicKey public_key, - SilcPrivateKey private_key, - SilcSKEPKType pk_type); - -/****f* silcske/SilcSKEAPI/silc_ske_end - * - * SYNOPSIS - * - * SilcSKEStatus silc_ske_end(SilcSKE ske); + * SilcAsyncOperation + * silc_ske_responder_start(SilcSKE ske, + * SilcPacketStream stream, + * const char *version, + * SilcBuffer start_payload, + * SilcSKESecurityPropertyFlag flags); * * DESCRIPTION * - * The Key Exchange protocol is ended by calling this function. This - * must not be called until the keys are processed by calling the - * silc_ske_process_key_material function. The protocol prohibits - * calling this function before key material is processed properly. + * 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. * - * This function is for both initiator and responder. After calling - * this function initiator must wait for end indication from the - * responder. After that the silc_ske_free may be called. The responder - * calls this function after it has received the intiator's end - * indication. + * 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. * - * NOTES + * 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. * - * Initiator must not start using the negotiated key material before - * calling this function or before remote end has sent its end - * indication. Only after that the key material may be taken in 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. * ***/ -SilcSKEStatus silc_ske_end(SilcSKE ske); - -/****f* silcske/SilcSKEAPI/silc_ske_abort - * - * SYNOPSIS - * - * SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status); - * - * DESCRIPTION - * - * Aborts the Key Exchange protocol. This is called if error occurs - * while performing the protocol. The status argument is the error - * status and it is sent to the remote end. - * - ***/ -SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status); +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 * * SYNOPSIS * - * SilcSKEStatus + * SilcSKEStartPayload * silc_ske_assemble_security_properties(SilcSKE ske, * SilcSKESecurityPropertyFlag flags, - * const char *version, - * SilcSKEStartPayload - * **return_payload); + * const char *version); * * 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 + * 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. The assembled payload is returned into - * the `return_payload' pointer. + * by the SKE library itself. Returns NULL on error. * ***/ -SilcSKEStatus +SilcSKEStartPayload silc_ske_assemble_security_properties(SilcSKE ske, SilcSKESecurityPropertyFlag flags, - const char *version, - SilcSKEStartPayload **return_payload); - -/****f* silcske/SilcSKEAPI/silc_ske_select_security_properties - * - * SYNOPSIS - * - * SilcSKEStatus - * silc_ske_select_security_properties(SilcSKE ske, - * const char *version, - * SilcSKEStartPayload *payload, - * SilcSKEStartPayload *remote_payload); - * - * DESCRIPTION - * - * Parses the Key Exchange Start Payload indicated by `remote_payload', - * and selects the security properties properties from it, and puts the - * selection into the `payload'. This always attempts to select the - * best security properties from the payload, and it always selects - * one of each kind of security property, as this is dictated by the - * protocol. The `version' is our version, that we will put to the - * `payload', since the `payload' is usually sent to the remote end. - * the `check_version' callback will be called in this function so - * that application can do version check with the remote end. - * - ***/ -SilcSKEStatus -silc_ske_select_security_properties(SilcSKE ske, - const char *version, - SilcSKEStartPayload *payload, - SilcSKEStartPayload *remote_payload); - -/****f* silcske/SilcSKEAPI/silc_ske_process_key_material - * - * SYNOPSIS - * - * SilcSKEStatus silc_ske_process_key_material(SilcSKE ske, - * SilcUInt32 req_iv_len, - * SilcUInt32 req_enc_key_len, - * SilcUInt32 req_hmac_key_len, - * SilcSKEKeyMaterial *key); - * - * DESCRIPTION - * - * This function is used by the application to process the key material - * negotiated with the SKE session, to actually produce the keys that - * is to be used in SILC protocol. The key processing is defined by the - * protocol. The `req_iv_len', `req_enc_key_len' and `req_hmac_key_len' - * are the request IV length, requested encryption/decrypt key length, - * and requested HMAC key length, respectively, and they cannot be - * zero (0). They tell the function how long the keys should be, and - * it will produce the requested length keys for the application. - * The key material is returned in to the `key', which the caller must - * free. - * - ***/ -SilcSKEStatus silc_ske_process_key_material(SilcSKE ske, - SilcUInt32 req_iv_len, - SilcUInt32 req_enc_key_len, - SilcUInt32 req_hmac_key_len, - SilcSKEKeyMaterial *key); - -/****f* silcske/SilcSKEAPI/silc_ske_process_key_material_data - * - * SYNOPSIS - * - * SilcSKEStatus - * 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, - * SilcSKEKeyMaterial *key); - * - * DESCRIPTION - * - * This function is equivalent to silc_ske_process_key_material, except - * that the caller provides the raw key material as argument, the `data' - * and `data_len'. This is special utility function provided for the - * application, if it needs to generate key material as the protocol - * defines for some other purpose than strictly SILC session key usage. - * Hence, this function can be used outside SKE protocol to just produce - * key material from some raw data. The `hash' is a hash algorithm that - * is used as part of key processing, and caller must provide it. - * - ***/ -SilcSKEStatus -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, - SilcSKEKeyMaterial *key); - -/****f* silcske/SilcSKEAPI/silc_ske_free_key_material - * - * SYNOPSIS - * - * void silc_ske_free_key_material(SilcSKEKeyMaterial *key); - * - * DESCRIPTION - * - * Frees the key material indicated by `key', and all data in it. - * - ***/ -void silc_ske_free_key_material(SilcSKEKeyMaterial *key); + const char *version); /****f* silcske/SilcSKEAPI/silc_ske_parse_version * * SYNOPSIS * - * bool silc_ske_parse_version(SilcSKE ske, + * bool silc_ske_parse_version(SilcSKE ske, * SilcUInt32 *protocol_version, * char **protocol_version_string, - * SilcUInt32 *software_version, + * SilcUInt32 *software_version, * char **software_version_string, * char **vendor_version); * @@ -920,10 +596,10 @@ void silc_ske_free_key_material(SilcSKEKeyMaterial *key); * string was successfully parsed. * ***/ -bool silc_ske_parse_version(SilcSKE ske, +bool silc_ske_parse_version(SilcSKE ske, SilcUInt32 *protocol_version, char **protocol_version_string, - SilcUInt32 *software_version, + SilcUInt32 *software_version, char **software_version_string, char **vendor_version);