lib/silcske/silcske.h

   1 /*
   2
   3   silcske.h
   4
   5   Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
   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 /* Supported Public Key Types, defined by the protocol */
  33 typedef enum {
  34   SILC_SKE_PK_TYPE_SILC    = 1, /* Mandatory type */
  35   /* Optional types. These are not implemented currently */
  36   SILC_SKE_PK_TYPE_SSH2    = 2,
  37   SILC_SKE_PK_TYPE_X509V3  = 3,
  38   SILC_SKE_PK_TYPE_OPENPGP = 4,
  39   SILC_SKE_PK_TYPE_SPKI    = 5
  40 } SilcSKEPKType;
  41
  42 /* Packet sending callback. Caller of the SKE routines must provide
  43    a routine to send packets to negotiation parties. */
  44 typedef void (*SilcSKESendPacketCb)(SilcSKE ske, SilcBuffer packet,
  45                                     SilcPacketType type, void *context);
  46
  47 /* Generic SKE callback function. This is called in various SKE
  48    routines. The SilcSKE object sent as argument provides all the data
  49    callers routine might need (payloads etc). */
  50 typedef void (*SilcSKECb)(SilcSKE ske, void *context);
  51
  52 /* Callback function used to verify the received public key. */
  53 typedef SilcSKEStatus (*SilcSKEVerifyCb)(SilcSKE ske,
  54                                          unsigned char *pk_data,
  55                                          uint32 pk_len,
  56                                          SilcSKEPKType pk_type,
  57                                          void *context);
  58
  59 /* Context passed to key material processing function. The function
  60    returns the processed key material into this structure. */
  61 typedef struct {
  62   unsigned char *send_iv;
  63   unsigned char *receive_iv;
  64   uint32 iv_len;
  65   unsigned char *send_enc_key;
  66   unsigned char *receive_enc_key;
  67   uint32 enc_key_len;
  68   unsigned char *hmac_key;
  69   uint32 hmac_key_len;
  70 } SilcSKEKeyMaterial;
  71
  72 /* Length of cookie in Start Payload */
  73 #define SILC_SKE_COOKIE_LEN 16
  74
  75 #include "groups.h"
  76 #include "payload.h"
  77
  78 /* Security Property Flags. */
  79 typedef enum {
  80   SILC_SKE_SP_FLAG_NONE      = 0x00,
  81   SILC_SKE_SP_FLAG_NO_REPLY  = 0x01,
  82   SILC_SKE_SP_FLAG_PFS       = 0x02,
  83   SILC_SKE_SP_FLAG_MUTUAL    = 0x04,
  84 } SilcSKESecurityPropertyFlag;
  85
  86 /* Security Properties negotiated between key exchange parties. This
  87    structure is filled from the Key Exchange Start Payload which is used
  88    to negotiate what security properties should be used in the
  89    communication. */
  90 struct SilcSKESecurityPropertiesStruct {
  91   unsigned char flags;
  92   SilcSKEDiffieHellmanGroup group;
  93   SilcPKCS pkcs;
  94   SilcCipher cipher;
  95   SilcHash hash;
  96   SilcHmac hmac;
  97   /* XXX SilcZip comp; */
  98 };
  99
 100 struct SilcSKEStruct {
 101   /* The connection object. This is initialized by the caller. */
 102   SilcSocketConnection sock;
 103
 104   /* Security properties negotiated */
 105   SilcSKESecurityProperties prop;
 106
 107   /* Key Exchange payloads filled during key negotiation with
 108      remote data. Responder may save local data here as well. */
 109   SilcSKEStartPayload *start_payload;
 110   SilcSKEKEPayload *ke1_payload;
 111   SilcSKEKEPayload *ke2_payload;
 112
 113   /* Temporary copy of the KE Start Payload used in the
 114      HASH computation. */
 115   SilcBuffer start_payload_copy;
 116
 117   /* If initiator, this is responders public key. If responder this
 118      is our own public key. */
 119   unsigned char *pk;
 120   uint32 pk_len;
 121
 122   /* Random number x, 1 < x < q. This is the secret exponent
 123      used in Diffie Hellman computations. */
 124   SilcInt *x;
 125
 126   /* The secret shared key */
 127   SilcInt *KEY;
 128
 129   /* The hash value HASH of the key exchange */
 130   unsigned char *hash;
 131   uint32 hash_len;
 132
 133   /* Random Number Generator. This is set by the caller and must
 134      be free'd by the caller. */
 135   SilcRng rng;
 136
 137   /* Pointer to the what ever user data. This is set by the caller
 138      and is not touched by the SKE. The caller must also free this one. */
 139   void *user_data;
 140
 141   /* Current status of SKE */
 142   SilcSKEStatus status;
 143 };
 144
 145 /* Prototypes */
 146 SilcSKE silc_ske_alloc();
 147 void silc_ske_free(SilcSKE ske);
 148 SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng,
 149                                        SilcSocketConnection sock,
 150                                        SilcSKEStartPayload *start_payload,
 151                                        SilcSKESendPacketCb send_packet,
 152                                        void *context);
 153 SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske,
 154                                          SilcBuffer start_payload,
 155                                          SilcSKECb callback,
 156                                          void *context);
 157 SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske,
 158                                          SilcPublicKey public_key,
 159                                          SilcPrivateKey private_key,
 160                                          SilcSKESendPacketCb send_packet,
 161                                          void *context);
 162 SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
 163                                         SilcBuffer ke_payload,
 164                                         SilcSKEVerifyCb verify_key,
 165                                         void *verify_context,
 166                                         SilcSKECb callback,
 167                                         void *context);
 168 SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
 169                                        SilcSocketConnection sock,
 170                                        char *version,
 171                                        SilcBuffer start_payload,
 172                                        int mutual_auth,
 173                                        SilcSKECb callback,
 174                                        void *context);
 175 SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske,
 176                                          SilcSKEStartPayload *start_payload,
 177                                          SilcSKESendPacketCb send_packet,
 178                                          void *context);
 179 SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
 180                                          SilcBuffer ke_payload,
 181                                          SilcSKEVerifyCb verify_key,
 182                                          void *verify_context,
 183                                          SilcSKECb callback,
 184                                          void *context);
 185 SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
 186                                         SilcPublicKey public_key,
 187                                         SilcPrivateKey private_key,
 188                                         SilcSKEPKType pk_type,
 189                                         SilcSKESendPacketCb send_packet,
 190                                         void *context);
 191 SilcSKEStatus silc_ske_end(SilcSKE ske,
 192                            SilcSKESendPacketCb send_packet,
 193                            void *context);
 194 SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status,
 195                              SilcSKESendPacketCb send_packet,
 196                              void *context);
 197 SilcSKEStatus
 198 silc_ske_assemble_security_properties(SilcSKE ske,
 199                                       unsigned char flags,
 200                                       char *version,
 201                                       SilcSKEStartPayload **return_payload);
 202 SilcSKEStatus
 203 silc_ske_select_security_properties(SilcSKE ske,
 204                                     char *version,
 205                                     SilcSKEStartPayload *payload,
 206                                     SilcSKEStartPayload *remote_payload);
 207 SilcSKEStatus silc_ske_create_rnd(SilcSKE ske, SilcInt n,
 208                                   uint32 len,
 209                                   SilcInt *rnd);
 210 SilcSKEStatus silc_ske_make_hash(SilcSKE ske,
 211                                  unsigned char *return_hash,
 212                                  uint32 *return_hash_len,
 213                                  int initiator);
 214 SilcSKEStatus
 215 silc_ske_process_key_material_data(unsigned char *data,
 216                                    uint32 data_len,
 217                                    uint32 req_iv_len,
 218                                    uint32 req_enc_key_len,
 219                                    uint32 req_hmac_key_len,
 220                                    SilcHash hash,
 221                                    SilcSKEKeyMaterial *key);
 222 SilcSKEStatus silc_ske_process_key_material(SilcSKE ske,
 223                                             uint32 req_iv_len,
 224                                             uint32 req_enc_key_len,
 225                                             uint32 req_hmac_key_len,
 226                                             SilcSKEKeyMaterial *key);
 227 SilcSKEStatus silc_ske_check_version(SilcSKE ske,
 228                                      unsigned char *version,
 229                                      uint32 version_len);
 230 void silc_ske_free_key_material(SilcSKEKeyMaterial *key);
 231
 232 #endif