lib/silcske/silcske.h

   1 /*
   2
   3   silcske.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2000 - 2001 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; either version 2 of the License, or
  12   (at your option) any later version.
  13
  14   This program is distributed in the hope that it will be useful,
  15   but WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17   GNU General Public License for more details.
  18
  19 */
  20
  21 #ifndef SILCSKE_H
  22 #define SILCSKE_H
  23
  24 #include "silcske_status.h"
  25
  26 /* Forward declaration for SKE object. */
  27 typedef struct SilcSKEStruct *SilcSKE;
  28
  29 /* Forward declaration for security properties. */
  30 typedef struct SilcSKESecurityPropertiesStruct *SilcSKESecurityProperties;
  31
  32 /* Forward declaration for SKE callbacks structure. */
  33 typedef struct SilcSKECallbacksStruct *SilcSKECallbacks;
  34
  35 /* Supported Public Key Types, defined by the protocol */
  36 typedef enum {
  37   SILC_SKE_PK_TYPE_SILC    = 1, /* Mandatory type */
  38   /* Optional types. These are not implemented currently */
  39   SILC_SKE_PK_TYPE_SSH2    = 2,
  40   SILC_SKE_PK_TYPE_X509V3  = 3,
  41   SILC_SKE_PK_TYPE_OPENPGP = 4,
  42   SILC_SKE_PK_TYPE_SPKI    = 5
  43 } SilcSKEPKType;
  44
  45 /* Packet sending callback. Caller of the SKE routines must provide
  46    a routine to send packets to negotiation parties. See the
  47    silc_ske_set_callbacks for more information. */
  48 typedef void (*SilcSKESendPacketCb)(SilcSKE ske, SilcBuffer packet,
  49                                     SilcPacketType type, void *context);
  50
  51 /* Generic SKE callback function. This is called in various SKE
  52    routines. The SilcSKE object sent as argument provides all the data
  53    callers routine might need (payloads etc). This is usually called
  54    to indicate that the application may continue the execution of the
  55    SKE protocol. The application should check the ske->status in this
  56    callback function. This callback is also called when Start Payload
  57    is processed. See silc_ske_set_callbacks function for more information. */
  58 typedef void (*SilcSKECb)(SilcSKE ske, void *context);
  59
  60 /* Completion callback that will be called when the public key
  61    has been verified.  The `status' will indicate whether the public
  62    key were trusted or not. If the `status' is PENDING then the status
  63    is not considered to be available at this moment. In this case the
  64    SKE libary will assume that the caller will call this callback again
  65    when the status is available. See silc_ske_set_callbacks for more
  66    information. */
  67 typedef void (*SilcSKEVerifyCbCompletion)(SilcSKE ske,
  68                                           SilcSKEStatus status,
  69                                           void *context);
  70
  71 /* Callback function used to verify the received public key or certificate.
  72    The verification process is most likely asynchronous. That's why the
  73    application must call the `completion' callback when the verification
  74    process has been completed. The library then calls the user callback
  75    (SilcSKECb), if it was provided for the function that takes this callback
  76    function as argument, to indicate that the SKE protocol may continue.
  77    See silc_ske_set_callbacks for more information. */
  78 typedef void (*SilcSKEVerifyCb)(SilcSKE ske,
  79                                 unsigned char *pk_data,
  80                                 uint32 pk_len,
  81                                 SilcSKEPKType pk_type,
  82                                 void *context,
  83                                 SilcSKEVerifyCbCompletion completion,
  84                                 void *completion_context);
  85
  86 /* Callback function used to check the version of the remote SKE server.
  87    The SKE library will call this function so that the appliation may
  88    check its version against the remote host's version. This returns
  89    SILC_SKE_STATUS_OK if the version string is Ok, and returns
  90    SILC_SKE_STATUS_BAD_VERSION if the version was not acceptable. */
  91 typedef SilcSKEStatus (*SilcSKECheckVersion)(SilcSKE ske,
  92                                              unsigned char *version,
  93                                              uint32 len, void *context);
  94
  95 /* Context passed to key material processing function. The function
  96    returns the processed key material into this structure. */
  97 typedef struct {
  98   unsigned char *send_iv;
  99   unsigned char *receive_iv;
 100   uint32 iv_len;
 101   unsigned char *send_enc_key;
 102   unsigned char *receive_enc_key;
 103   uint32 enc_key_len;
 104   unsigned char *hmac_key;
 105   uint32 hmac_key_len;
 106 } SilcSKEKeyMaterial;
 107
 108 /* Length of cookie in Start Payload */
 109 #define SILC_SKE_COOKIE_LEN 16
 110
 111 #include "groups.h"
 112 #include "payload.h"
 113
 114 /* Security Property Flags. */
 115 typedef enum {
 116   SILC_SKE_SP_FLAG_NONE      = 0x00,
 117   SILC_SKE_SP_FLAG_NO_REPLY  = 0x01,
 118   SILC_SKE_SP_FLAG_PFS       = 0x02,
 119   SILC_SKE_SP_FLAG_MUTUAL    = 0x04,
 120 } SilcSKESecurityPropertyFlag;
 121
 122 /* Security Properties negotiated between key exchange parties. This
 123    structure is filled from the Key Exchange Start Payload which is used
 124    to negotiate what security properties should be used in the
 125    communication. */
 126 struct SilcSKESecurityPropertiesStruct {
 127   unsigned char flags;
 128   SilcSKEDiffieHellmanGroup group;
 129   SilcPKCS pkcs;
 130   SilcCipher cipher;
 131   SilcHash hash;
 132   SilcHmac hmac;
 133   /* XXX SilcZip comp; */
 134 };
 135
 136 struct SilcSKEStruct {
 137   /* The connection object. This is initialized by the caller. */
 138   SilcSocketConnection sock;
 139
 140   /* Security properties negotiated */
 141   SilcSKESecurityProperties prop;
 142
 143   /* Key Exchange payloads filled during key negotiation with
 144      remote data. Responder may save local data here as well. */
 145   SilcSKEStartPayload *start_payload;
 146   SilcSKEKEPayload *ke1_payload;
 147   SilcSKEKEPayload *ke2_payload;
 148
 149   /* Temporary copy of the KE Start Payload used in the
 150      HASH computation. */
 151   SilcBuffer start_payload_copy;
 152
 153   /* Random number x, 1 < x < q. This is the secret exponent
 154      used in Diffie Hellman computations. */
 155   SilcMPInt *x;
 156
 157   /* The secret shared key */
 158   SilcMPInt *KEY;
 159
 160   /* The hash value HASH of the key exchange */
 161   unsigned char *hash;
 162   uint32 hash_len;
 163
 164   /* Random Number Generator. This is set by the caller and must
 165      be free'd by the caller. */
 166   SilcRng rng;
 167
 168   /* Pointer to the what ever user data. This is set by the caller
 169      and is not touched by the SKE. The caller must also free this one. */
 170   void *user_data;
 171
 172   /* Current status of SKE */
 173   SilcSKEStatus status;
 174
 175   /* Reference counter. This is used when SKE library is performing async
 176      operations, like public key verification. */
 177   int users;
 178
 179   /* SKE callbacks. */
 180   SilcSKECallbacks callbacks;
 181 };
 182
 183 /* Prototypes */
 184 SilcSKE silc_ske_alloc();
 185 void silc_ske_free(SilcSKE ske);
 186 void silc_ske_set_callbacks(SilcSKE ske,
 187                             SilcSKESendPacketCb send_packet,
 188                             SilcSKECb payload_receive,
 189                             SilcSKEVerifyCb verify_key,
 190                             SilcSKECb proto_continue,
 191                             SilcSKECheckVersion check_version,
 192                             void *context);
 193 SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng,
 194                                        SilcSocketConnection sock,
 195                                        SilcSKEStartPayload *start_payload);
 196 SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske,
 197                                          SilcBuffer start_payload);
 198 SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske,
 199                                          SilcPublicKey public_key,
 200                                          SilcPrivateKey private_key);
 201 SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
 202                                         SilcBuffer ke_payload);
 203 SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
 204                                        SilcSocketConnection sock,
 205                                        char *version,
 206                                        SilcBuffer start_payload,
 207                                        bool mutual_auth);
 208 SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske,
 209                                          SilcSKEStartPayload *start_payload);
 210 SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
 211                                          SilcBuffer ke_payload);
 212 SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
 213                                         SilcPublicKey public_key,
 214                                         SilcPrivateKey private_key,
 215                                         SilcSKEPKType pk_type);
 216 SilcSKEStatus silc_ske_end(SilcSKE ske);
 217 SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status);
 218 SilcSKEStatus
 219 silc_ske_assemble_security_properties(SilcSKE ske,
 220                                       unsigned char flags,
 221                                       char *version,
 222                                       SilcSKEStartPayload **return_payload);
 223 SilcSKEStatus
 224 silc_ske_select_security_properties(SilcSKE ske,
 225                                     char *version,
 226                                     SilcSKEStartPayload *payload,
 227                                     SilcSKEStartPayload *remote_payload);
 228 SilcSKEStatus silc_ske_create_rnd(SilcSKE ske, SilcMPInt *n,
 229                                   uint32 len,
 230                                   SilcMPInt *rnd);
 231 SilcSKEStatus silc_ske_make_hash(SilcSKE ske,
 232                                  unsigned char *return_hash,
 233                                  uint32 *return_hash_len,
 234                                  int initiator);
 235 SilcSKEStatus
 236 silc_ske_process_key_material_data(unsigned char *data,
 237                                    uint32 data_len,
 238                                    uint32 req_iv_len,
 239                                    uint32 req_enc_key_len,
 240                                    uint32 req_hmac_key_len,
 241                                    SilcHash hash,
 242                                    SilcSKEKeyMaterial *key);
 243 SilcSKEStatus silc_ske_process_key_material(SilcSKE ske,
 244                                             uint32 req_iv_len,
 245                                             uint32 req_enc_key_len,
 246                                             uint32 req_hmac_key_len,
 247                                             SilcSKEKeyMaterial *key);
 248 void silc_ske_free_key_material(SilcSKEKeyMaterial *key);
 249
 250 #endif