5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2000 - 2002 Pekka Riikonen
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; version 2 of the License.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
23 /****h* silcske/SILC SKE Interface
27 * Implementation of the SILC Key Exchange Protocol (SKE). The SKE protocol
28 * is used to negotiate secret key material between two parties, to be used
29 * as session key or some other key. For example, when client connects to
30 * server SKE is performed to exchange public keys, and to generate the key
31 * that is then used as session key. Two clients can execute SKE as well
32 * two create secret key material for securing for example file transfer
35 * SKE is based on Diffie-Hellman, and it derives its functionality from
36 * SSH2 Key Exchange protocol, OAKLEY Key Determination protocol and
37 * Station-To-Station (STS) protocols.
39 * This SKE implementation provides easy interface for application
40 * that wants to use SKE. In fact, the interface is designed to be
41 * application independent, and does not expect that the application using
42 * SKE would actually relate in any way to SILC. Hence, the interface
43 * can be used in any kind of application needing to perform key exchange
44 * protocol with two parties. The network connection is also handled
45 * outside the SKE interface. For the interface application must provide
46 * a packet sending function which SKE library can call when it wants
47 * to send packet to the remote host. The actual network connection
48 * therefore is handled in the application and not by the SKE library.
50 * The protocol has initiator and responder. The initiator is the one
51 * that starts the protocol, and the responder is the one that receives
52 * negotiation request. The protocol has phases, and the interface is
53 * split into several phases that the application may call when
54 * needed. Heavy operations has been splitted so that application may
55 * call next phase with a timeout to give processing times to other
56 * things in the application. On the other hand, if application does
57 * not care about this it may call the phases immediately without any
62 #include "silcske_status.h"
64 /****s* silcske/SilcSKEAPI/SilcSKE
68 * typedef struct SilcSKEStruct *SilcSKE;
72 * This context is forward declaration for the SilcSKEStruct.
73 * This is allocated by the silc_ske_alloc and freed by the
74 * silc_ske_free function. This context represents the SKE session.
77 typedef struct SilcSKEStruct *SilcSKE;
79 /****s* silcske/SilcSKEAPI/SilcSKESecurityProperties
83 * typedef struct SilcSKESecurityPropertiesStruct
84 * *SilcSKESecurityProperties;
88 * This context is forward declaration for the
89 * SilcSKESecurityPropertiesStruct structure. It is allocated by the
90 * library, and it represents the security properties selected during
91 * the SKE negotiation.
94 typedef struct SilcSKESecurityPropertiesStruct *SilcSKESecurityProperties;
96 /* Forward declaration for SKE callbacks structure, which is internal. */
97 typedef struct SilcSKECallbacksStruct *SilcSKECallbacks;
99 /****d* silcske/SilcSKEAPI/SilcSKEPKType
103 * typedef enum { ... } SilcSKEPKType;
107 * Public key and certificate types defined by the SKE protocol.
112 SILC_SKE_PK_TYPE_SILC = 1, /* Mandatory type */
113 /* Optional types. These are not implemented currently */
114 SILC_SKE_PK_TYPE_SSH2 = 2,
115 SILC_SKE_PK_TYPE_X509V3 = 3,
116 SILC_SKE_PK_TYPE_OPENPGP = 4,
117 SILC_SKE_PK_TYPE_SPKI = 5
121 /****f* silcske/SilcSKEAPI/SilcSKESendPacketCb
125 * typedef void (*SilcSKESendPacketCb)(SilcSKE ske, SilcBuffer packet,
126 * SilcPacketType type, void *context);
130 * Packet sending callback. Caller of the SKE routines must provide
131 * a routine to send packets to negotiation parties. See the
132 * silc_ske_set_callbacks for more information.
135 typedef void (*SilcSKESendPacketCb)(SilcSKE ske, SilcBuffer packet,
136 SilcPacketType type, void *context);
138 /****f* silcske/SilcSKEAPI/SilcSKECb
142 * typedef void (*SilcSKECb)(SilcSKE ske, void *context);
146 * Generic SKE callback function. This is called in various SKE
147 * routines. The SilcSKE object sent as argument provides all the data
148 * callers routine might need (payloads etc). This is usually called
149 * to indicate that the application may continue the execution of the
150 * SKE protocol. The application should check the ske->status in this
151 * callback function. This callback is also called when Start Payload
152 * is processed. See silc_ske_set_callbacks function for more information.
155 typedef void (*SilcSKECb)(SilcSKE ske, void *context);
157 /****f* silcske/SilcSKEAPI/SilcSKEVerifyCbCompletion
161 * typedef void (*SilcSKEVerifyCbCompletion)(SilcSKE ske,
162 * SilcSKEStatus status,
167 * Completion callback that will be called when the public key
168 * has been verified. The `status' will indicate whether the public
169 * key were trusted or not. If the `status' is PENDING then the status
170 * is not considered to be available at this moment. In this case the
171 * SKE libary will assume that the caller will call this callback again
172 * when the status is available. See silc_ske_set_callbacks for more
176 typedef void (*SilcSKEVerifyCbCompletion)(SilcSKE ske,
177 SilcSKEStatus status,
180 /****f* silcske/SilcSKEAPI/SilcSKEVerifyCb
184 * typedef void (*SilcSKEVerifyCb)(SilcSKE ske,
185 * unsigned char *pk_data,
187 * SilcSKEPKType pk_type,
189 * SilcSKEVerifyCbCompletion completion,
190 * void *completion_context);
194 * Callback function used to verify the received public key or certificate.
195 * The verification process is most likely asynchronous. That's why the
196 * application must call the `completion' callback when the verification
197 * process has been completed. The library then calls the user callback
198 * (SilcSKECb), if it was provided for the function that takes this callback
199 * function as argument, to indicate that the SKE protocol may continue.
200 * See silc_ske_set_callbacks for more information.
203 typedef void (*SilcSKEVerifyCb)(SilcSKE ske,
204 unsigned char *pk_data,
206 SilcSKEPKType pk_type,
208 SilcSKEVerifyCbCompletion completion,
209 void *completion_context);
211 /****f* silcske/SilcSKEAPI/SilcSKECheckVersion
215 * typedef SilcSKEStatus (*SilcSKECheckVersion)(SilcSKE ske,
216 * unsigned char *version,
217 * SilcUInt32 len, void *context);
221 * Callback function used to check the version of the remote SKE server.
222 * The SKE library will call this function so that the appliation may
223 * check its version against the remote host's version. This returns
224 * SILC_SKE_STATUS_OK if the version string is Ok, and returns
225 * SILC_SKE_STATUS_BAD_VERSION if the version was not acceptable.
228 typedef SilcSKEStatus (*SilcSKECheckVersion)(SilcSKE ske,
229 unsigned char *version,
230 SilcUInt32 len, void *context);
232 /****s* silcske/SilcSKEAPI/SilcSKEKeyMaterial
236 * typedef struct { ... } SilcSKEKeyMaterial;
240 * This is the key material structure, and is passed as argument by the
241 * application to silc_ske_process_key_material* functions. It includes
242 * the processed key material which can be used as SILC session keys.
246 unsigned char *send_iv;
247 unsigned char *receive_iv;
249 unsigned char *send_enc_key;
250 unsigned char *receive_enc_key;
251 SilcUInt32 enc_key_len;
252 unsigned char *send_hmac_key;
253 unsigned char *receive_hmac_key;
254 SilcUInt32 hmac_key_len;
255 } SilcSKEKeyMaterial;
257 /* Length of cookie in Start Payload */
258 #define SILC_SKE_COOKIE_LEN 16
260 #include "silcske_groups.h"
261 #include "silcske_payload.h"
263 /****d* silcske/SilcSKEAPI/SilcSKESecurityPropertyFlag
267 * typedef enum { ... } SilcSKESecurityPropertyFlag
271 * SKE security property flags as defined by the SK protocol.
276 SILC_SKE_SP_FLAG_NONE = 0x00, /* No flags */
277 SILC_SKE_SP_FLAG_IV_INCLUDED = 0x01, /* IV included in ciphertexts */
278 SILC_SKE_SP_FLAG_PFS = 0x02, /* Perfect Forward Secrecy */
279 SILC_SKE_SP_FLAG_MUTUAL = 0x04, /* Mutual authentication */
280 } SilcSKESecurityPropertyFlag;
283 /****s* silcske/SilcSKEAPI/SilcSKESecurityPropertiesStruct
287 * struct SilcSKESecurityPropertiesStruct { ... };
291 * Security Properties negotiated between key exchange parties. This
292 * structure is filled from the Key Exchange Start Payload which is used
293 * to negotiate what security properties should be used in the
298 struct SilcSKESecurityPropertiesStruct {
299 SilcSKESecurityPropertyFlag flags; /* Flags */
300 SilcSKEDiffieHellmanGroup group; /* Selected Diffie Hellman group */
301 SilcPKCS pkcs; /* Selected PKCS algorithm */
302 SilcCipher cipher; /* Selected cipher */
303 SilcHash hash; /* Selected hash algorithm */
304 SilcHmac hmac; /* Selected HMAC */
308 /****s* silcske/SilcSKEAPI/SilcSKEStruct
312 * struct SilcSKEStruct { ... };
316 * This structure is the SKE session context, and has a type definition
317 * to SilcSKE. The structure includes the network connection socket,
318 * securit properties collected during the SKE negotiation, payloads
319 * sent and received during the negotiation, and the actual raw key
320 * material too. The application usually does not need to reference
321 * to the inside of this structure. However, checking the current
322 * status of the session can easily be checked with ske->status.
326 struct SilcSKEStruct {
327 /* The connection object. This is initialized by the caller. */
329 SilcSocketConnection sock;
332 /* Security properties negotiated */
333 SilcSKESecurityProperties prop;
335 /* Key Exchange payloads filled during key negotiation with
336 remote data. Responder may save local data here as well. */
337 SilcSKEStartPayload *start_payload;
338 SilcSKEKEPayload *ke1_payload;
339 SilcSKEKEPayload *ke2_payload;
340 unsigned char *remote_version;
342 /* Temporary copy of the KE Start Payload used in the
344 SilcBuffer start_payload_copy;
346 /* Random number x, 1 < x < q. This is the secret exponent
347 used in Diffie Hellman computations. */
350 /* The secret shared key */
353 /* The hash value HASH of the key exchange */
357 /* Random Number Generator. This is set by the caller and must
358 be free'd by the caller. */
361 /* Pointer to the what ever user data. This is set by the caller
362 and is not touched by the SKE. The caller must also free this one. */
365 /* Current status of SKE */
366 SilcSKEStatus status;
368 /* Reference counter. This is used when SKE library is performing async
369 operations, like public key verification. */
373 SilcSKECallbacks callbacks;
375 /* Backwards support version indicator */
376 SilcUInt32 backward_version;
382 /****f* silcske/SilcSKEAPI/silc_ske_alloc
386 * SilcSKE silc_ske_alloc(SilcRng rng, void *context);
390 * Allocates the SKE session context and returns it. The `rng' is
391 * the random number generator the SKE is going to use when it needs
392 * random number generation during the SKE session. The `context' is
393 * user context that the libary will not touch. The application can
394 * access that context with the ske->user_context if needed. The
395 * application is responsible of freeing the `context'. After the
396 * SKE session context is allocated application must call the
397 * silc_ske_set_callbacks.
400 SilcSKE silc_ske_alloc(SilcRng rng, void *context);
402 /****f* silcske/SilcSKEAPI/silc_ske_free
406 * void silc_ske_free(SilcSKE ske);
410 * Frees the SKE session context and all allocated resources.
413 void silc_ske_free(SilcSKE ske);
415 /****f* silcske/SilcSKEAPI/silc_ske_set_callbacks
419 * void silc_ske_set_callbacks(SilcSKE ske,
420 * SilcSKESendPacketCb send_packet,
421 * SilcSKECb payload_receive,
422 * SilcSKEVerifyCb verify_key,
423 * SilcSKECb proto_continue,
424 * SilcSKECheckVersion check_version,
429 * Sets the callback functions for the SKE session.
431 * The `send_packet' callback is a function that sends the packet to
432 * network. The SKE library will call it at any time packet needs to
433 * be sent to the remote host.
435 * The `payload_receive' callback is called when the remote host's Key
436 * Exchange Start Payload has been processed. The payload is saved
437 * to ske->start_payload if the application would need it. The application
438 * must also provide the payload to the next state of the SKE.
440 * The `verify_key' callback is called to verify the received public key
441 * or certificate. The verification process is most likely asynchronous.
442 * That is why the application must call the completion callback when the
443 * verification process has been completed. The library then calls the user
444 * callback (`proto_continue'), if it is provided to indicate that the SKE
445 * protocol may continue. If this SKE session context is used to perform
446 * rekey, this callback usually is not provided as argument since sending
447 * public key in rekey is not mandatory. Setting this callback implies
448 * that remote end MUST send its public key, and this could cause
449 * problems when performing rekey. When doing normal SKE session this
450 * callback should be set.
452 * The `proto_continue' callback is called to indicate that it is
453 * safe to continue the execution of the SKE protocol after executing
454 * an asynchronous operation, such as calling the `verify_key' callback
455 * function, which is asynchronous. The application should check the
456 * ske->status in this function to check whether it is Ok to continue
457 * the execution of the protocol.
459 * The `check_version' callback is called to verify the remote host's
460 * version. The application may check its own version against the remote
461 * host's version and determine whether supporting the remote host
464 * The `context' is passed as argument to all of the above callback
468 void silc_ske_set_callbacks(SilcSKE ske,
469 SilcSKESendPacketCb send_packet,
470 SilcSKECb payload_receive,
471 SilcSKEVerifyCb verify_key,
472 SilcSKECb proto_continue,
473 SilcSKECheckVersion check_version,
476 /****f* silcske/SilcSKEAPI/silc_ske_initiator_start
480 * SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng,
481 * SilcSocketConnection sock,
482 * SilcSKEStartPayload
487 * Starts the SILC Key Exchange protocol for initiator. The connection
488 * to the responder end must be established before calling this function
489 * and the connecting socket must be sent as argument. This function
490 * creates the Key Exchange Start Payload which includes all our
491 * configured security properties. This payload is then sent to the
492 * responder end for further processing. This payload must be sent as
493 * argument to the function, however, it must not be encoded
494 * already, it is done by this function. The caller must not free
495 * the `start_payload' since the SKE library will save it.
497 * Before calling this function application calls the
498 * silc_ske_assemble_security_properties which returns the `start_payload'
499 * which application must provide for this function.
501 * After calling this function the application must wait for reply
502 * from the responder.
505 SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng,
507 SilcSocketConnection sock,
509 SilcSKEStartPayload *start_payload);
511 /****f* silcske/SilcSKEAPI/silc_ske_initiator_phase_1
515 * SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske,
516 * SilcBuffer start_payload);
520 * Function called after ske_initiator_start fuction. This receives
521 * the responder's Key Exchange Start payload which includes the
522 * security properties selected by the responder from our payload
523 * sent in the silc_ske_initiator_start function. The `start_payload'
524 * is the received payload and the application must send it as argument.
526 * After calling this function the application must call immediately,
527 * or with short timeout, the silc_ske_initiator_phase_2 function.
530 SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske,
531 SilcBuffer start_payload);
533 /****f* silcske/SilcSKEAPI/silc_ske_initiator_phase_2
537 * SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske,
538 * SilcPublicKey public_key,
539 * SilcPrivateKey private_key,
540 * SilcSKEPKType pk_type)
544 * This function continues the SKE session after the initiator has
545 * called the silc_ske_initiator_phase_1. After that function returns
546 * the application should call immediately, or with short timeout, this
547 * function which will continue with the session, and sends next phase
548 * packet to the responder. The caller must provide the caller's
549 * public key and private key as argument, since the public key is
550 * sent to the responder, and the private key is be used to generate
553 * After this function the application must wait for reply from the
557 SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske,
558 SilcPublicKey public_key,
559 SilcPrivateKey private_key,
560 SilcSKEPKType pk_type);
562 /****f* silcske/SilcSKEAPI/silc_ske_initiator_finish
566 * SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
567 * SilcBuffer ke_payload);
571 * Receives the reply from the responder and processes it. The
572 * `ke_payload' is the reply and application must provide it as argument.
573 * This function will verify the responder's public key, by calling
574 * the `verify_key' callback that was set with silc_ske_set_callbacks
577 * If this function returns error, no callbacks will be called. If
578 * this function needs to verify remote end's public key, this will
579 * return SILC_SKE_STATUS_PENDING, which indicates application that
580 * SKE is performing asynchronous operation and is in pending status.
581 * When in this status application must not continue with calling
582 * any other SKE routine. The asynchronous operation is the `verify_key'
583 * callback, which application completes by calling its completion
584 * callback. After completion the SKE libary will call the
585 * `proto_continue' callback, to indicate application that pending
586 * status is over and it is safe to continue the execution of SKE,
587 * which application does by calling the silc_ske_end function.
589 * If this function returns SILC_SKE_STATUS_OK, it will not call the
590 * `verify_key' callback, however, it will or has already called the
591 * `proto_continue' callback.
593 * Application must not continue execution of the SKE before library
594 * has called the `proto_continue' callback. After it is called
595 * the application finishes SKE session by calling silc_ske_end
599 SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
600 SilcBuffer ke_payload);
602 /****f* silcske/SilcSKEAPI/silc_ske_responder_start
606 * SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
607 * SilcSocketConnection sock,
608 * const char *version,
609 * SilcBuffer start_payload,
610 * SilcSKESecurityPropertyFlag
615 * Starts Key Exchange protocol for responder. The application has
616 * received initiator's first packet from network and it must provide
617 * it as `start_payload' argument to this function. The function
618 * processes the packet and makes security property selection from
619 * the initiator's proposal. The `version' is the responder's version
620 * that will be sent in reply to the initiator. The `flags' indicates
621 * SilcSKESecurityPropertyFlag flags that responder enforces for the
622 * initiator. Responder may, for example, enforce that the PFS
623 * will be performed in rekey. This example can be done by providing
624 * SILC_SKE_SP_FLAG_PFS as `flags'. The `flags' is a bit mask of
627 * After this function the responder calls immediately, or with short
628 * timeout the silc_ske_responder_phase_1 function.
631 SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
633 SilcSocketConnection sock,
636 SilcBuffer start_payload,
637 SilcSKESecurityPropertyFlag flags);
639 /****f* silcske/SilcSKEAPI/silc_ske_responder_phase_1
643 * SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske);
647 * This function is called after the silc_ske_responder_start, and
648 * is used to send our reply to the initiator. This function is
649 * called either immediately, or with short timeout, after the
650 * silc_ske_responder_start function returned.
652 * After this function the responder must wait for reply from the
656 SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske);
658 /****f* silcske/SilcSKEAPI/silc_ske_responder_phase_2
662 * SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
663 * SilcBuffer ke_payload);
667 * Receives the reply from the initiator and procedses it. The
668 * `ke_payload' is the reply and application must provide it as argument.
669 * This function will verify the remote host's public key, by calling
670 * the `verify_key' callback that was set with silc_ske_set_callbacks
673 * If this function returns error, no callbacks will be called. If
674 * this function needs to verify remote end's public key, this will
675 * return SILC_SKE_STATUS_PENDING, which indicates application that
676 * SKE is performing asynchronous operation and is in pending status.
677 * When in this status application must not continue with calling
678 * any other SKE routine. The asynchronous operation is the `verify_key'
679 * callback, which application completes by calling its completion
680 * callback. After completion the SKE libary will call the
681 * `proto_continue' callback, to indicate application that pending
682 * status is over and it is safe to continue the execution of SKE,
683 * which application does by calling the silc_ske_responder_finish
686 * If this function returns SILC_SKE_STATUS_OK, it will not call the
687 * `verify_key' callback, however, it will or has already called the
688 * `proto_continue' callback.
690 * Application must not continue execution of the SKE before library
691 * has called the `proto_continue' callback. After it is called
692 * the application calls the silc_ske_responder_finish function.
695 SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
696 SilcBuffer ke_payload);
698 /****f* silcske/SilcSKEAPI/silc_ske_responder_finish
702 * SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
703 * SilcPublicKey public_key,
704 * SilcPrivateKey private_key,
705 * SilcSKEPKType pk_type);
709 * This function finishes the responder's SKE session, and this function
710 * is called either immediately, or with short timeout, after the
711 * silc_ske_responder_phase_2 returned. This will send our reply to
712 * the initiator. The caller must provide the caller's public key and
713 * private key as argument, since the public key is sent to the responder,
714 * and the private key is be used to generate digital signature.
716 * After this function the application must wait for the end indication
717 * from the intiator, and when it is received the silc_ske_end is called.
720 SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
721 SilcPublicKey public_key,
722 SilcPrivateKey private_key,
723 SilcSKEPKType pk_type);
725 /****f* silcske/SilcSKEAPI/silc_ske_end
729 * SilcSKEStatus silc_ske_end(SilcSKE ske);
733 * The Key Exchange protocol is ended by calling this function. This
734 * must not be called until the keys are processed by calling the
735 * silc_ske_process_key_material function. The protocol prohibits
736 * calling this function before key material is processed properly.
738 * This function is for both initiator and responder. After calling
739 * this function initiator must wait for end indication from the
740 * responder. After that the silc_ske_free may be called. The responder
741 * calls this function after it has received the intiator's end
746 * Initiator must not start using the negotiated key material before
747 * calling this function or before remote end has sent its end
748 * indication. Only after that the key material may be taken in use.
751 SilcSKEStatus silc_ske_end(SilcSKE ske);
753 /****f* silcske/SilcSKEAPI/silc_ske_abort
757 * SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status);
761 * Aborts the Key Exchange protocol. This is called if error occurs
762 * while performing the protocol. The status argument is the error
763 * status and it is sent to the remote end.
766 SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status);
768 /****f* silcske/SilcSKEAPI/silc_ske_assemble_security_properties
773 * silc_ske_assemble_security_properties(SilcSKE ske,
774 * SilcSKESecurityPropertyFlag flags,
775 * const char *version,
776 * SilcSKEStartPayload
781 * Assembles security properties to Key Exchange Start Payload to be
782 * sent to the remote end. This checks system wide (SILC system, that is)
783 * settings and chooses from those. However, if other properties
784 * should be used this function is easy to replace by another function,
785 * as, this function is called by the caller of the library and not
786 * by the SKE library itself. The assembled payload is returned into
787 * the `return_payload' pointer.
791 silc_ske_assemble_security_properties(SilcSKE ske,
792 SilcSKESecurityPropertyFlag flags,
794 SilcSKEStartPayload **return_payload);
796 /****f* silcske/SilcSKEAPI/silc_ske_select_security_properties
801 * silc_ske_select_security_properties(SilcSKE ske,
802 * const char *version,
803 * SilcSKEStartPayload *payload,
804 * SilcSKEStartPayload *remote_payload);
808 * Parses the Key Exchange Start Payload indicated by `remote_payload',
809 * and selects the security properties properties from it, and puts the
810 * selection into the `payload'. This always attempts to select the
811 * best security properties from the payload, and it always selects
812 * one of each kind of security property, as this is dictated by the
813 * protocol. The `version' is our version, that we will put to the
814 * `payload', since the `payload' is usually sent to the remote end.
815 * the `check_version' callback will be called in this function so
816 * that application can do version check with the remote end.
820 silc_ske_select_security_properties(SilcSKE ske,
822 SilcSKEStartPayload *payload,
823 SilcSKEStartPayload *remote_payload);
825 /****f* silcske/SilcSKEAPI/silc_ske_process_key_material
829 * SilcSKEStatus silc_ske_process_key_material(SilcSKE ske,
830 * SilcUInt32 req_iv_len,
831 * SilcUInt32 req_enc_key_len,
832 * SilcUInt32 req_hmac_key_len,
833 * SilcSKEKeyMaterial *key);
837 * This function is used by the application to process the key material
838 * negotiated with the SKE session, to actually produce the keys that
839 * is to be used in SILC protocol. The key processing is defined by the
840 * protocol. The `req_iv_len', `req_enc_key_len' and `req_hmac_key_len'
841 * are the request IV length, requested encryption/decrypt key length,
842 * and requested HMAC key length, respectively, and they cannot be
843 * zero (0). They tell the function how long the keys should be, and
844 * it will produce the requested length keys for the application.
845 * The key material is returned in to the `key', which the caller must
849 SilcSKEStatus silc_ske_process_key_material(SilcSKE ske,
850 SilcUInt32 req_iv_len,
851 SilcUInt32 req_enc_key_len,
852 SilcUInt32 req_hmac_key_len,
853 SilcSKEKeyMaterial *key);
855 /****f* silcske/SilcSKEAPI/silc_ske_process_key_material_data
860 * silc_ske_process_key_material_data(unsigned char *data,
861 * SilcUInt32 data_len,
862 * SilcUInt32 req_iv_len,
863 * SilcUInt32 req_enc_key_len,
864 * SilcUInt32 req_hmac_key_len,
866 * SilcSKEKeyMaterial *key);
870 * This function is equivalent to silc_ske_process_key_material, except
871 * that the caller provides the raw key material as argument, the `data'
872 * and `data_len'. This is special utility function provided for the
873 * application, if it needs to generate key material as the protocol
874 * defines for some other purpose than strictly SILC session key usage.
875 * Hence, this function can be used outside SKE protocol to just produce
876 * key material from some raw data. The `hash' is a hash algorithm that
877 * is used as part of key processing, and caller must provide it.
881 silc_ske_process_key_material_data(unsigned char *data,
883 SilcUInt32 req_iv_len,
884 SilcUInt32 req_enc_key_len,
885 SilcUInt32 req_hmac_key_len,
887 SilcSKEKeyMaterial *key);
889 /****f* silcske/SilcSKEAPI/silc_ske_free_key_material
893 * void silc_ske_free_key_material(SilcSKEKeyMaterial *key);
897 * Frees the key material indicated by `key', and all data in it.
900 void silc_ske_free_key_material(SilcSKEKeyMaterial *key);
902 /****f* silcske/SilcSKEAPI/silc_ske_parse_version
906 * bool silc_ske_parse_version(SilcSKE ske,
907 * SilcUInt32 *protocol_version,
908 * char **protocol_version_string,
909 * SilcUInt32 *software_version,
910 * char **software_version_string,
911 * char **vendor_version);
915 * This utility function can be used to parse the remote host's version
916 * string. This returns the protocol version, and software version into
917 * the `protocol_version', `software_version' and `vendor_version' pointers
918 * if they are provided. The string versions of the versions are saved
919 * in *_string pointers if they are provided. Returns TRUE if the version
920 * string was successfully parsed.
923 bool silc_ske_parse_version(SilcSKE ske,
924 SilcUInt32 *protocol_version,
925 char **protocol_version_string,
926 SilcUInt32 *software_version,
927 char **software_version_string,
928 char **vendor_version);
930 #endif /* !SILCSKE_H */