Author: Pekka Riikonen <priikone@silcnet.org>
- 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
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;
/***/
*
* 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 */
- SilcPKCS pkcs; /* Selected PKCS and remote's
- public key/certificate */
+ SilcPublicKey public_key; /* Remote public key */
+ SilcUInt16 remote_port; /* Remote port, set when IV Included
+ set and using UDP/IP */
} *SilcSKESecurityProperties;
/***/
* 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;
/***/
*
* 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
+ *
+ * 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
*
* 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,
* 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);
* 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);
*
* typedef void (*SilcSKECompletionCb)(SilcSKE ske,
* SilcSKEStatus status,
- * SilcSKESecurityProperties prop,
- * SilcSKEKeyMaterial keymat,
+ * const SilcSKESecurityProperties prop,
+ * const SilcSKEKeyMaterial keymat,
* SilcSKERekeyMaterial rekey,
* void *context);
*
* 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);
* SYNOPSIS
*
* SilcSKE silc_ske_alloc(SilcRng rng, SilcSchedule schedule,
- * SilcPublicKey public_key,
+ * SilcSKR repository, SilcPublicKey public_key,
* SilcPrivateKey private_key, void *context);
*
* DESCRIPTION
* 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);
+ * 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);
- * start_payload =
- * silc_ske_assemble_security_properties(ske, SILC_SKE_SP_FLAG_PFS |
- * SILC_SKE_SP_FLAG_MUTUAL,
- * version);
- * silc_ske_initiator_start(ske);
+ * silc_ske_initiator(ske, stream, ¶ms, NULL);
*
***/
SilcSKE silc_ske_alloc(SilcRng rng, SilcSchedule schedule,
- SilcPublicKey public_key, SilcPrivateKey private_key,
- void *context);
+ SilcSKR repository, SilcPublicKey public_key,
+ SilcPrivateKey private_key, void *context);
/****f* silcske/SilcSKEAPI/silc_ske_free
*
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 `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 `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.
+ * 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.
*
* This function returns SilcAsyncOperation operation context which can
* be used to control the protocol from the application. Application may
* NULL on error.
*
***/
-SilcAsyncOperation
-silc_ske_initiator(SilcSKE ske,
- SilcPacketStream stream,
- 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,
- * const char *version,
- * SilcBuffer start_payload,
- * SilcSKESecurityPropertyFlag flags);
+ * 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 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.
*
- * 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.
+ *
+ ***/
+SilcAsyncOperation silc_ske_responder(SilcSKE ske,
+ SilcPacketStream stream,
+ SilcSKEParams params);
+
+/****f* silcske/SilcSKEAPI/silc_ske_rekey_initiator
*
- * The `version' is the responder's SILC protocol version that will be
- * sent in reply to the initiator. The `flags' indicates the
- * SilcSKESecurityPropertyFlag flags that responder supports and enforces
- * for the initiator. Responder may, for example, enforce that the PFS
- * will be performed in rekey.
+ * 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
* NULL on error.
*
***/
-SilcAsyncOperation
-silc_ske_responder(SilcSKE ske,
- SilcPacketStream stream,
- const char *version,
- SilcSKESecurityPropertyFlag flags);
-
-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_initiator(SilcSKE ske,
+ SilcPacketStream stream,
+ SilcSKERekeyMaterial rekey);
-/****f* silcske/SilcSKEAPI/silc_ske_assemble_security_properties
+/****f* silcske/SilcSKEAPI/silc_ske_rekey_responder
*
* SYNOPSIS
*
- * SilcSKEStartPayload
- * silc_ske_assemble_security_properties(SilcSKE ske,
- * SilcSKESecurityPropertyFlag flags,
- * const char *version);
+ * SilcAsyncOperation
+ * silc_ske_rekey_responder(SilcSKE ske,
+ * SilcPacketStream stream,
+ * SilcSKERekeyMaterial rekey,
+ * SilcPacket packet);
*
* 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.
- * Returns NULL on error. This is an utility function. This is used
- * by the initiator of the protocol. The `version' is the local SILC
- * protocol version string.
+ * 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.
*
***/
-SilcSKEStartPayload
-silc_ske_assemble_security_properties(SilcSKE ske,
- SilcSKESecurityPropertyFlag flags,
- const char *version);
+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
*
*
* 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,
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
projects / silc.git / blobdiff