lib/silcske/silcske.h

   1 /*
   2
   3   silcske.h
   4
   5   Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
   6
   7   Copyright (C) 2000 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                                          unsigned int 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   unsigned int iv_len;
  65   unsigned char *send_enc_key;
  66   unsigned char *receive_enc_key;
  67   unsigned int enc_key_len;
  68   unsigned char *hmac_key;
  69   unsigned int 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      = (1L << 0),
  81   SILC_SKE_SP_FLAG_NO_REPLY  = (1L << 1),
  82   SILC_SKE_SP_FLAG_PFS       = (1L << 2),
  83 } SilcSKESecurityPropertyFlag;
  84
  85 /* Security Properties negotiated between key exchange parties. This
  86    structure is filled from the Key Exchange Start Payload which is used
  87    to negotiate what security properties should be used in the
  88    communication. */
  89 struct SilcSKESecurityPropertiesStruct {
  90   unsigned char flags;
  91   SilcSKEDiffieHellmanGroup group;
  92   SilcPKCS pkcs;
  93   SilcCipher cipher;
  94   SilcHash hash;
  95   SilcHmac hmac;
  96   /* XXX SilcZip comp; */
  97 };
  98
  99 struct SilcSKEStruct {
 100   /* The connection object. This is initialized by the caller. */
 101   SilcSocketConnection sock;
 102
 103   /* Security properties negotiated */
 104   SilcSKESecurityProperties prop;
 105
 106   /* Key Exchange payloads filled during key negotiation with
 107      remote data. Responder may save local data here as well. */
 108   SilcSKEStartPayload *start_payload;
 109   SilcSKEOnePayload *ke1_payload;
 110   SilcSKETwoPayload *ke2_payload;
 111
 112   /* Temporary copy of the KE Start Payload used in the
 113      HASH computation. */
 114   SilcBuffer start_payload_copy;
 115
 116   /* If initiator, this is responders public key. If responder this
 117      is our own public key. */
 118   unsigned char *pk;
 119   unsigned int pk_len;
 120
 121   /* Random number x, 1 < x < q. This is the secret exponent
 122      used in Diffie Hellman computations. */
 123   SilcInt *x;
 124
 125   /* The secret shared key */
 126   SilcInt *KEY;
 127
 128   /* The hash value HASH of the key exchange */
 129   unsigned char *hash;
 130   unsigned int hash_len;
 131
 132   /* Random Number Generator. This is set by the caller and must
 133      be free'd by the caller. */
 134   SilcRng rng;
 135
 136   /* Pointer to the what ever user data. This is set by the caller
 137      and is not touched by the SKE. The caller must also free this one. */
 138   void *user_data;
 139
 140   /* Current status of SKE */
 141   SilcSKEStatus status;
 142 };
 143
 144 /* Prototypes */
 145 SilcSKE silc_ske_alloc();
 146 void silc_ske_free(SilcSKE ske);
 147 SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng,
 148                                        SilcSocketConnection sock,
 149                                        SilcSKEStartPayload *start_payload,
 150                                        SilcSKESendPacketCb send_packet,
 151                                        void *context);
 152 SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske,
 153                                          SilcBuffer start_payload,
 154                                          SilcSKECb callback,
 155                                          void *context);
 156 SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske,
 157                                          SilcPublicKey public_key,
 158                                          SilcSKESendPacketCb send_packet,
 159                                          void *context);
 160 SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
 161                                         SilcBuffer ke2_payload,
 162                                         SilcSKEVerifyCb verify_key,
 163                                         void *verify_context,
 164                                         SilcSKECb callback,
 165                                         void *context);
 166 SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
 167                                        SilcSocketConnection sock,
 168                                        char *version,
 169                                        SilcBuffer start_payload,
 170                                        SilcSKECb callback,
 171                                        void *context);
 172 SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske,
 173                                          SilcSKEStartPayload *start_payload,
 174                                          SilcSKESendPacketCb send_packet,
 175                                          void *context);
 176 SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
 177                                          SilcBuffer ke1_payload,
 178                                          SilcSKECb callback,
 179                                          void *context);
 180 SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
 181                                         SilcPublicKey public_key,
 182                                         SilcPrivateKey private_key,
 183                                         SilcSKEPKType pk_type,
 184                                         SilcSKESendPacketCb send_packet,
 185                                         void *context);
 186 SilcSKEStatus silc_ske_end(SilcSKE ske,
 187                            SilcSKESendPacketCb send_packet,
 188                            void *context);
 189 SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status,
 190                              SilcSKESendPacketCb send_packet,
 191                              void *context);
 192 SilcSKEStatus
 193 silc_ske_assemble_security_properties(SilcSKE ske,
 194                                       unsigned char flags,
 195                                       char *version,
 196                                       SilcSKEStartPayload **return_payload);
 197 SilcSKEStatus
 198 silc_ske_select_security_properties(SilcSKE ske,
 199                                     char *version,
 200                                     SilcSKEStartPayload *payload,
 201                                     SilcSKEStartPayload *remote_payload);
 202 SilcSKEStatus silc_ske_create_rnd(SilcSKE ske, SilcInt n,
 203                                   unsigned int len,
 204                                   SilcInt *rnd);
 205 SilcSKEStatus silc_ske_make_hash(SilcSKE ske,
 206                                  unsigned char *return_hash,
 207                                  unsigned int *return_hash_len);
 208 SilcSKEStatus
 209 silc_ske_process_key_material_data(unsigned char *data,
 210                                    unsigned int data_len,
 211                                    unsigned int req_iv_len,
 212                                    unsigned int req_enc_key_len,
 213                                    unsigned int req_hmac_key_len,
 214                                    SilcHash hash,
 215                                    SilcSKEKeyMaterial *key);
 216 SilcSKEStatus silc_ske_process_key_material(SilcSKE ske,
 217                                             unsigned int req_iv_len,
 218                                             unsigned int req_enc_key_len,
 219                                             unsigned int req_hmac_key_len,
 220                                             SilcSKEKeyMaterial *key);
 221 SilcSKEStatus silc_ske_check_version(SilcSKE ske,
 222                                      unsigned char *version,
 223                                      unsigned int version_len);
 224 void silc_ske_free_key_material(SilcSKEKeyMaterial *key);
 225
 226 #endif