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). This is usually called
  50    to indicate that the application may continue the execution of the
  51    SKE protocol. The application should check the ske->status in this
  52    callback function. */
  53 typedef void (*SilcSKECb)(SilcSKE ske, void *context);
  54
  55 /* Completion callback that will be called when the public key
  56    has been verified.  The `status' will indicate whether the public
  57    key were trusted or not. If the `status' is PENDING then the status
  58    is not considered to be available at this moment. In this case the
  59    SKE libary will assume that the caller will call this callback again
  60    when the status is available. */
  61 typedef void (*SilcSKEVerifyCbCompletion)(SilcSKE ske,
  62                                           SilcSKEStatus status,
  63                                           void *context);
  64
  65 /* Callback function used to verify the received public key or certificate.
  66    The verification process is most likely asynchronous. That's why the
  67    application must call the `completion' callback when the verification
  68    process has been completed. The library then calls the user callback
  69    (SilcSKECb), if it was provided for the function that takes this callback
  70    function as argument, to indicate that the SKE protocol may continue. */
  71 typedef void (*SilcSKEVerifyCb)(SilcSKE ske,
  72                                 unsigned char *pk_data,
  73                                 uint32 pk_len,
  74                                 SilcSKEPKType pk_type,
  75                                 void *context,
  76                                 SilcSKEVerifyCbCompletion completion,
  77                                 void *completion_context);
  78
  79 /* Context passed to key material processing function. The function
  80    returns the processed key material into this structure. */
  81 typedef struct {
  82   unsigned char *send_iv;
  83   unsigned char *receive_iv;
  84   uint32 iv_len;
  85   unsigned char *send_enc_key;
  86   unsigned char *receive_enc_key;
  87   uint32 enc_key_len;
  88   unsigned char *hmac_key;
  89   uint32 hmac_key_len;
  90 } SilcSKEKeyMaterial;
  91
  92 /* Length of cookie in Start Payload */
  93 #define SILC_SKE_COOKIE_LEN 16
  94
  95 #include "groups.h"
  96 #include "payload.h"
  97
  98 /* Security Property Flags. */
  99 typedef enum {
 100   SILC_SKE_SP_FLAG_NONE      = 0x00,
 101   SILC_SKE_SP_FLAG_NO_REPLY  = 0x01,
 102   SILC_SKE_SP_FLAG_PFS       = 0x02,
 103   SILC_SKE_SP_FLAG_MUTUAL    = 0x04,
 104 } SilcSKESecurityPropertyFlag;
 105
 106 /* Security Properties negotiated between key exchange parties. This
 107    structure is filled from the Key Exchange Start Payload which is used
 108    to negotiate what security properties should be used in the
 109    communication. */
 110 struct SilcSKESecurityPropertiesStruct {
 111   unsigned char flags;
 112   SilcSKEDiffieHellmanGroup group;
 113   SilcPKCS pkcs;
 114   SilcCipher cipher;
 115   SilcHash hash;
 116   SilcHmac hmac;
 117   /* XXX SilcZip comp; */
 118 };
 119
 120 struct SilcSKEStruct {
 121   /* The connection object. This is initialized by the caller. */
 122   SilcSocketConnection sock;
 123
 124   /* Security properties negotiated */
 125   SilcSKESecurityProperties prop;
 126
 127   /* Key Exchange payloads filled during key negotiation with
 128      remote data. Responder may save local data here as well. */
 129   SilcSKEStartPayload *start_payload;
 130   SilcSKEKEPayload *ke1_payload;
 131   SilcSKEKEPayload *ke2_payload;
 132
 133   /* Temporary copy of the KE Start Payload used in the
 134      HASH computation. */
 135   SilcBuffer start_payload_copy;
 136
 137   /* If initiator, this is responders public key. If responder this
 138      is our own public key. */
 139   unsigned char *pk;
 140   uint32 pk_len;
 141
 142   /* Random number x, 1 < x < q. This is the secret exponent
 143      used in Diffie Hellman computations. */
 144   SilcMPInt *x;
 145
 146   /* The secret shared key */
 147   SilcMPInt *KEY;
 148
 149   /* The hash value HASH of the key exchange */
 150   unsigned char *hash;
 151   uint32 hash_len;
 152
 153   /* Random Number Generator. This is set by the caller and must
 154      be free'd by the caller. */
 155   SilcRng rng;
 156
 157   /* Pointer to the what ever user data. This is set by the caller
 158      and is not touched by the SKE. The caller must also free this one. */
 159   void *user_data;
 160
 161   /* Current status of SKE */
 162   SilcSKEStatus status;
 163 };
 164
 165 /* Prototypes */
 166 SilcSKE silc_ske_alloc();
 167 void silc_ske_free(SilcSKE ske);
 168 SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng,
 169                                        SilcSocketConnection sock,
 170                                        SilcSKEStartPayload *start_payload,
 171                                        SilcSKESendPacketCb send_packet,
 172                                        void *context);
 173 SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske,
 174                                          SilcBuffer start_payload,
 175                                          SilcSKECb callback,
 176                                          void *context);
 177 SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske,
 178                                          SilcPublicKey public_key,
 179                                          SilcPrivateKey private_key,
 180                                          SilcSKESendPacketCb send_packet,
 181                                          void *context);
 182 SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
 183                                         SilcBuffer ke_payload,
 184                                         SilcSKEVerifyCb verify_key,
 185                                         void *verify_context,
 186                                         SilcSKECb callback,
 187                                         void *context);
 188 SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
 189                                        SilcSocketConnection sock,
 190                                        char *version,
 191                                        SilcBuffer start_payload,
 192                                        int mutual_auth,
 193                                        SilcSKECb callback,
 194                                        void *context);
 195 SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske,
 196                                          SilcSKEStartPayload *start_payload,
 197                                          SilcSKESendPacketCb send_packet,
 198                                          void *context);
 199 SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
 200                                          SilcBuffer ke_payload,
 201                                          SilcSKEVerifyCb verify_key,
 202                                          void *verify_context,
 203                                          SilcSKECb callback,
 204                                          void *context);
 205 SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
 206                                         SilcPublicKey public_key,
 207                                         SilcPrivateKey private_key,
 208                                         SilcSKEPKType pk_type,
 209                                         SilcSKESendPacketCb send_packet,
 210                                         void *context);
 211 SilcSKEStatus silc_ske_end(SilcSKE ske,
 212                            SilcSKESendPacketCb send_packet,
 213                            void *context);
 214 SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status,
 215                              SilcSKESendPacketCb send_packet,
 216                              void *context);
 217 SilcSKEStatus
 218 silc_ske_assemble_security_properties(SilcSKE ske,
 219                                       unsigned char flags,
 220                                       char *version,
 221                                       SilcSKEStartPayload **return_payload);
 222 SilcSKEStatus
 223 silc_ske_select_security_properties(SilcSKE ske,
 224                                     char *version,
 225                                     SilcSKEStartPayload *payload,
 226                                     SilcSKEStartPayload *remote_payload);
 227 SilcSKEStatus silc_ske_create_rnd(SilcSKE ske, SilcMPInt n,
 228                                   uint32 len,
 229                                   SilcMPInt *rnd);
 230 SilcSKEStatus silc_ske_make_hash(SilcSKE ske,
 231                                  unsigned char *return_hash,
 232                                  uint32 *return_hash_len,
 233                                  int initiator);
 234 SilcSKEStatus
 235 silc_ske_process_key_material_data(unsigned char *data,
 236                                    uint32 data_len,
 237                                    uint32 req_iv_len,
 238                                    uint32 req_enc_key_len,
 239                                    uint32 req_hmac_key_len,
 240                                    SilcHash hash,
 241                                    SilcSKEKeyMaterial *key);
 242 SilcSKEStatus silc_ske_process_key_material(SilcSKE ske,
 243                                             uint32 req_iv_len,
 244                                             uint32 req_enc_key_len,
 245                                             uint32 req_hmac_key_len,
 246                                             SilcSKEKeyMaterial *key);
 247 SilcSKEStatus silc_ske_check_version(SilcSKE ske,
 248                                      unsigned char *version,
 249                                      uint32 version_len);
 250 void silc_ske_free_key_material(SilcSKEKeyMaterial *key);
 251
 252 #endif