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   /* 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   /* Current status of SKE */
 140   SilcSKEStatus status;
 141 };
 142
 143 /* Prototypes */
 144 SilcSKE silc_ske_alloc();
 145 void silc_ske_free(SilcSKE ske);
 146 SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng,
 147                                        SilcSocketConnection sock,
 148                                        SilcSKEStartPayload *start_payload,
 149                                        SilcSKESendPacketCb send_packet,
 150                                        void *context);
 151 SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske,
 152                                          SilcBuffer start_payload,
 153                                          SilcSKECb callback,
 154                                          void *context);
 155 SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske,
 156                                          SilcPublicKey public_key,
 157                                          SilcSKESendPacketCb send_packet,
 158                                          void *context);
 159 SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
 160                                         SilcBuffer ke2_payload,
 161                                         SilcSKEVerifyCb verify_key,
 162                                         void *verify_context,
 163                                         SilcSKECb callback,
 164                                         void *context);
 165 SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
 166                                        SilcSocketConnection sock,
 167                                        char *version,
 168                                        SilcBuffer start_payload,
 169                                        SilcSKECb callback,
 170                                        void *context);
 171 SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske,
 172                                          SilcSKEStartPayload *start_payload,
 173                                          SilcSKESendPacketCb send_packet,
 174                                          void *context);
 175 SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
 176                                          SilcBuffer ke1_payload,
 177                                          SilcSKECb callback,
 178                                          void *context);
 179 SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
 180                                         SilcPublicKey public_key,
 181                                         SilcPrivateKey private_key,
 182                                         SilcSKEPKType pk_type,
 183                                         SilcSKESendPacketCb send_packet,
 184                                         void *context);
 185 SilcSKEStatus silc_ske_end(SilcSKE ske,
 186                            SilcSKESendPacketCb send_packet,
 187                            void *context);
 188 SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status,
 189                              SilcSKESendPacketCb send_packet,
 190                              void *context);
 191 SilcSKEStatus
 192 silc_ske_assemble_security_properties(SilcSKE ske,
 193                                       unsigned char flags,
 194                                       char *version,
 195                                       SilcSKEStartPayload **return_payload);
 196 SilcSKEStatus
 197 silc_ske_select_security_properties(SilcSKE ske,
 198                                     char *version,
 199                                     SilcSKEStartPayload *payload,
 200                                     SilcSKEStartPayload *remote_payload);
 201 SilcSKEStatus silc_ske_create_rnd(SilcSKE ske, SilcInt n,
 202                                   unsigned int len,
 203                                   SilcInt *rnd);
 204 SilcSKEStatus silc_ske_make_hash(SilcSKE ske,
 205                                  unsigned char *return_hash,
 206                                  unsigned int *return_hash_len);
 207 SilcSKEStatus silc_ske_process_key_material(SilcSKE ske,
 208                                             unsigned int req_iv_len,
 209                                             unsigned int req_enc_key_len,
 210                                             unsigned int req_hmac_key_len,
 211                                             SilcSKEKeyMaterial *key);
 212 SilcSKEStatus silc_ske_check_version(SilcSKE ske,
 213                                      unsigned char *version,
 214                                      unsigned int version_len);
 215 #endif