lib/silcske/silcske.h

   1 /*
   2
   3   silcske.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2000 - 2002 Pekka Riikonen
   8
   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.
  12
  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.
  17
  18 */
  19
  20 #ifndef SILCSKE_H
  21 #define SILCSKE_H
  22
  23 /****h* silcske/SilcSKEAPI
  24  *
  25  * DESCRIPTION
  26  *
  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
  33  * stream.
  34  *
  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.
  38  *
  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.
  49  *
  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
  58  * timeout.
  59  *
  60  ***/
  61
  62 #include "silcske_status.h"
  63
  64 /****s* silcske/SilcSKEAPI/SilcSKE
  65  *
  66  * NAME
  67  *
  68  *    typedef struct SilcSKEStruct *SilcSKE;
  69  *
  70  * DESCRIPTION
  71  *
  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.
  75  *
  76  ***/
  77 typedef struct SilcSKEStruct *SilcSKE;
  78
  79 /****s* silcske/SilcSKEAPI/SilcSKESecurityProperties
  80  *
  81  * NAME
  82  *
  83  *    typedef struct SilcSKESecurityPropertiesStruct
  84  *                                 *SilcSKESecurityProperties;
  85  *
  86  * DESCRIPTION
  87  *
  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.
  92  *
  93  ***/
  94 typedef struct SilcSKESecurityPropertiesStruct *SilcSKESecurityProperties;
  95
  96 /* Forward declaration for SKE callbacks structure, which is internal. */
  97 typedef struct SilcSKECallbacksStruct *SilcSKECallbacks;
  98
  99 /****d* silcske/SilcSKEAPI/SilcSKEPKType
 100  *
 101  * NAME
 102  *
 103  *    typedef enum { ... } SilcSKEPKType;
 104  *
 105  * DESCRIPTION
 106  *
 107  *    Public key and certificate types defined by the SKE protocol.
 108  *
 109  * SOURCE
 110  */
 111 typedef enum {
 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
 118 } SilcSKEPKType;
 119 /***/
 120
 121 /****f* silcske/SilcSKEAPI/SilcSKESendPacketCb
 122  *
 123  * SYNOPSIS
 124  *
 125  *    typedef void (*SilcSKESendPacketCb)(SilcSKE ske, SilcBuffer packet,
 126  *                                        SilcPacketType type, void *context);
 127  *
 128  * DESCRIPTION
 129  *
 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.
 133  *
 134  ***/
 135 typedef void (*SilcSKESendPacketCb)(SilcSKE ske, SilcBuffer packet,
 136                                     SilcPacketType type, void *context);
 137
 138 /****f* silcske/SilcSKEAPI/SilcSKECb
 139  *
 140  * SYNOPSIS
 141  *
 142  *    typedef void (*SilcSKECb)(SilcSKE ske, void *context);
 143  *
 144  * DESCRIPTION
 145  *
 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.
 153  *
 154  ***/
 155 typedef void (*SilcSKECb)(SilcSKE ske, void *context);
 156
 157 /****f* silcske/SilcSKEAPI/SilcSKEVerifyCbCompletion
 158  *
 159  * SYNOPSIS
 160  *
 161  *    typedef void (*SilcSKEVerifyCbCompletion)(SilcSKE ske,
 162  *                                              SilcSKEStatus status,
 163  *                                              void *context);
 164  *
 165  * DESCRIPTION
 166  *
 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
 173  *    information.
 174  *
 175  ***/
 176 typedef void (*SilcSKEVerifyCbCompletion)(SilcSKE ske,
 177                                           SilcSKEStatus status,
 178                                           void *context);
 179
 180 /****f* silcske/SilcSKEAPI/SilcSKEVerifyCb
 181  *
 182  * SYNOPSIS
 183  *
 184  *    typedef void (*SilcSKEVerifyCb)(SilcSKE ske,
 185  *                                    unsigned char *pk_data,
 186  *                                    SilcUInt32 pk_len,
 187  *                                    SilcSKEPKType pk_type,
 188  *                                    void *context,
 189  *                                    SilcSKEVerifyCbCompletion completion,
 190  *                                    void *completion_context);
 191  *
 192  * DESCRIPTION
 193  *
 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.
 201  *
 202  ***/
 203 typedef void (*SilcSKEVerifyCb)(SilcSKE ske,
 204                                 unsigned char *pk_data,
 205                                 SilcUInt32 pk_len,
 206                                 SilcSKEPKType pk_type,
 207                                 void *context,
 208                                 SilcSKEVerifyCbCompletion completion,
 209                                 void *completion_context);
 210
 211 /****f* silcske/SilcSKEAPI/SilcSKECheckVersion
 212  *
 213  * SYNOPSIS
 214  *
 215  *    typedef SilcSKEStatus (*SilcSKECheckVersion)(SilcSKE ske,
 216  *                                                 unsigned char *version,
 217  *                                                 SilcUInt32 len, void *context);
 218  *
 219  * DESCRIPTION
 220  *
 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.
 226  *
 227  ***/
 228 typedef SilcSKEStatus (*SilcSKECheckVersion)(SilcSKE ske,
 229                                              unsigned char *version,
 230                                              SilcUInt32 len, void *context);
 231
 232 /****s* silcske/SilcSKEAPI/SilcSKEKeyMaterial
 233  *
 234  * NAME
 235  *
 236  *    typedef struct { ... } SilcSKEKeyMaterial;
 237  *
 238  * DESCRIPTION
 239  *
 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.
 243  *
 244  ***/
 245 typedef struct {
 246   unsigned char *send_iv;
 247   unsigned char *receive_iv;
 248   SilcUInt32 iv_len;
 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;
 256
 257 /* Length of cookie in Start Payload */
 258 #define SILC_SKE_COOKIE_LEN 16
 259
 260 #include "silcske_groups.h"
 261 #include "silcske_payload.h"
 262
 263 /****d* silcske/SilcSKEAPI/SilcSKESecurityPropertyFlag
 264  *
 265  * NAME
 266  *
 267  *    typedef enum { ... } SilcSKESecurityPropertyFlag
 268  *
 269  * DESCRIPTION
 270  *
 271  *    SKE security property flags as defined by the SK protocol.
 272  *
 273  * SOURCE
 274  */
 275 typedef enum {
 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;
 281 /***/
 282
 283 /****s* silcske/SilcSKEAPI/SilcSKESecurityPropertiesStruct
 284  *
 285  * NAME
 286  *
 287  *    struct SilcSKESecurityPropertiesStruct { ... };
 288  *
 289  * DESCRIPTION
 290  *
 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
 294  *    communication.
 295  *
 296  * SOURCE
 297  */
 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 */
 305 };
 306 /***/
 307
 308 /****s* silcske/SilcSKEAPI/SilcSKEStruct
 309  *
 310  * NAME
 311  *
 312  *    struct SilcSKEStruct { ... };
 313  *
 314  * DESCRIPTION
 315  *
 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.
 323  *
 324  * SOURCE
 325  */
 326 struct SilcSKEStruct {
 327   /* The connection object. This is initialized by the caller. */
 328   SilcSocketConnection sock;
 329
 330   /* Security properties negotiated */
 331   SilcSKESecurityProperties prop;
 332
 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
 339   /* Temporary copy of the KE Start Payload used in the
 340      HASH computation. */
 341   SilcBuffer start_payload_copy;
 342
 343   /* Random number x, 1 < x < q. This is the secret exponent
 344      used in Diffie Hellman computations. */
 345   SilcMPInt *x;
 346
 347   /* The secret shared key */
 348   SilcMPInt *KEY;
 349
 350   /* The hash value HASH of the key exchange */
 351   unsigned char *hash;
 352   SilcUInt32 hash_len;
 353
 354   /* Random Number Generator. This is set by the caller and must
 355      be free'd by the caller. */
 356   SilcRng rng;
 357
 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. */
 360   void *user_data;
 361
 362   /* Current status of SKE */
 363   SilcSKEStatus status;
 364
 365   /* Reference counter. This is used when SKE library is performing async
 366      operations, like public key verification. */
 367   int users;
 368
 369   /* SKE callbacks. */
 370   SilcSKECallbacks callbacks;
 371
 372   /* Backwards support version indicator */
 373   SilcUInt32 backward_version;
 374 };
 375 /***/
 376
 377 /* Prototypes */
 378
 379 /****f* silcske/SilcSKEAPI/silc_ske_alloc
 380  *
 381  * SYNOPSIS
 382  *
 383  *    SilcSKE silc_ske_alloc(SilcRng rng, void *context);
 384  *
 385  * DESCRIPTION
 386  *
 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.
 395  *
 396  ***/
 397 SilcSKE silc_ske_alloc(SilcRng rng, void *context);
 398
 399 /****f* silcske/SilcSKEAPI/silc_ske_free
 400  *
 401  * SYNOPSIS
 402  *
 403  *    void silc_ske_free(SilcSKE ske);
 404  *
 405  * DESCRIPTION
 406  *
 407  *    Frees the SKE session context and all allocated resources.
 408  *
 409  ***/
 410 void silc_ske_free(SilcSKE ske);
 411
 412 /****f* silcske/SilcSKEAPI/silc_ske_set_callbacks
 413  *
 414  * SYNOPSIS
 415  *
 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,
 422  *                                void *context);
 423  *
 424  * DESCRIPTION
 425  *
 426  *    Sets the callback functions for the SKE session.
 427  *
 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.
 431  *
 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.
 436  *
 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.
 448  *
 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.
 455  *
 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
 459  *    is possible.
 460  *
 461  *    The `context' is passed as argument to all of the above callback
 462  *    functions.
 463  *
 464  ***/
 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,
 471                             void *context);
 472
 473 /****f* silcske/SilcSKEAPI/silc_ske_initiator_start
 474  *
 475  * SYNOPSIS
 476  *
 477  *    SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng,
 478  *                                           SilcSocketConnection sock,
 479  *                                           SilcSKEStartPayload
 480  *                                              *start_payload);
 481  *
 482  * DESCRIPTION
 483  *
 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.
 493  *
 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.
 497  *
 498  *    After calling this function the application must wait for reply
 499  *    from the responder.
 500  *
 501  ***/
 502 SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng,
 503                                        SilcSocketConnection sock,
 504                                        SilcSKEStartPayload *start_payload);
 505
 506 /****f* silcske/SilcSKEAPI/silc_ske_initiator_phase_1
 507  *
 508  * SYNOPSIS
 509  *
 510  *    SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske,
 511  *                                             SilcBuffer start_payload);
 512  *
 513  * DESCRIPTION
 514  *
 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.
 520  *
 521  *    After calling this function the application must call immediately,
 522  *    or with short timeout, the silc_ske_initiator_phase_2 function.
 523  *
 524  ***/
 525 SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske,
 526                                          SilcBuffer start_payload);
 527
 528 /****f* silcske/SilcSKEAPI/silc_ske_initiator_phase_2
 529  *
 530  * SYNOPSIS
 531  *
 532  *    SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske,
 533  *                                             SilcPublicKey public_key,
 534  *                                             SilcPrivateKey private_key,
 535  *                                             SilcSKEPKType pk_type)
 536  *
 537  * DESCRIPTION
 538  *
 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
 546  *    digital signature.
 547  *
 548  *    After this function the application must wait for reply from the
 549  *    responder.
 550  *
 551  ***/
 552 SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske,
 553                                          SilcPublicKey public_key,
 554                                          SilcPrivateKey private_key,
 555                                          SilcSKEPKType pk_type);
 556
 557 /****f* silcske/SilcSKEAPI/silc_ske_initiator_finish
 558  *
 559  * SYNOPSIS
 560  *
 561  *    SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
 562  *                                            SilcBuffer ke_payload);
 563  *
 564  * DESCRIPTION
 565  *
 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
 570  *    function.
 571  *
 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.
 583  *
 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.
 587  *
 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
 591  *    function.
 592  *
 593  ***/
 594 SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
 595                                         SilcBuffer ke_payload);
 596
 597 /****f* silcske/SilcSKEAPI/silc_ske_responder_start
 598  *
 599  * SYNOPSIS
 600  *
 601  *    SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
 602  *                                           SilcSocketConnection sock,
 603  *                                           const char *version,
 604  *                                           SilcBuffer start_payload,
 605  *                                           SilcSKESecurityPropertyFlag
 606  *                                                               flags);
 607  *
 608  * DESCRIPTION
 609  *
 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
 620  *    enforced flags.
 621  *
 622  *    After this function the responder calls immediately, or with short
 623  *    timeout the silc_ske_responder_phase_1 function.
 624  *
 625  ***/
 626 SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
 627                                        SilcSocketConnection sock,
 628                                        const char *version,
 629                                        SilcBuffer start_payload,
 630                                        SilcSKESecurityPropertyFlag flags);
 631
 632 /****f* silcske/SilcSKEAPI/silc_ske_responder_phase_1
 633  *
 634  * SYNOPSIS
 635  *
 636  *    SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske);
 637  *
 638  * DESCRIPTION
 639  *
 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.
 644  *
 645  *    After this function the responder must wait for reply from the
 646  *    initiator.
 647  *
 648  ***/
 649 SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske);
 650
 651 /****f* silcske/SilcSKEAPI/silc_ske_responder_phase_2
 652  *
 653  * SYNOPSIS
 654  *
 655  *    SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
 656  *                                             SilcBuffer ke_payload);
 657  *
 658  * DESCRIPTION
 659  *
 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
 664  *    function.
 665  *
 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
 677  *    function.
 678  *
 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.
 682  *
 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.
 686  *
 687  ***/
 688 SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
 689                                          SilcBuffer ke_payload);
 690
 691 /****f* silcske/SilcSKEAPI/silc_ske_responder_finish
 692  *
 693  * SYNOPSIS
 694  *
 695  *    SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
 696  *                                            SilcPublicKey public_key,
 697  *                                            SilcPrivateKey private_key,
 698  *                                            SilcSKEPKType pk_type);
 699  *
 700  * DESCRIPTION
 701  *
 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.
 708  *
 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.
 711  *
 712  ***/
 713 SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
 714                                         SilcPublicKey public_key,
 715                                         SilcPrivateKey private_key,
 716                                         SilcSKEPKType pk_type);
 717
 718 /****f* silcske/SilcSKEAPI/silc_ske_end
 719  *
 720  * SYNOPSIS
 721  *
 722  *    SilcSKEStatus silc_ske_end(SilcSKE ske);
 723  *
 724  * DESCRIPTION
 725  *
 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.
 730  *
 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
 735  *    indication.
 736  *
 737  * NOTES
 738  *
 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.
 742  *
 743  ***/
 744 SilcSKEStatus silc_ske_end(SilcSKE ske);
 745
 746 /****f* silcske/SilcSKEAPI/silc_ske_abort
 747  *
 748  * SYNOPSIS
 749  *
 750  *    SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status);
 751  *
 752  * DESCRIPTION
 753  *
 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.
 757  *
 758  ***/
 759 SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status);
 760
 761 /****f* silcske/SilcSKEAPI/silc_ske_assemble_security_properties
 762  *
 763  * SYNOPSIS
 764  *
 765  *    SilcSKEStatus
 766  *    silc_ske_assemble_security_properties(SilcSKE ske,
 767  *                                          SilcSKESecurityPropertyFlag flags,
 768  *                                          const char *version,
 769  *                                          SilcSKEStartPayload
 770  *                                            **return_payload);
 771  *
 772  * DESCRIPTION
 773  *
 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.
 781  *
 782  ***/
 783 SilcSKEStatus
 784 silc_ske_assemble_security_properties(SilcSKE ske,
 785                                       SilcSKESecurityPropertyFlag flags,
 786                                       const char *version,
 787                                       SilcSKEStartPayload **return_payload);
 788
 789 /****f* silcske/SilcSKEAPI/silc_ske_select_security_properties
 790  *
 791  * SYNOPSIS
 792  *
 793  *    SilcSKEStatus
 794  *    silc_ske_select_security_properties(SilcSKE ske,
 795  *                                        const char *version,
 796  *                                        SilcSKEStartPayload *payload,
 797  *                                        SilcSKEStartPayload *remote_payload);
 798  *
 799  * DESCRIPTION
 800  *
 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.
 810  *
 811  ***/
 812 SilcSKEStatus
 813 silc_ske_select_security_properties(SilcSKE ske,
 814                                     const char *version,
 815                                     SilcSKEStartPayload *payload,
 816                                     SilcSKEStartPayload *remote_payload);
 817
 818 /****f* silcske/SilcSKEAPI/silc_ske_process_key_material
 819  *
 820  * SYNOPSIS
 821  *
 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);
 827  *
 828  * DESCRIPTION
 829  *
 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
 839  *    free.
 840  *
 841  ***/
 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);
 847
 848 /****f* silcske/SilcSKEAPI/silc_ske_process_key_material_data
 849  *
 850  * SYNOPSIS
 851  *
 852  *    SilcSKEStatus
 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,
 858  *                                       SilcHash hash,
 859  *                                       SilcSKEKeyMaterial *key);
 860  *
 861  * DESCRIPTION
 862  *
 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.
 871  *
 872  ***/
 873 SilcSKEStatus
 874 silc_ske_process_key_material_data(unsigned char *data,
 875                                    SilcUInt32 data_len,
 876                                    SilcUInt32 req_iv_len,
 877                                    SilcUInt32 req_enc_key_len,
 878                                    SilcUInt32 req_hmac_key_len,
 879                                    SilcHash hash,
 880                                    SilcSKEKeyMaterial *key);
 881
 882 /****f* silcske/SilcSKEAPI/silc_ske_free_key_material
 883  *
 884  * SYNOPSIS
 885  *
 886  *    void silc_ske_free_key_material(SilcSKEKeyMaterial *key);
 887  *
 888  * DESCRIPTION
 889  *
 890  *    Frees the key material indicated by `key', and all data in it.
 891  *
 892  ***/
 893 void silc_ske_free_key_material(SilcSKEKeyMaterial *key);
 894
 895 #endif  /* !SILCSKE_H */