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                                          SilcSKESendPacketCb send_packet,
 154                                          void *context);
 155 SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
 156                                         SilcBuffer ke2_payload,
 157                                         SilcSKEVerifyCb verify_key,
 158                                         void *verify_context,
 159                                         SilcSKECb callback,
 160                                         void *context);
 161 SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
 162                                        SilcSocketConnection sock,
 163                                        SilcBuffer start_payload,
 164                                        SilcSKECb callback,
 165                                        void *context);
 166 SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske,
 167                                          SilcSKEStartPayload *start_payload,
 168                                          SilcSKESendPacketCb send_packet,
 169                                          void *context);
 170 SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
 171                                          SilcBuffer ke1_payload,
 172                                          SilcSKECb callback,
 173                                          void *context);
 174 SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
 175                                         SilcPublicKey public_key,
 176                                         SilcPrivateKey private_key,
 177                                         SilcSKEPKType pk_type,
 178                                         SilcSKESendPacketCb send_packet,
 179                                         void *context);
 180 SilcSKEStatus silc_ske_end(SilcSKE ske,
 181                            SilcSKESendPacketCb send_packet,
 182                            void *context);
 183 SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status,
 184                              SilcSKESendPacketCb send_packet,
 185                              void *context);
 186 SilcSKEStatus
 187 silc_ske_assemble_security_properties(SilcSKE ske,
 188                                       SilcSKEStartPayload **return_payload);
 189 SilcSKEStatus
 190 silc_ske_select_security_properties(SilcSKE ske,
 191                                     SilcSKEStartPayload *payload,
 192                                     SilcSKEStartPayload *remote_payload);
 193 SilcSKEStatus silc_ske_create_rnd(SilcSKE ske, SilcInt n,
 194                                   unsigned int len,
 195                                   SilcInt *rnd);
 196 SilcSKEStatus silc_ske_make_hash(SilcSKE ske,
 197                                  unsigned char *return_hash,
 198                                  unsigned int *return_hash_len);
 199 SilcSKEStatus silc_ske_process_key_material(SilcSKE ske,
 200                                             unsigned int req_iv_len,
 201                                             unsigned int req_enc_key_len,
 202                                             unsigned int req_hmac_key_len,
 203                                             SilcSKEKeyMaterial *key);
 204 #endif