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_NO_REPLY = 0x01, /* No reply required to payload */
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. */
328 SilcSocketConnection sock;
330 /* Security properties negotiated */
331 SilcSKESecurityProperties prop;
333 /* Key Exchange payloads filled during key negotiation with
334 remote data. Responder may save local data here as well. */
335 SilcSKEStartPayload *start_payload;
336 SilcSKEKEPayload *ke1_payload;
337 SilcSKEKEPayload *ke2_payload;
339 /* Temporary copy of the KE Start Payload used in the
341 SilcBuffer start_payload_copy;
343 /* Random number x, 1 < x < q. This is the secret exponent
344 used in Diffie Hellman computations. */
347 /* The secret shared key */
350 /* The hash value HASH of the key exchange */
354 /* Random Number Generator. This is set by the caller and must
355 be free'd by the caller. */
358 /* Pointer to the what ever user data. This is set by the caller
359 and is not touched by the SKE. The caller must also free this one. */
362 /* Current status of SKE */
363 SilcSKEStatus status;
365 /* Reference counter. This is used when SKE library is performing async
366 operations, like public key verification. */
370 SilcSKECallbacks callbacks;
372 /* Backwards support version indicator */
373 SilcUInt32 backward_version;
379 /****f* silcske/SilcSKEAPI/silc_ske_alloc
383 * SilcSKE silc_ske_alloc(SilcRng rng, void *context);
387 * Allocates the SKE session context and returns it. The `rng' is
388 * the random number generator the SKE is going to use when it needs
389 * random number generation during the SKE session. The `context' is
390 * user context that the libary will not touch. The application can
391 * access that context with the ske->user_context if needed. The
392 * application is responsible of freeing the `context'. After the
393 * SKE session context is allocated application must call the
394 * silc_ske_set_callbacks.
397 SilcSKE silc_ske_alloc(SilcRng rng, void *context);
399 /****f* silcske/SilcSKEAPI/silc_ske_free
403 * void silc_ske_free(SilcSKE ske);
407 * Frees the SKE session context and all allocated resources.
410 void silc_ske_free(SilcSKE ske);
412 /****f* silcske/SilcSKEAPI/silc_ske_set_callbacks
416 * void silc_ske_set_callbacks(SilcSKE ske,
417 * SilcSKESendPacketCb send_packet,
418 * SilcSKECb payload_receive,
419 * SilcSKEVerifyCb verify_key,
420 * SilcSKECb proto_continue,
421 * SilcSKECheckVersion check_version,
426 * Sets the callback functions for the SKE session.
428 * The `send_packet' callback is a function that sends the packet to
429 * network. The SKE library will call it at any time packet needs to
430 * be sent to the remote host.
432 * The `payload_receive' callback is called when the remote host's Key
433 * Exchange Start Payload has been processed. The payload is saved
434 * to ske->start_payload if the application would need it. The application
435 * must also provide the payload to the next state of the SKE.
437 * The `verify_key' callback is called to verify the received public key
438 * or certificate. The verification process is most likely asynchronous.
439 * That is why the application must call the completion callback when the
440 * verification process has been completed. The library then calls the user
441 * callback (`proto_continue'), if it is provided to indicate that the SKE
442 * protocol may continue. If this SKE session context is used to perform
443 * rekey, this callback usually is not provided as argument since sending
444 * public key in rekey is not mandatory. Setting this callback implies
445 * that remote end MUST send its public key, and this could cause
446 * problems when performing rekey. When doing normal SKE session this
447 * callback should be set.
449 * The `proto_continue' callback is called to indicate that it is
450 * safe to continue the execution of the SKE protocol after executing
451 * an asynchronous operation, such as calling the `verify_key' callback
452 * function, which is asynchronous. The application should check the
453 * ske->status in this function to check whether it is Ok to continue
454 * the execution of the protocol.
456 * The `check_version' callback is called to verify the remote host's
457 * version. The application may check its own version against the remote
458 * host's version and determine whether supporting the remote host
461 * The `context' is passed as argument to all of the above callback
465 void silc_ske_set_callbacks(SilcSKE ske,
466 SilcSKESendPacketCb send_packet,
467 SilcSKECb payload_receive,
468 SilcSKEVerifyCb verify_key,
469 SilcSKECb proto_continue,
470 SilcSKECheckVersion check_version,
473 /****f* silcske/SilcSKEAPI/silc_ske_initiator_start
477 * SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng,
478 * SilcSocketConnection sock,
479 * SilcSKEStartPayload
484 * Starts the SILC Key Exchange protocol for initiator. The connection
485 * to the responder end must be established before calling this function
486 * and the connecting socket must be sent as argument. This function
487 * creates the Key Exchange Start Payload which includes all our
488 * configured security properties. This payload is then sent to the
489 * responder end for further processing. This payload must be sent as
490 * argument to the function, however, it must not be encoded
491 * already, it is done by this function. The caller must not free
492 * the `start_payload' since the SKE library will save it.
494 * Before calling this function application calls the
495 * silc_ske_assemble_security_properties which returns the `start_payload'
496 * which application must provide for this function.
498 * After calling this function the application must wait for reply
499 * from the responder.
502 SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng,
503 SilcSocketConnection sock,
504 SilcSKEStartPayload *start_payload);
506 /****f* silcske/SilcSKEAPI/silc_ske_initiator_phase_1
510 * SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske,
511 * SilcBuffer start_payload);
515 * Function called after ske_initiator_start fuction. This receives
516 * the responder's Key Exchange Start payload which includes the
517 * security properties selected by the responder from our payload
518 * sent in the silc_ske_initiator_start function. The `start_payload'
519 * is the received payload and the application must send it as argument.
521 * After calling this function the application must call immediately,
522 * or with short timeout, the silc_ske_initiator_phase_2 function.
525 SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske,
526 SilcBuffer start_payload);
528 /****f* silcske/SilcSKEAPI/silc_ske_initiator_phase_2
532 * SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske,
533 * SilcPublicKey public_key,
534 * SilcPrivateKey private_key,
535 * SilcSKEPKType pk_type)
539 * This function continues the SKE session after the initiator has
540 * called the silc_ske_initiator_phase_1. After that function returns
541 * the application should call immediately, or with short timeout, this
542 * function which will continue with the session, and sends next phase
543 * packet to the responder. The caller must provide the caller's
544 * public key and private key as argument, since the public key is
545 * sent to the responder, and the private key is be used to generate
548 * After this function the application must wait for reply from the
552 SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske,
553 SilcPublicKey public_key,
554 SilcPrivateKey private_key,
555 SilcSKEPKType pk_type);
557 /****f* silcske/SilcSKEAPI/silc_ske_initiator_finish
561 * SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
562 * SilcBuffer ke_payload);
566 * Receives the reply from the responder and processes it. The
567 * `ke_payload' is the reply and application must provide it as argument.
568 * This function will verify the responder's public key, by calling
569 * the `verify_key' callback that was set with silc_ske_set_callbacks
572 * If this function returns error, no callbacks will be called. If
573 * this function needs to verify remote end's public key, this will
574 * return SILC_SKE_STATUS_PENDING, which indicates application that
575 * SKE is performing asynchronous operation and is in pending status.
576 * When in this status application must not continue with calling
577 * any other SKE routine. The asynchronous operation is the `verify_key'
578 * callback, which application completes by calling its completion
579 * callback. After completion the SKE libary will call the
580 * `proto_continue' callback, to indicate application that pending
581 * status is over and it is safe to continue the execution of SKE,
582 * which application does by calling the silc_ske_end function.
584 * If this function returns SILC_SKE_STATUS_OK, it will not call the
585 * `verify_key' callback, however, it will or has already called the
586 * `proto_continue' callback.
588 * Application must not continue execution of the SKE before library
589 * has called the `proto_continue' callback. After it is called
590 * the application finishes SKE session by calling silc_ske_end
594 SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
595 SilcBuffer ke_payload);
597 /****f* silcske/SilcSKEAPI/silc_ske_responder_start
601 * SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
602 * SilcSocketConnection sock,
603 * const char *version,
604 * SilcBuffer start_payload,
605 * SilcSKESecurityPropertyFlag
610 * Starts Key Exchange protocol for responder. The application has
611 * received initiator's first packet from network and it must provide
612 * it as `start_payload' argument to this function. The function
613 * processes the packet and makes security property selection from
614 * the initiator's proposal. The `version' is the responder's version
615 * that will be sent in reply to the initiator. The `flags' indicates
616 * SilcSKESecurityPropertyFlag flags that responder enforces for the
617 * initiator. Responder may, for example, enforce that the PFS
618 * will be performed in rekey. This example can be done by providing
619 * SILC_SKE_SP_FLAG_PFS as `flags'. The `flags' is a bit mask of
622 * After this function the responder calls immediately, or with short
623 * timeout the silc_ske_responder_phase_1 function.
626 SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
627 SilcSocketConnection sock,
629 SilcBuffer start_payload,
630 SilcSKESecurityPropertyFlag flags);
632 /****f* silcske/SilcSKEAPI/silc_ske_responder_phase_1
636 * SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske);
640 * This function is called after the silc_ske_responder_start, and
641 * is used to send our reply to the initiator. This function is
642 * called either immediately, or with short timeout, after the
643 * silc_ske_responder_start function returned.
645 * After this function the responder must wait for reply from the
649 SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske);
651 /****f* silcske/SilcSKEAPI/silc_ske_responder_phase_2
655 * SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
656 * SilcBuffer ke_payload);
660 * Receives the reply from the initiator and procedses it. The
661 * `ke_payload' is the reply and application must provide it as argument.
662 * This function will verify the remote host's public key, by calling
663 * the `verify_key' callback that was set with silc_ske_set_callbacks
666 * If this function returns error, no callbacks will be called. If
667 * this function needs to verify remote end's public key, this will
668 * return SILC_SKE_STATUS_PENDING, which indicates application that
669 * SKE is performing asynchronous operation and is in pending status.
670 * When in this status application must not continue with calling
671 * any other SKE routine. The asynchronous operation is the `verify_key'
672 * callback, which application completes by calling its completion
673 * callback. After completion the SKE libary will call the
674 * `proto_continue' callback, to indicate application that pending
675 * status is over and it is safe to continue the execution of SKE,
676 * which application does by calling the silc_ske_responder_finish
679 * If this function returns SILC_SKE_STATUS_OK, it will not call the
680 * `verify_key' callback, however, it will or has already called the
681 * `proto_continue' callback.
683 * Application must not continue execution of the SKE before library
684 * has called the `proto_continue' callback. After it is called
685 * the application calls the silc_ske_responder_finish function.
688 SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
689 SilcBuffer ke_payload);
691 /****f* silcske/SilcSKEAPI/silc_ske_responder_finish
695 * SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
696 * SilcPublicKey public_key,
697 * SilcPrivateKey private_key,
698 * SilcSKEPKType pk_type);
702 * This function finishes the responder's SKE session, and this function
703 * is called either immediately, or with short timeout, after the
704 * silc_ske_responder_phase_2 returned. This will send our reply to
705 * the initiator. The caller must provide the caller's public key and
706 * private key as argument, since the public key is sent to the responder,
707 * and the private key is be used to generate digital signature.
709 * After this function the application must wait for the end indication
710 * from the intiator, and when it is received the silc_ske_end is called.
713 SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
714 SilcPublicKey public_key,
715 SilcPrivateKey private_key,
716 SilcSKEPKType pk_type);
718 /****f* silcske/SilcSKEAPI/silc_ske_end
722 * SilcSKEStatus silc_ske_end(SilcSKE ske);
726 * The Key Exchange protocol is ended by calling this function. This
727 * must not be called until the keys are processed by calling the
728 * silc_ske_process_key_material function. The protocol prohibits
729 * calling this function before key material is processed properly.
731 * This function is for both initiator and responder. After calling
732 * this function initiator must wait for end indication from the
733 * responder. After that the silc_ske_free may be called. The responder
734 * calls this function after it has received the intiator's end
739 * Initiator must not start using the negotiated key material before
740 * calling this function or before remote end has sent its end
741 * indication. Only after that the key material may be taken in use.
744 SilcSKEStatus silc_ske_end(SilcSKE ske);
746 /****f* silcske/SilcSKEAPI/silc_ske_abort
750 * SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status);
754 * Aborts the Key Exchange protocol. This is called if error occurs
755 * while performing the protocol. The status argument is the error
756 * status and it is sent to the remote end.
759 SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status);
761 /****f* silcske/SilcSKEAPI/silc_ske_assemble_security_properties
766 * silc_ske_assemble_security_properties(SilcSKE ske,
767 * SilcSKESecurityPropertyFlag flags,
768 * const char *version,
769 * SilcSKEStartPayload
774 * Assembles security properties to Key Exchange Start Payload to be
775 * sent to the remote end. This checks system wide (SILC system, that is)
776 * settings and chooses from those. However, if other properties
777 * should be used this function is easy to replace by another function,
778 * as, this function is called by the caller of the library and not
779 * by the SKE library itself. The assembled payload is returned into
780 * the `return_payload' pointer.
784 silc_ske_assemble_security_properties(SilcSKE ske,
785 SilcSKESecurityPropertyFlag flags,
787 SilcSKEStartPayload **return_payload);
789 /****f* silcske/SilcSKEAPI/silc_ske_select_security_properties
794 * silc_ske_select_security_properties(SilcSKE ske,
795 * const char *version,
796 * SilcSKEStartPayload *payload,
797 * SilcSKEStartPayload *remote_payload);
801 * Parses the Key Exchange Start Payload indicated by `remote_payload',
802 * and selects the security properties properties from it, and puts the
803 * selection into the `payload'. This always attempts to select the
804 * best security properties from the payload, and it always selects
805 * one of each kind of security property, as this is dictated by the
806 * protocol. The `version' is our version, that we will put to the
807 * `payload', since the `payload' is usually sent to the remote end.
808 * the `check_version' callback will be called in this function so
809 * that application can do version check with the remote end.
813 silc_ske_select_security_properties(SilcSKE ske,
815 SilcSKEStartPayload *payload,
816 SilcSKEStartPayload *remote_payload);
818 /****f* silcske/SilcSKEAPI/silc_ske_process_key_material
822 * SilcSKEStatus silc_ske_process_key_material(SilcSKE ske,
823 * SilcUInt32 req_iv_len,
824 * SilcUInt32 req_enc_key_len,
825 * SilcUInt32 req_hmac_key_len,
826 * SilcSKEKeyMaterial *key);
830 * This function is used by the application to process the key material
831 * negotiated with the SKE session, to actually produce the keys that
832 * is to be used in SILC protocol. The key processing is defined by the
833 * protocol. The `req_iv_len', `req_enc_key_len' and `req_hmac_key_len'
834 * are the request IV length, requested encryption/decrypt key length,
835 * and requested HMAC key length, respectively, and they cannot be
836 * zero (0). They tell the function how long the keys should be, and
837 * it will produce the requested length keys for the application.
838 * The key material is returned in to the `key', which the caller must
842 SilcSKEStatus silc_ske_process_key_material(SilcSKE ske,
843 SilcUInt32 req_iv_len,
844 SilcUInt32 req_enc_key_len,
845 SilcUInt32 req_hmac_key_len,
846 SilcSKEKeyMaterial *key);
848 /****f* silcske/SilcSKEAPI/silc_ske_process_key_material_data
853 * silc_ske_process_key_material_data(unsigned char *data,
854 * SilcUInt32 data_len,
855 * SilcUInt32 req_iv_len,
856 * SilcUInt32 req_enc_key_len,
857 * SilcUInt32 req_hmac_key_len,
859 * SilcSKEKeyMaterial *key);
863 * This function is equivalent to silc_ske_process_key_material, except
864 * that the caller provides the raw key material as argument, the `data'
865 * and `data_len'. This is special utility function provided for the
866 * application, if it needs to generate key material as the protocol
867 * defines for some other purpose than strictly SILC session key usage.
868 * Hence, this function can be used outside SKE protocol to just produce
869 * key material from some raw data. The `hash' is a hash algorithm that
870 * is used as part of key processing, and caller must provide it.
874 silc_ske_process_key_material_data(unsigned char *data,
876 SilcUInt32 req_iv_len,
877 SilcUInt32 req_enc_key_len,
878 SilcUInt32 req_hmac_key_len,
880 SilcSKEKeyMaterial *key);
882 /****f* silcske/SilcSKEAPI/silc_ske_free_key_material
886 * void silc_ske_free_key_material(SilcSKEKeyMaterial *key);
890 * Frees the key material indicated by `key', and all data in it.
893 void silc_ske_free_key_material(SilcSKEKeyMaterial *key);
895 /****f* silcske/SilcSKEAPI/silc_ske_parse_version
899 * bool silc_ske_parse_version(SilcSKE ske,
900 * SilcUInt32 *protocol_version,
901 * char **protocol_version_string,
902 * SilcUInt32 *software_version,
903 * char **software_version_string,
904 * char **vendor_version);
908 * This utility function can be used to parse the remote host's version
909 * string. This returns the protocol version, and software version into
910 * the `protocol_version', `software_version' and `vendor_version' pointers
911 * if they are provided. The string versions of the versions are saved
912 * in *_string pointers if they are provided. Returns TRUE if the version
913 * string was successfully parsed.
916 bool silc_ske_parse_version(SilcSKE ske,
917 SilcUInt32 *protocol_version,
918 char **protocol_version_string,
919 SilcUInt32 *software_version,
920 char **software_version_string,
921 char **vendor_version);
923 #endif /* !SILCSKE_H */