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   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   unsigned char *remote_version;
 339
 340   /* Temporary copy of the KE Start Payload used in the
 341      HASH computation. */
 342   SilcBuffer start_payload_copy;
 343
 344   /* Random number x, 1 < x < q. This is the secret exponent
 345      used in Diffie Hellman computations. */
 346   SilcMPInt *x;
 347
 348   /* The secret shared key */
 349   SilcMPInt *KEY;
 350
 351   /* The hash value HASH of the key exchange */
 352   unsigned char *hash;
 353   SilcUInt32 hash_len;
 354
 355   /* Random Number Generator. This is set by the caller and must
 356      be free'd by the caller. */
 357   SilcRng rng;
 358
 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. */
 361   void *user_data;
 362
 363   /* Current status of SKE */
 364   SilcSKEStatus status;
 365
 366   /* Reference counter. This is used when SKE library is performing async
 367      operations, like public key verification. */
 368   int users;
 369
 370   /* SKE callbacks. */
 371   SilcSKECallbacks callbacks;
 372
 373   /* Backwards support version indicator */
 374   SilcUInt32 backward_version;
 375 };
 376 /***/
 377
 378 /* Prototypes */
 379
 380 /****f* silcske/SilcSKEAPI/silc_ske_alloc
 381  *
 382  * SYNOPSIS
 383  *
 384  *    SilcSKE silc_ske_alloc(SilcRng rng, void *context);
 385  *
 386  * DESCRIPTION
 387  *
 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.
 396  *
 397  ***/
 398 SilcSKE silc_ske_alloc(SilcRng rng, void *context);
 399
 400 /****f* silcske/SilcSKEAPI/silc_ske_free
 401  *
 402  * SYNOPSIS
 403  *
 404  *    void silc_ske_free(SilcSKE ske);
 405  *
 406  * DESCRIPTION
 407  *
 408  *    Frees the SKE session context and all allocated resources.
 409  *
 410  ***/
 411 void silc_ske_free(SilcSKE ske);
 412
 413 /****f* silcske/SilcSKEAPI/silc_ske_set_callbacks
 414  *
 415  * SYNOPSIS
 416  *
 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,
 423  *                                void *context);
 424  *
 425  * DESCRIPTION
 426  *
 427  *    Sets the callback functions for the SKE session.
 428  *
 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.
 432  *
 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.
 437  *
 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.
 449  *
 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.
 456  *
 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
 460  *    is possible.
 461  *
 462  *    The `context' is passed as argument to all of the above callback
 463  *    functions.
 464  *
 465  ***/
 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,
 472                             void *context);
 473
 474 /****f* silcske/SilcSKEAPI/silc_ske_initiator_start
 475  *
 476  * SYNOPSIS
 477  *
 478  *    SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng,
 479  *                                           SilcSocketConnection sock,
 480  *                                           SilcSKEStartPayload
 481  *                                              *start_payload);
 482  *
 483  * DESCRIPTION
 484  *
 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.
 494  *
 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.
 498  *
 499  *    After calling this function the application must wait for reply
 500  *    from the responder.
 501  *
 502  ***/
 503 SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng,
 504                                        SilcSocketConnection sock,
 505                                        SilcSKEStartPayload *start_payload);
 506
 507 /****f* silcske/SilcSKEAPI/silc_ske_initiator_phase_1
 508  *
 509  * SYNOPSIS
 510  *
 511  *    SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske,
 512  *                                             SilcBuffer start_payload);
 513  *
 514  * DESCRIPTION
 515  *
 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.
 521  *
 522  *    After calling this function the application must call immediately,
 523  *    or with short timeout, the silc_ske_initiator_phase_2 function.
 524  *
 525  ***/
 526 SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske,
 527                                          SilcBuffer start_payload);
 528
 529 /****f* silcske/SilcSKEAPI/silc_ske_initiator_phase_2
 530  *
 531  * SYNOPSIS
 532  *
 533  *    SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske,
 534  *                                             SilcPublicKey public_key,
 535  *                                             SilcPrivateKey private_key,
 536  *                                             SilcSKEPKType pk_type)
 537  *
 538  * DESCRIPTION
 539  *
 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
 547  *    digital signature.
 548  *
 549  *    After this function the application must wait for reply from the
 550  *    responder.
 551  *
 552  ***/
 553 SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske,
 554                                          SilcPublicKey public_key,
 555                                          SilcPrivateKey private_key,
 556                                          SilcSKEPKType pk_type);
 557
 558 /****f* silcske/SilcSKEAPI/silc_ske_initiator_finish
 559  *
 560  * SYNOPSIS
 561  *
 562  *    SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
 563  *                                            SilcBuffer ke_payload);
 564  *
 565  * DESCRIPTION
 566  *
 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
 571  *    function.
 572  *
 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.
 584  *
 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.
 588  *
 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
 592  *    function.
 593  *
 594  ***/
 595 SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
 596                                         SilcBuffer ke_payload);
 597
 598 /****f* silcske/SilcSKEAPI/silc_ske_responder_start
 599  *
 600  * SYNOPSIS
 601  *
 602  *    SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
 603  *                                           SilcSocketConnection sock,
 604  *                                           const char *version,
 605  *                                           SilcBuffer start_payload,
 606  *                                           SilcSKESecurityPropertyFlag
 607  *                                                               flags);
 608  *
 609  * DESCRIPTION
 610  *
 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
 621  *    enforced flags.
 622  *
 623  *    After this function the responder calls immediately, or with short
 624  *    timeout the silc_ske_responder_phase_1 function.
 625  *
 626  ***/
 627 SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
 628                                        SilcSocketConnection sock,
 629                                        const char *version,
 630                                        SilcBuffer start_payload,
 631                                        SilcSKESecurityPropertyFlag flags);
 632
 633 /****f* silcske/SilcSKEAPI/silc_ske_responder_phase_1
 634  *
 635  * SYNOPSIS
 636  *
 637  *    SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske);
 638  *
 639  * DESCRIPTION
 640  *
 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.
 645  *
 646  *    After this function the responder must wait for reply from the
 647  *    initiator.
 648  *
 649  ***/
 650 SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske);
 651
 652 /****f* silcske/SilcSKEAPI/silc_ske_responder_phase_2
 653  *
 654  * SYNOPSIS
 655  *
 656  *    SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
 657  *                                             SilcBuffer ke_payload);
 658  *
 659  * DESCRIPTION
 660  *
 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
 665  *    function.
 666  *
 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
 678  *    function.
 679  *
 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.
 683  *
 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.
 687  *
 688  ***/
 689 SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
 690                                          SilcBuffer ke_payload);
 691
 692 /****f* silcske/SilcSKEAPI/silc_ske_responder_finish
 693  *
 694  * SYNOPSIS
 695  *
 696  *    SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
 697  *                                            SilcPublicKey public_key,
 698  *                                            SilcPrivateKey private_key,
 699  *                                            SilcSKEPKType pk_type);
 700  *
 701  * DESCRIPTION
 702  *
 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.
 709  *
 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.
 712  *
 713  ***/
 714 SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
 715                                         SilcPublicKey public_key,
 716                                         SilcPrivateKey private_key,
 717                                         SilcSKEPKType pk_type);
 718
 719 /****f* silcske/SilcSKEAPI/silc_ske_end
 720  *
 721  * SYNOPSIS
 722  *
 723  *    SilcSKEStatus silc_ske_end(SilcSKE ske);
 724  *
 725  * DESCRIPTION
 726  *
 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.
 731  *
 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
 736  *    indication.
 737  *
 738  * NOTES
 739  *
 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.
 743  *
 744  ***/
 745 SilcSKEStatus silc_ske_end(SilcSKE ske);
 746
 747 /****f* silcske/SilcSKEAPI/silc_ske_abort
 748  *
 749  * SYNOPSIS
 750  *
 751  *    SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status);
 752  *
 753  * DESCRIPTION
 754  *
 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.
 758  *
 759  ***/
 760 SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status);
 761
 762 /****f* silcske/SilcSKEAPI/silc_ske_assemble_security_properties
 763  *
 764  * SYNOPSIS
 765  *
 766  *    SilcSKEStatus
 767  *    silc_ske_assemble_security_properties(SilcSKE ske,
 768  *                                          SilcSKESecurityPropertyFlag flags,
 769  *                                          const char *version,
 770  *                                          SilcSKEStartPayload
 771  *                                            **return_payload);
 772  *
 773  * DESCRIPTION
 774  *
 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.
 782  *
 783  ***/
 784 SilcSKEStatus
 785 silc_ske_assemble_security_properties(SilcSKE ske,
 786                                       SilcSKESecurityPropertyFlag flags,
 787                                       const char *version,
 788                                       SilcSKEStartPayload **return_payload);
 789
 790 /****f* silcske/SilcSKEAPI/silc_ske_select_security_properties
 791  *
 792  * SYNOPSIS
 793  *
 794  *    SilcSKEStatus
 795  *    silc_ske_select_security_properties(SilcSKE ske,
 796  *                                        const char *version,
 797  *                                        SilcSKEStartPayload *payload,
 798  *                                        SilcSKEStartPayload *remote_payload);
 799  *
 800  * DESCRIPTION
 801  *
 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.
 811  *
 812  ***/
 813 SilcSKEStatus
 814 silc_ske_select_security_properties(SilcSKE ske,
 815                                     const char *version,
 816                                     SilcSKEStartPayload *payload,
 817                                     SilcSKEStartPayload *remote_payload);
 818
 819 /****f* silcske/SilcSKEAPI/silc_ske_process_key_material
 820  *
 821  * SYNOPSIS
 822  *
 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);
 828  *
 829  * DESCRIPTION
 830  *
 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
 840  *    free.
 841  *
 842  ***/
 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);
 848
 849 /****f* silcske/SilcSKEAPI/silc_ske_process_key_material_data
 850  *
 851  * SYNOPSIS
 852  *
 853  *    SilcSKEStatus
 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,
 859  *                                       SilcHash hash,
 860  *                                       SilcSKEKeyMaterial *key);
 861  *
 862  * DESCRIPTION
 863  *
 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.
 872  *
 873  ***/
 874 SilcSKEStatus
 875 silc_ske_process_key_material_data(unsigned char *data,
 876                                    SilcUInt32 data_len,
 877                                    SilcUInt32 req_iv_len,
 878                                    SilcUInt32 req_enc_key_len,
 879                                    SilcUInt32 req_hmac_key_len,
 880                                    SilcHash hash,
 881                                    SilcSKEKeyMaterial *key);
 882
 883 /****f* silcske/SilcSKEAPI/silc_ske_free_key_material
 884  *
 885  * SYNOPSIS
 886  *
 887  *    void silc_ske_free_key_material(SilcSKEKeyMaterial *key);
 888  *
 889  * DESCRIPTION
 890  *
 891  *    Frees the key material indicated by `key', and all data in it.
 892  *
 893  ***/
 894 void silc_ske_free_key_material(SilcSKEKeyMaterial *key);
 895
 896 /****f* silcske/SilcSKEAPI/silc_ske_parse_version
 897  *
 898  * SYNOPSIS
 899  *
 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);
 906  *
 907  * DESCRIPTION
 908  *
 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.
 915  *
 916  ***/
 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);
 923
 924 #endif  /* !SILCSKE_H */