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;
338 unsigned char *remote_version;
340 /* Temporary copy of the KE Start Payload used in the
342 SilcBuffer start_payload_copy;
344 /* Random number x, 1 < x < q. This is the secret exponent
345 used in Diffie Hellman computations. */
348 /* The secret shared key */
351 /* The hash value HASH of the key exchange */
355 /* Random Number Generator. This is set by the caller and must
356 be free'd by the caller. */
359 /* Pointer to the what ever user data. This is set by the caller
360 and is not touched by the SKE. The caller must also free this one. */
363 /* Current status of SKE */
364 SilcSKEStatus status;
366 /* Reference counter. This is used when SKE library is performing async
367 operations, like public key verification. */
371 SilcSKECallbacks callbacks;
373 /* Backwards support version indicator */
374 SilcUInt32 backward_version;
380 /****f* silcske/SilcSKEAPI/silc_ske_alloc
384 * SilcSKE silc_ske_alloc(SilcRng rng, void *context);
388 * Allocates the SKE session context and returns it. The `rng' is
389 * the random number generator the SKE is going to use when it needs
390 * random number generation during the SKE session. The `context' is
391 * user context that the libary will not touch. The application can
392 * access that context with the ske->user_context if needed. The
393 * application is responsible of freeing the `context'. After the
394 * SKE session context is allocated application must call the
395 * silc_ske_set_callbacks.
398 SilcSKE silc_ske_alloc(SilcRng rng, void *context);
400 /****f* silcske/SilcSKEAPI/silc_ske_free
404 * void silc_ske_free(SilcSKE ske);
408 * Frees the SKE session context and all allocated resources.
411 void silc_ske_free(SilcSKE ske);
413 /****f* silcske/SilcSKEAPI/silc_ske_set_callbacks
417 * void silc_ske_set_callbacks(SilcSKE ske,
418 * SilcSKESendPacketCb send_packet,
419 * SilcSKECb payload_receive,
420 * SilcSKEVerifyCb verify_key,
421 * SilcSKECb proto_continue,
422 * SilcSKECheckVersion check_version,
427 * Sets the callback functions for the SKE session.
429 * The `send_packet' callback is a function that sends the packet to
430 * network. The SKE library will call it at any time packet needs to
431 * be sent to the remote host.
433 * The `payload_receive' callback is called when the remote host's Key
434 * Exchange Start Payload has been processed. The payload is saved
435 * to ske->start_payload if the application would need it. The application
436 * must also provide the payload to the next state of the SKE.
438 * The `verify_key' callback is called to verify the received public key
439 * or certificate. The verification process is most likely asynchronous.
440 * That is why the application must call the completion callback when the
441 * verification process has been completed. The library then calls the user
442 * callback (`proto_continue'), if it is provided to indicate that the SKE
443 * protocol may continue. If this SKE session context is used to perform
444 * rekey, this callback usually is not provided as argument since sending
445 * public key in rekey is not mandatory. Setting this callback implies
446 * that remote end MUST send its public key, and this could cause
447 * problems when performing rekey. When doing normal SKE session this
448 * callback should be set.
450 * The `proto_continue' callback is called to indicate that it is
451 * safe to continue the execution of the SKE protocol after executing
452 * an asynchronous operation, such as calling the `verify_key' callback
453 * function, which is asynchronous. The application should check the
454 * ske->status in this function to check whether it is Ok to continue
455 * the execution of the protocol.
457 * The `check_version' callback is called to verify the remote host's
458 * version. The application may check its own version against the remote
459 * host's version and determine whether supporting the remote host
462 * The `context' is passed as argument to all of the above callback
466 void silc_ske_set_callbacks(SilcSKE ske,
467 SilcSKESendPacketCb send_packet,
468 SilcSKECb payload_receive,
469 SilcSKEVerifyCb verify_key,
470 SilcSKECb proto_continue,
471 SilcSKECheckVersion check_version,
474 /****f* silcske/SilcSKEAPI/silc_ske_initiator_start
478 * SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng,
479 * SilcSocketConnection sock,
480 * SilcSKEStartPayload
485 * Starts the SILC Key Exchange protocol for initiator. The connection
486 * to the responder end must be established before calling this function
487 * and the connecting socket must be sent as argument. This function
488 * creates the Key Exchange Start Payload which includes all our
489 * configured security properties. This payload is then sent to the
490 * responder end for further processing. This payload must be sent as
491 * argument to the function, however, it must not be encoded
492 * already, it is done by this function. The caller must not free
493 * the `start_payload' since the SKE library will save it.
495 * Before calling this function application calls the
496 * silc_ske_assemble_security_properties which returns the `start_payload'
497 * which application must provide for this function.
499 * After calling this function the application must wait for reply
500 * from the responder.
503 SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng,
504 SilcSocketConnection sock,
505 SilcSKEStartPayload *start_payload);
507 /****f* silcske/SilcSKEAPI/silc_ske_initiator_phase_1
511 * SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske,
512 * SilcBuffer start_payload);
516 * Function called after ske_initiator_start fuction. This receives
517 * the responder's Key Exchange Start payload which includes the
518 * security properties selected by the responder from our payload
519 * sent in the silc_ske_initiator_start function. The `start_payload'
520 * is the received payload and the application must send it as argument.
522 * After calling this function the application must call immediately,
523 * or with short timeout, the silc_ske_initiator_phase_2 function.
526 SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske,
527 SilcBuffer start_payload);
529 /****f* silcske/SilcSKEAPI/silc_ske_initiator_phase_2
533 * SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske,
534 * SilcPublicKey public_key,
535 * SilcPrivateKey private_key,
536 * SilcSKEPKType pk_type)
540 * This function continues the SKE session after the initiator has
541 * called the silc_ske_initiator_phase_1. After that function returns
542 * the application should call immediately, or with short timeout, this
543 * function which will continue with the session, and sends next phase
544 * packet to the responder. The caller must provide the caller's
545 * public key and private key as argument, since the public key is
546 * sent to the responder, and the private key is be used to generate
549 * After this function the application must wait for reply from the
553 SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske,
554 SilcPublicKey public_key,
555 SilcPrivateKey private_key,
556 SilcSKEPKType pk_type);
558 /****f* silcske/SilcSKEAPI/silc_ske_initiator_finish
562 * SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
563 * SilcBuffer ke_payload);
567 * Receives the reply from the responder and processes it. The
568 * `ke_payload' is the reply and application must provide it as argument.
569 * This function will verify the responder's public key, by calling
570 * the `verify_key' callback that was set with silc_ske_set_callbacks
573 * If this function returns error, no callbacks will be called. If
574 * this function needs to verify remote end's public key, this will
575 * return SILC_SKE_STATUS_PENDING, which indicates application that
576 * SKE is performing asynchronous operation and is in pending status.
577 * When in this status application must not continue with calling
578 * any other SKE routine. The asynchronous operation is the `verify_key'
579 * callback, which application completes by calling its completion
580 * callback. After completion the SKE libary will call the
581 * `proto_continue' callback, to indicate application that pending
582 * status is over and it is safe to continue the execution of SKE,
583 * which application does by calling the silc_ske_end function.
585 * If this function returns SILC_SKE_STATUS_OK, it will not call the
586 * `verify_key' callback, however, it will or has already called the
587 * `proto_continue' callback.
589 * Application must not continue execution of the SKE before library
590 * has called the `proto_continue' callback. After it is called
591 * the application finishes SKE session by calling silc_ske_end
595 SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
596 SilcBuffer ke_payload);
598 /****f* silcske/SilcSKEAPI/silc_ske_responder_start
602 * SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
603 * SilcSocketConnection sock,
604 * const char *version,
605 * SilcBuffer start_payload,
606 * SilcSKESecurityPropertyFlag
611 * Starts Key Exchange protocol for responder. The application has
612 * received initiator's first packet from network and it must provide
613 * it as `start_payload' argument to this function. The function
614 * processes the packet and makes security property selection from
615 * the initiator's proposal. The `version' is the responder's version
616 * that will be sent in reply to the initiator. The `flags' indicates
617 * SilcSKESecurityPropertyFlag flags that responder enforces for the
618 * initiator. Responder may, for example, enforce that the PFS
619 * will be performed in rekey. This example can be done by providing
620 * SILC_SKE_SP_FLAG_PFS as `flags'. The `flags' is a bit mask of
623 * After this function the responder calls immediately, or with short
624 * timeout the silc_ske_responder_phase_1 function.
627 SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
628 SilcSocketConnection sock,
630 SilcBuffer start_payload,
631 SilcSKESecurityPropertyFlag flags);
633 /****f* silcske/SilcSKEAPI/silc_ske_responder_phase_1
637 * SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske);
641 * This function is called after the silc_ske_responder_start, and
642 * is used to send our reply to the initiator. This function is
643 * called either immediately, or with short timeout, after the
644 * silc_ske_responder_start function returned.
646 * After this function the responder must wait for reply from the
650 SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske);
652 /****f* silcske/SilcSKEAPI/silc_ske_responder_phase_2
656 * SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
657 * SilcBuffer ke_payload);
661 * Receives the reply from the initiator and procedses it. The
662 * `ke_payload' is the reply and application must provide it as argument.
663 * This function will verify the remote host's public key, by calling
664 * the `verify_key' callback that was set with silc_ske_set_callbacks
667 * If this function returns error, no callbacks will be called. If
668 * this function needs to verify remote end's public key, this will
669 * return SILC_SKE_STATUS_PENDING, which indicates application that
670 * SKE is performing asynchronous operation and is in pending status.
671 * When in this status application must not continue with calling
672 * any other SKE routine. The asynchronous operation is the `verify_key'
673 * callback, which application completes by calling its completion
674 * callback. After completion the SKE libary will call the
675 * `proto_continue' callback, to indicate application that pending
676 * status is over and it is safe to continue the execution of SKE,
677 * which application does by calling the silc_ske_responder_finish
680 * If this function returns SILC_SKE_STATUS_OK, it will not call the
681 * `verify_key' callback, however, it will or has already called the
682 * `proto_continue' callback.
684 * Application must not continue execution of the SKE before library
685 * has called the `proto_continue' callback. After it is called
686 * the application calls the silc_ske_responder_finish function.
689 SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
690 SilcBuffer ke_payload);
692 /****f* silcske/SilcSKEAPI/silc_ske_responder_finish
696 * SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
697 * SilcPublicKey public_key,
698 * SilcPrivateKey private_key,
699 * SilcSKEPKType pk_type);
703 * This function finishes the responder's SKE session, and this function
704 * is called either immediately, or with short timeout, after the
705 * silc_ske_responder_phase_2 returned. This will send our reply to
706 * the initiator. The caller must provide the caller's public key and
707 * private key as argument, since the public key is sent to the responder,
708 * and the private key is be used to generate digital signature.
710 * After this function the application must wait for the end indication
711 * from the intiator, and when it is received the silc_ske_end is called.
714 SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
715 SilcPublicKey public_key,
716 SilcPrivateKey private_key,
717 SilcSKEPKType pk_type);
719 /****f* silcske/SilcSKEAPI/silc_ske_end
723 * SilcSKEStatus silc_ske_end(SilcSKE ske);
727 * The Key Exchange protocol is ended by calling this function. This
728 * must not be called until the keys are processed by calling the
729 * silc_ske_process_key_material function. The protocol prohibits
730 * calling this function before key material is processed properly.
732 * This function is for both initiator and responder. After calling
733 * this function initiator must wait for end indication from the
734 * responder. After that the silc_ske_free may be called. The responder
735 * calls this function after it has received the intiator's end
740 * Initiator must not start using the negotiated key material before
741 * calling this function or before remote end has sent its end
742 * indication. Only after that the key material may be taken in use.
745 SilcSKEStatus silc_ske_end(SilcSKE ske);
747 /****f* silcske/SilcSKEAPI/silc_ske_abort
751 * SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status);
755 * Aborts the Key Exchange protocol. This is called if error occurs
756 * while performing the protocol. The status argument is the error
757 * status and it is sent to the remote end.
760 SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status);
762 /****f* silcske/SilcSKEAPI/silc_ske_assemble_security_properties
767 * silc_ske_assemble_security_properties(SilcSKE ske,
768 * SilcSKESecurityPropertyFlag flags,
769 * const char *version,
770 * SilcSKEStartPayload
775 * Assembles security properties to Key Exchange Start Payload to be
776 * sent to the remote end. This checks system wide (SILC system, that is)
777 * settings and chooses from those. However, if other properties
778 * should be used this function is easy to replace by another function,
779 * as, this function is called by the caller of the library and not
780 * by the SKE library itself. The assembled payload is returned into
781 * the `return_payload' pointer.
785 silc_ske_assemble_security_properties(SilcSKE ske,
786 SilcSKESecurityPropertyFlag flags,
788 SilcSKEStartPayload **return_payload);
790 /****f* silcske/SilcSKEAPI/silc_ske_select_security_properties
795 * silc_ske_select_security_properties(SilcSKE ske,
796 * const char *version,
797 * SilcSKEStartPayload *payload,
798 * SilcSKEStartPayload *remote_payload);
802 * Parses the Key Exchange Start Payload indicated by `remote_payload',
803 * and selects the security properties properties from it, and puts the
804 * selection into the `payload'. This always attempts to select the
805 * best security properties from the payload, and it always selects
806 * one of each kind of security property, as this is dictated by the
807 * protocol. The `version' is our version, that we will put to the
808 * `payload', since the `payload' is usually sent to the remote end.
809 * the `check_version' callback will be called in this function so
810 * that application can do version check with the remote end.
814 silc_ske_select_security_properties(SilcSKE ske,
816 SilcSKEStartPayload *payload,
817 SilcSKEStartPayload *remote_payload);
819 /****f* silcske/SilcSKEAPI/silc_ske_process_key_material
823 * SilcSKEStatus silc_ske_process_key_material(SilcSKE ske,
824 * SilcUInt32 req_iv_len,
825 * SilcUInt32 req_enc_key_len,
826 * SilcUInt32 req_hmac_key_len,
827 * SilcSKEKeyMaterial *key);
831 * This function is used by the application to process the key material
832 * negotiated with the SKE session, to actually produce the keys that
833 * is to be used in SILC protocol. The key processing is defined by the
834 * protocol. The `req_iv_len', `req_enc_key_len' and `req_hmac_key_len'
835 * are the request IV length, requested encryption/decrypt key length,
836 * and requested HMAC key length, respectively, and they cannot be
837 * zero (0). They tell the function how long the keys should be, and
838 * it will produce the requested length keys for the application.
839 * The key material is returned in to the `key', which the caller must
843 SilcSKEStatus silc_ske_process_key_material(SilcSKE ske,
844 SilcUInt32 req_iv_len,
845 SilcUInt32 req_enc_key_len,
846 SilcUInt32 req_hmac_key_len,
847 SilcSKEKeyMaterial *key);
849 /****f* silcske/SilcSKEAPI/silc_ske_process_key_material_data
854 * silc_ske_process_key_material_data(unsigned char *data,
855 * SilcUInt32 data_len,
856 * SilcUInt32 req_iv_len,
857 * SilcUInt32 req_enc_key_len,
858 * SilcUInt32 req_hmac_key_len,
860 * SilcSKEKeyMaterial *key);
864 * This function is equivalent to silc_ske_process_key_material, except
865 * that the caller provides the raw key material as argument, the `data'
866 * and `data_len'. This is special utility function provided for the
867 * application, if it needs to generate key material as the protocol
868 * defines for some other purpose than strictly SILC session key usage.
869 * Hence, this function can be used outside SKE protocol to just produce
870 * key material from some raw data. The `hash' is a hash algorithm that
871 * is used as part of key processing, and caller must provide it.
875 silc_ske_process_key_material_data(unsigned char *data,
877 SilcUInt32 req_iv_len,
878 SilcUInt32 req_enc_key_len,
879 SilcUInt32 req_hmac_key_len,
881 SilcSKEKeyMaterial *key);
883 /****f* silcske/SilcSKEAPI/silc_ske_free_key_material
887 * void silc_ske_free_key_material(SilcSKEKeyMaterial *key);
891 * Frees the key material indicated by `key', and all data in it.
894 void silc_ske_free_key_material(SilcSKEKeyMaterial *key);
896 /****f* silcske/SilcSKEAPI/silc_ske_parse_version
900 * bool silc_ske_parse_version(SilcSKE ske,
901 * SilcUInt32 *protocol_version,
902 * char **protocol_version_string,
903 * SilcUInt32 *software_version,
904 * char **software_version_string,
905 * char **vendor_version);
909 * This utility function can be used to parse the remote host's version
910 * string. This returns the protocol version, and software version into
911 * the `protocol_version', `software_version' and `vendor_version' pointers
912 * if they are provided. The string versions of the versions are saved
913 * in *_string pointers if they are provided. Returns TRUE if the version
914 * string was successfully parsed.
917 bool silc_ske_parse_version(SilcSKE ske,
918 SilcUInt32 *protocol_version,
919 char **protocol_version_string,
920 SilcUInt32 *software_version,
921 char **software_version_string,
922 char **vendor_version);
924 #endif /* !SILCSKE_H */