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   */
  41 } SilcSKEPKType;
  42
  43 /* Packet sending callback. Caller of the SKE routines must provide
  44    a routine to send packets to negotiation parties. */
  45 typedef void (*SilcSKESendPacketCb)(SilcSKE ske, SilcBuffer packet,
  46                                     SilcPacketType type, void *context);
  47
  48 /* Generic SKE callback function. This is called in various SKE
  49    routines. The SilcSKE object sent as argument provides all the data
  50    callers routine might need (payloads etc). */
  51 typedef void (*SilcSKECb)(SilcSKE ske, void *context);
  52
  53 /* Callback function used to verify the received public key. */
  54 typedef SilcSKEStatus (*SilcSKEVerifyCb)(SilcSKE ske,
  55                                          unsigned char *pk_data,
  56                                          unsigned int pk_len,
  57                                          SilcSKEPKType pk_type,
  58                                          void *context);
  59
  60 /* Context passed to key material processing function. The function
  61    returns the processed key material into this structure. */
  62 typedef struct {
  63   unsigned char *send_iv;
  64   unsigned char *receive_iv;
  65   unsigned int iv_len;
  66   unsigned char *send_enc_key;
  67   unsigned char *receive_enc_key;
  68   unsigned int enc_key_len;
  69   unsigned char *hmac_key;
  70   unsigned int hmac_key_len;
  71 } SilcSKEKeyMaterial;
  72
  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   /* XXX SilcCompression comp; */
  96 };
  97
  98 struct SilcSKEStruct {
  99   /* The connection object. This is initialized by the caller. */
 100   SilcSocketConnection sock;
 101
 102   /* Security properties negotiated */
 103   SilcSKESecurityProperties prop;
 104
 105   /* Key Exchange payloads filled during key negotiation with
 106      remote data. Responder may save local data here as well. */
 107   SilcSKEStartPayload *start_payload;
 108   SilcSKEOnePayload *ke1_payload;
 109   SilcSKETwoPayload *ke2_payload;
 110
 111   /* Temporary copy of the KE Start Payload used in the
 112      HASH computation. */
 113   SilcBuffer start_payload_copy;
 114
 115   /* If initiator, this is responders public key. If responder this
 116      is our own public key. */
 117   unsigned char *pk;
 118   unsigned int pk_len;
 119
 120   /* Random number x, 1 < x < q. This is the secret exponent
 121      used in Diffie Hellman computations. */
 122   SilcInt x;
 123
 124   /* The secret shared key */
 125   SilcInt KEY;
 126
 127   /* The hash value HASH of the key exchange */
 128   unsigned char *hash;
 129   unsigned int hash_len;
 130
 131   /* Random Number Generator. This is set by the caller and must
 132      be free'd by the caller. */
 133   SilcRng rng;
 134
 135   /* Pointer to the what ever user data. This is set by the caller
 136      and is not touched by the SKE. The caller must also free this one. */
 137   void *user_data;
 138 };
 139
 140 /* Prototypes */
 141 SilcSKE silc_ske_alloc();
 142 void silc_ske_free(SilcSKE ske);
 143 SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng,
 144                                        SilcSocketConnection sock,
 145                                        SilcSKEStartPayload *start_payload,
 146                                        SilcSKESendPacketCb send_packet,
 147                                        void *context);
 148 SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske,
 149                                          SilcBuffer start_payload,
 150                                          SilcSKECb callback,
 151                                          void *context);
 152 SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske,
 153                                          SilcPublicKey public_key,
 154                                          SilcSKESendPacketCb send_packet,
 155                                          void *context);
 156 SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
 157                                         SilcBuffer ke2_payload,
 158                                         SilcSKEVerifyCb verify_key,
 159                                         void *verify_context,
 160                                         SilcSKECb callback,
 161                                         void *context);
 162 SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
 163                                        SilcSocketConnection sock,
 164                                        char *version,
 165                                        SilcBuffer start_payload,
 166                                        SilcSKECb callback,
 167                                        void *context);
 168 SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske,
 169                                          SilcSKEStartPayload *start_payload,
 170                                          SilcSKESendPacketCb send_packet,
 171                                          void *context);
 172 SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
 173                                          SilcBuffer ke1_payload,
 174                                          SilcSKECb callback,
 175                                          void *context);
 176 SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
 177                                         SilcPublicKey public_key,
 178                                         SilcPrivateKey private_key,
 179                                         SilcSKEPKType pk_type,
 180                                         SilcSKESendPacketCb send_packet,
 181                                         void *context);
 182 SilcSKEStatus silc_ske_end(SilcSKE ske,
 183                            SilcSKESendPacketCb send_packet,
 184                            void *context);
 185 SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status,
 186                              SilcSKESendPacketCb send_packet,
 187                              void *context);
 188 SilcSKEStatus
 189 silc_ske_assemble_security_properties(SilcSKE ske,
 190                                       char *version,
 191                                       SilcSKEStartPayload **return_payload);
 192 SilcSKEStatus
 193 silc_ske_select_security_properties(SilcSKE ske,
 194                                     char *version,
 195                                     SilcSKEStartPayload *payload,
 196                                     SilcSKEStartPayload *remote_payload);
 197 SilcSKEStatus silc_ske_create_rnd(SilcSKE ske, SilcInt n,
 198                                   unsigned int len,
 199                                   SilcInt *rnd);
 200 SilcSKEStatus silc_ske_make_hash(SilcSKE ske,
 201                                  unsigned char *return_hash,
 202                                  unsigned int *return_hash_len);
 203 SilcSKEStatus silc_ske_process_key_material(SilcSKE ske,
 204                                             unsigned int req_iv_len,
 205                                             unsigned int req_enc_key_len,
 206                                             unsigned int req_hmac_key_len,
 207                                             SilcSKEKeyMaterial *key);
 208 #endif