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/SILC SKE Interface
  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_IV_INCLUDED  = 0x01,  /* IV included in ciphertexts */
 278   SILC_SKE_SP_FLAG_PFS          = 0x02,  /* Perfect Forward Secrecy */
 279   SILC_SKE_SP_FLAG_MUTUAL       = 0x04,  /* Mutual authentication */
 280 } SilcSKESecurityPropertyFlag;
 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 #if 0
 329   SilcSocketConnection sock;
 330 #endif
 331
 332   /* Security properties negotiated */
 333   SilcSKESecurityProperties prop;
 334
 335   /* Key Exchange payloads filled during key negotiation with
 336      remote data. Responder may save local data here as well. */
 337   SilcSKEStartPayload *start_payload;
 338   SilcSKEKEPayload *ke1_payload;
 339   SilcSKEKEPayload *ke2_payload;
 340   unsigned char *remote_version;
 341
 342   /* Temporary copy of the KE Start Payload used in the
 343      HASH computation. */
 344   SilcBuffer start_payload_copy;
 345
 346   /* Random number x, 1 < x < q. This is the secret exponent
 347      used in Diffie Hellman computations. */
 348   SilcMPInt *x;
 349
 350   /* The secret shared key */
 351   SilcMPInt *KEY;
 352
 353   /* The hash value HASH of the key exchange */
 354   unsigned char *hash;
 355   SilcUInt32 hash_len;
 356
 357   /* Random Number Generator. This is set by the caller and must
 358      be free'd by the caller. */
 359   SilcRng rng;
 360
 361   /* Pointer to the what ever user data. This is set by the caller
 362      and is not touched by the SKE. The caller must also free this one. */
 363   void *user_data;
 364
 365   /* Current status of SKE */
 366   SilcSKEStatus status;
 367
 368   /* Reference counter. This is used when SKE library is performing async
 369      operations, like public key verification. */
 370   int users;
 371
 372   /* SKE callbacks. */
 373   SilcSKECallbacks callbacks;
 374
 375   /* Backwards support version indicator */
 376   SilcUInt32 backward_version;
 377 };
 378 /***/
 379
 380 /* Prototypes */
 381
 382 /****f* silcske/SilcSKEAPI/silc_ske_alloc
 383  *
 384  * SYNOPSIS
 385  *
 386  *    SilcSKE silc_ske_alloc(SilcRng rng, void *context);
 387  *
 388  * DESCRIPTION
 389  *
 390  *    Allocates the SKE session context and returns it.  The `rng' is
 391  *    the random number generator the SKE is going to use when it needs
 392  *    random number generation during the SKE session.  The `context' is
 393  *    user context that the libary will not touch.  The application can
 394  *    access that context with the ske->user_context if needed.  The
 395  *    application is responsible of freeing the `context'.  After the
 396  *    SKE session context is allocated application must call the
 397  *    silc_ske_set_callbacks.
 398  *
 399  ***/
 400 SilcSKE silc_ske_alloc(SilcRng rng, void *context);
 401
 402 /****f* silcske/SilcSKEAPI/silc_ske_free
 403  *
 404  * SYNOPSIS
 405  *
 406  *    void silc_ske_free(SilcSKE ske);
 407  *
 408  * DESCRIPTION
 409  *
 410  *    Frees the SKE session context and all allocated resources.
 411  *
 412  ***/
 413 void silc_ske_free(SilcSKE ske);
 414
 415 /****f* silcske/SilcSKEAPI/silc_ske_set_callbacks
 416  *
 417  * SYNOPSIS
 418  *
 419  *    void silc_ske_set_callbacks(SilcSKE ske,
 420  *                                SilcSKESendPacketCb send_packet,
 421  *                                SilcSKECb payload_receive,
 422  *                                SilcSKEVerifyCb verify_key,
 423  *                                SilcSKECb proto_continue,
 424  *                                SilcSKECheckVersion check_version,
 425  *                                void *context);
 426  *
 427  * DESCRIPTION
 428  *
 429  *    Sets the callback functions for the SKE session.
 430  *
 431  *    The `send_packet' callback is a function that sends the packet to
 432  *    network. The SKE library will call it at any time packet needs to
 433  *    be sent to the remote host.
 434  *
 435  *    The `payload_receive' callback is called when the remote host's Key
 436  *    Exchange Start Payload has been processed.  The payload is saved
 437  *    to ske->start_payload if the application would need it.  The application
 438  *    must also provide the payload to the next state of the SKE.
 439  *
 440  *    The `verify_key' callback is called to verify the received public key
 441  *    or certificate.  The verification process is most likely asynchronous.
 442  *    That is why the application must call the completion callback when the
 443  *    verification process has been completed. The library then calls the user
 444  *    callback (`proto_continue'), if it is provided to indicate that the SKE
 445  *    protocol may continue. If this SKE session context is used to perform
 446  *    rekey, this callback usually is not provided as argument since sending
 447  *    public key in rekey is not mandatory. Setting this callback implies
 448  *    that remote end MUST send its public key, and this could cause
 449  *    problems when performing rekey. When doing normal SKE session this
 450  *    callback should be set.
 451  *
 452  *    The `proto_continue' callback is called to indicate that it is
 453  *    safe to continue the execution of the SKE protocol after executing
 454  *    an asynchronous operation, such as calling the `verify_key' callback
 455  *    function, which is asynchronous. The application should check the
 456  *    ske->status in this function to check whether it is Ok to continue
 457  *    the execution of the protocol.
 458  *
 459  *    The `check_version' callback is called to verify the remote host's
 460  *    version. The application may check its own version against the remote
 461  *    host's version and determine whether supporting the remote host
 462  *    is possible.
 463  *
 464  *    The `context' is passed as argument to all of the above callback
 465  *    functions.
 466  *
 467  ***/
 468 void silc_ske_set_callbacks(SilcSKE ske,
 469                             SilcSKESendPacketCb send_packet,
 470                             SilcSKECb payload_receive,
 471                             SilcSKEVerifyCb verify_key,
 472                             SilcSKECb proto_continue,
 473                             SilcSKECheckVersion check_version,
 474                             void *context);
 475
 476 /****f* silcske/SilcSKEAPI/silc_ske_initiator_start
 477  *
 478  * SYNOPSIS
 479  *
 480  *    SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng,
 481  *                                           SilcSocketConnection sock,
 482  *                                           SilcSKEStartPayload
 483  *                                              *start_payload);
 484  *
 485  * DESCRIPTION
 486  *
 487  *    Starts the SILC Key Exchange protocol for initiator. The connection
 488  *    to the responder end must be established before calling this function
 489  *    and the connecting socket must be sent as argument. This function
 490  *    creates the Key Exchange Start Payload which includes all our
 491  *    configured security properties. This payload is then sent to the
 492  *    responder end for further processing. This payload must be sent as
 493  *    argument to the function, however, it must not be encoded
 494  *    already, it is done by this function. The caller must not free
 495  *    the `start_payload' since the SKE library will save it.
 496  *
 497  *    Before calling this function application calls the
 498  *    silc_ske_assemble_security_properties which returns the `start_payload'
 499  *    which application must provide for this function.
 500  *
 501  *    After calling this function the application must wait for reply
 502  *    from the responder.
 503  *
 504  ***/
 505 SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng,
 506 #if 0
 507                                        SilcSocketConnection sock,
 508 #endif
 509                                        SilcSKEStartPayload *start_payload);
 510
 511 /****f* silcske/SilcSKEAPI/silc_ske_initiator_phase_1
 512  *
 513  * SYNOPSIS
 514  *
 515  *    SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske,
 516  *                                             SilcBuffer start_payload);
 517  *
 518  * DESCRIPTION
 519  *
 520  *    Function called after ske_initiator_start fuction. This receives
 521  *    the responder's Key Exchange Start payload which includes the
 522  *    security properties selected by the responder from our payload
 523  *    sent in the silc_ske_initiator_start function. The `start_payload'
 524  *    is the received payload and the application must send it as argument.
 525  *
 526  *    After calling this function the application must call immediately,
 527  *    or with short timeout, the silc_ske_initiator_phase_2 function.
 528  *
 529  ***/
 530 SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske,
 531                                          SilcBuffer start_payload);
 532
 533 /****f* silcske/SilcSKEAPI/silc_ske_initiator_phase_2
 534  *
 535  * SYNOPSIS
 536  *
 537  *    SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske,
 538  *                                             SilcPublicKey public_key,
 539  *                                             SilcPrivateKey private_key,
 540  *                                             SilcSKEPKType pk_type)
 541  *
 542  * DESCRIPTION
 543  *
 544  *    This function continues the SKE session after the initiator has
 545  *    called the silc_ske_initiator_phase_1.  After that function returns
 546  *    the application should call immediately, or with short timeout, this
 547  *    function which will continue with the session, and sends next phase
 548  *    packet to the responder.  The caller must provide the caller's
 549  *    public key and private key as argument, since the public key is
 550  *    sent to the responder, and the private key is be used to generate
 551  *    digital signature.
 552  *
 553  *    After this function the application must wait for reply from the
 554  *    responder.
 555  *
 556  ***/
 557 SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske,
 558                                          SilcPublicKey public_key,
 559                                          SilcPrivateKey private_key,
 560                                          SilcSKEPKType pk_type);
 561
 562 /****f* silcske/SilcSKEAPI/silc_ske_initiator_finish
 563  *
 564  * SYNOPSIS
 565  *
 566  *    SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
 567  *                                            SilcBuffer ke_payload);
 568  *
 569  * DESCRIPTION
 570  *
 571  *    Receives the reply from the responder and processes it.  The
 572  *    `ke_payload' is the reply and application must provide it as argument.
 573  *    This function will verify the responder's public key, by calling
 574  *    the `verify_key' callback that was set with silc_ske_set_callbacks
 575  *    function.
 576  *
 577  *    If this function returns error, no callbacks will be called. If
 578  *    this function needs to verify remote end's public key, this will
 579  *    return SILC_SKE_STATUS_PENDING, which indicates application that
 580  *    SKE is performing asynchronous operation and is in pending status.
 581  *    When in this status application must not continue with calling
 582  *    any other SKE routine. The asynchronous operation is the `verify_key'
 583  *    callback, which application completes by calling its completion
 584  *    callback. After completion the SKE libary will call the
 585  *    `proto_continue' callback, to indicate application that pending
 586  *    status is over and it is safe to continue the execution of SKE,
 587  *    which application does by calling the silc_ske_end function.
 588  *
 589  *    If this function returns SILC_SKE_STATUS_OK, it will not call the
 590  *    `verify_key' callback, however, it will or has already called the
 591  *    `proto_continue' callback.
 592  *
 593  *    Application must not continue execution of the SKE before library
 594  *    has called the `proto_continue' callback.  After it is called
 595  *    the application finishes SKE session by calling silc_ske_end
 596  *    function.
 597  *
 598  ***/
 599 SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
 600                                         SilcBuffer ke_payload);
 601
 602 /****f* silcske/SilcSKEAPI/silc_ske_responder_start
 603  *
 604  * SYNOPSIS
 605  *
 606  *    SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
 607  *                                           SilcSocketConnection sock,
 608  *                                           const char *version,
 609  *                                           SilcBuffer start_payload,
 610  *                                           SilcSKESecurityPropertyFlag
 611  *                                                               flags);
 612  *
 613  * DESCRIPTION
 614  *
 615  *    Starts Key Exchange protocol for responder. The application has
 616  *    received initiator's first packet from network and it must provide
 617  *    it as `start_payload' argument to this function. The function
 618  *    processes the packet and makes security property selection from
 619  *    the initiator's proposal. The `version' is the responder's version
 620  *    that will be sent in reply to the initiator. The `flags' indicates
 621  *    SilcSKESecurityPropertyFlag flags that responder enforces for the
 622  *    initiator. Responder may, for example, enforce that the PFS
 623  *    will be performed in rekey. This example can be done by providing
 624  *    SILC_SKE_SP_FLAG_PFS as `flags'. The `flags' is a bit mask of
 625  *    enforced flags.
 626  *
 627  *    After this function the responder calls immediately, or with short
 628  *    timeout the silc_ske_responder_phase_1 function.
 629  *
 630  ***/
 631 SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
 632 #if 0
 633                                        SilcSocketConnection sock,
 634 #endif
 635                                        const char *version,
 636                                        SilcBuffer start_payload,
 637                                        SilcSKESecurityPropertyFlag flags);
 638
 639 /****f* silcske/SilcSKEAPI/silc_ske_responder_phase_1
 640  *
 641  * SYNOPSIS
 642  *
 643  *    SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske);
 644  *
 645  * DESCRIPTION
 646  *
 647  *    This function is called after the silc_ske_responder_start, and
 648  *    is used to send our reply to the initiator.  This function is
 649  *    called either immediately, or with short timeout, after the
 650  *    silc_ske_responder_start function returned.
 651  *
 652  *    After this function the responder must wait for reply from the
 653  *    initiator.
 654  *
 655  ***/
 656 SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske);
 657
 658 /****f* silcske/SilcSKEAPI/silc_ske_responder_phase_2
 659  *
 660  * SYNOPSIS
 661  *
 662  *    SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
 663  *                                             SilcBuffer ke_payload);
 664  *
 665  * DESCRIPTION
 666  *
 667  *    Receives the reply from the initiator and procedses it.  The
 668  *    `ke_payload' is the reply and application must provide it as argument.
 669  *    This function will verify the remote host's public key, by calling
 670  *    the `verify_key' callback that was set with silc_ske_set_callbacks
 671  *    function.
 672  *
 673  *    If this function returns error, no callbacks will be called. If
 674  *    this function needs to verify remote end's public key, this will
 675  *    return SILC_SKE_STATUS_PENDING, which indicates application that
 676  *    SKE is performing asynchronous operation and is in pending status.
 677  *    When in this status application must not continue with calling
 678  *    any other SKE routine. The asynchronous operation is the `verify_key'
 679  *    callback, which application completes by calling its completion
 680  *    callback. After completion the SKE libary will call the
 681  *    `proto_continue' callback, to indicate application that pending
 682  *    status is over and it is safe to continue the execution of SKE,
 683  *    which application does by calling the silc_ske_responder_finish
 684  *    function.
 685  *
 686  *    If this function returns SILC_SKE_STATUS_OK, it will not call the
 687  *    `verify_key' callback, however, it will or has already called the
 688  *    `proto_continue' callback.
 689  *
 690  *    Application must not continue execution of the SKE before library
 691  *    has called the `proto_continue' callback.  After it is called
 692  *    the application calls the silc_ske_responder_finish function.
 693  *
 694  ***/
 695 SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
 696                                          SilcBuffer ke_payload);
 697
 698 /****f* silcske/SilcSKEAPI/silc_ske_responder_finish
 699  *
 700  * SYNOPSIS
 701  *
 702  *    SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
 703  *                                            SilcPublicKey public_key,
 704  *                                            SilcPrivateKey private_key,
 705  *                                            SilcSKEPKType pk_type);
 706  *
 707  * DESCRIPTION
 708  *
 709  *    This function finishes the responder's SKE session, and this function
 710  *    is called either immediately, or with short timeout, after the
 711  *    silc_ske_responder_phase_2 returned. This will send our reply to
 712  *    the initiator.  The caller must provide the caller's public key and
 713  *    private key as argument, since the public key is sent to the responder,
 714  *    and the private key is be used to generate digital signature.
 715  *
 716  *    After this function the application must wait for the end indication
 717  *    from the intiator, and when it is received the silc_ske_end is called.
 718  *
 719  ***/
 720 SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
 721                                         SilcPublicKey public_key,
 722                                         SilcPrivateKey private_key,
 723                                         SilcSKEPKType pk_type);
 724
 725 /****f* silcske/SilcSKEAPI/silc_ske_end
 726  *
 727  * SYNOPSIS
 728  *
 729  *    SilcSKEStatus silc_ske_end(SilcSKE ske);
 730  *
 731  * DESCRIPTION
 732  *
 733  *    The Key Exchange protocol is ended by calling this function. This
 734  *    must not be called until the keys are processed by calling the
 735  *    silc_ske_process_key_material function. The protocol prohibits
 736  *    calling this function before key material is processed properly.
 737  *
 738  *    This function is for both initiator and responder. After calling
 739  *    this function initiator must wait for end indication from the
 740  *    responder. After that the silc_ske_free may be called. The responder
 741  *    calls this function after it has received the intiator's end
 742  *    indication.
 743  *
 744  * NOTES
 745  *
 746  *    Initiator must not start using the negotiated key material before
 747  *    calling this function or before remote end has sent its end
 748  *    indication. Only after that the key material may be taken in use.
 749  *
 750  ***/
 751 SilcSKEStatus silc_ske_end(SilcSKE ske);
 752
 753 /****f* silcske/SilcSKEAPI/silc_ske_abort
 754  *
 755  * SYNOPSIS
 756  *
 757  *    SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status);
 758  *
 759  * DESCRIPTION
 760  *
 761  *    Aborts the Key Exchange protocol. This is called if error occurs
 762  *    while performing the protocol. The status argument is the error
 763  *    status and it is sent to the remote end.
 764  *
 765  ***/
 766 SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status);
 767
 768 /****f* silcske/SilcSKEAPI/silc_ske_assemble_security_properties
 769  *
 770  * SYNOPSIS
 771  *
 772  *    SilcSKEStatus
 773  *    silc_ske_assemble_security_properties(SilcSKE ske,
 774  *                                          SilcSKESecurityPropertyFlag flags,
 775  *                                          const char *version,
 776  *                                          SilcSKEStartPayload
 777  *                                            **return_payload);
 778  *
 779  * DESCRIPTION
 780  *
 781  *    Assembles security properties to Key Exchange Start Payload to be
 782  *    sent to the remote end. This checks system wide (SILC system, that is)
 783  *    settings and chooses from those. However, if other properties
 784  *    should be used this function is easy to replace by another function,
 785  *    as, this function is called by the caller of the library and not
 786  *    by the SKE library itself. The assembled payload is returned into
 787  *    the `return_payload' pointer.
 788  *
 789  ***/
 790 SilcSKEStatus
 791 silc_ske_assemble_security_properties(SilcSKE ske,
 792                                       SilcSKESecurityPropertyFlag flags,
 793                                       const char *version,
 794                                       SilcSKEStartPayload **return_payload);
 795
 796 /****f* silcske/SilcSKEAPI/silc_ske_select_security_properties
 797  *
 798  * SYNOPSIS
 799  *
 800  *    SilcSKEStatus
 801  *    silc_ske_select_security_properties(SilcSKE ske,
 802  *                                        const char *version,
 803  *                                        SilcSKEStartPayload *payload,
 804  *                                        SilcSKEStartPayload *remote_payload);
 805  *
 806  * DESCRIPTION
 807  *
 808  *    Parses the Key Exchange Start Payload indicated by `remote_payload',
 809  *    and selects the security properties properties from it, and puts the
 810  *    selection into the `payload'. This always attempts to select the
 811  *    best security properties from the payload, and it always selects
 812  *    one of each kind of security property, as this is dictated by the
 813  *    protocol. The `version' is our version, that we will put to the
 814  *    `payload', since the `payload' is usually sent to the remote end.
 815  *    the `check_version' callback will be called in this function so
 816  *    that application can do version check with the remote end.
 817  *
 818  ***/
 819 SilcSKEStatus
 820 silc_ske_select_security_properties(SilcSKE ske,
 821                                     const char *version,
 822                                     SilcSKEStartPayload *payload,
 823                                     SilcSKEStartPayload *remote_payload);
 824
 825 /****f* silcske/SilcSKEAPI/silc_ske_process_key_material
 826  *
 827  * SYNOPSIS
 828  *
 829  *    SilcSKEStatus silc_ske_process_key_material(SilcSKE ske,
 830  *                                                SilcUInt32 req_iv_len,
 831  *                                                SilcUInt32 req_enc_key_len,
 832  *                                                SilcUInt32 req_hmac_key_len,
 833  *                                                SilcSKEKeyMaterial *key);
 834  *
 835  * DESCRIPTION
 836  *
 837  *    This function is used by the application to process the key material
 838  *    negotiated with the SKE session, to actually produce the keys that
 839  *    is to be used in SILC protocol. The key processing is defined by the
 840  *    protocol. The `req_iv_len', `req_enc_key_len' and `req_hmac_key_len'
 841  *    are the request IV length, requested encryption/decrypt key length,
 842  *    and requested HMAC key length, respectively, and  they cannot be
 843  *    zero (0). They tell the function how long the keys should be, and
 844  *    it will produce the requested length keys for the application.
 845  *    The key material is returned in to the `key', which the caller must
 846  *    free.
 847  *
 848  ***/
 849 SilcSKEStatus silc_ske_process_key_material(SilcSKE ske,
 850                                             SilcUInt32 req_iv_len,
 851                                             SilcUInt32 req_enc_key_len,
 852                                             SilcUInt32 req_hmac_key_len,
 853                                             SilcSKEKeyMaterial *key);
 854
 855 /****f* silcske/SilcSKEAPI/silc_ske_process_key_material_data
 856  *
 857  * SYNOPSIS
 858  *
 859  *    SilcSKEStatus
 860  *    silc_ske_process_key_material_data(unsigned char *data,
 861  *                                       SilcUInt32 data_len,
 862  *                                       SilcUInt32 req_iv_len,
 863  *                                       SilcUInt32 req_enc_key_len,
 864  *                                       SilcUInt32 req_hmac_key_len,
 865  *                                       SilcHash hash,
 866  *                                       SilcSKEKeyMaterial *key);
 867  *
 868  * DESCRIPTION
 869  *
 870  *    This function is equivalent to silc_ske_process_key_material, except
 871  *    that the caller provides the raw key material as argument, the `data'
 872  *    and `data_len'. This is special utility function provided for the
 873  *    application, if it needs to generate key material as the protocol
 874  *    defines for some other purpose than strictly SILC session key usage.
 875  *    Hence, this function can be used outside SKE protocol to just produce
 876  *    key material from some raw data. The `hash' is a hash algorithm that
 877  *    is used as part of key processing, and caller must provide it.
 878  *
 879  ***/
 880 SilcSKEStatus
 881 silc_ske_process_key_material_data(unsigned char *data,
 882                                    SilcUInt32 data_len,
 883                                    SilcUInt32 req_iv_len,
 884                                    SilcUInt32 req_enc_key_len,
 885                                    SilcUInt32 req_hmac_key_len,
 886                                    SilcHash hash,
 887                                    SilcSKEKeyMaterial *key);
 888
 889 /****f* silcske/SilcSKEAPI/silc_ske_free_key_material
 890  *
 891  * SYNOPSIS
 892  *
 893  *    void silc_ske_free_key_material(SilcSKEKeyMaterial *key);
 894  *
 895  * DESCRIPTION
 896  *
 897  *    Frees the key material indicated by `key', and all data in it.
 898  *
 899  ***/
 900 void silc_ske_free_key_material(SilcSKEKeyMaterial *key);
 901
 902 /****f* silcske/SilcSKEAPI/silc_ske_parse_version
 903  *
 904  * SYNOPSIS
 905  *
 906  *    bool silc_ske_parse_version(SilcSKE ske,
 907  *                                SilcUInt32 *protocol_version,
 908  *                                char **protocol_version_string,
 909  *                                SilcUInt32 *software_version,
 910  *                                char **software_version_string,
 911  *                                char **vendor_version);
 912  *
 913  * DESCRIPTION
 914  *
 915  *    This utility function can be used to parse the remote host's version
 916  *    string.  This returns the protocol version, and software version into
 917  *    the `protocol_version', `software_version' and `vendor_version' pointers
 918  *    if they are provided.  The string versions of the versions are saved
 919  *    in *_string pointers if they are provided.  Returns TRUE if the version
 920  *    string was successfully parsed.
 921  *
 922  ***/
 923 bool silc_ske_parse_version(SilcSKE ske,
 924                             SilcUInt32 *protocol_version,
 925                             char **protocol_version_string,
 926                             SilcUInt32 *software_version,
 927                             char **software_version_string,
 928                             char **vendor_version);
 929
 930 #endif  /* !SILCSKE_H */