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   /* Reference counter. This is used when SKE library is performing async
 165      operations, like public key verification. */
 166   int users;
 167 };
 168
 169 /* Prototypes */
 170 SilcSKE silc_ske_alloc();
 171 void silc_ske_free(SilcSKE ske);
 172 SilcSKEStatus silc_ske_initiator_start(SilcSKE ske, SilcRng rng,
 173                                        SilcSocketConnection sock,
 174                                        SilcSKEStartPayload *start_payload,
 175                                        SilcSKESendPacketCb send_packet,
 176                                        void *context);
 177 SilcSKEStatus silc_ske_initiator_phase_1(SilcSKE ske,
 178                                          SilcBuffer start_payload,
 179                                          SilcSKECb callback,
 180                                          void *context);
 181 SilcSKEStatus silc_ske_initiator_phase_2(SilcSKE ske,
 182                                          SilcPublicKey public_key,
 183                                          SilcPrivateKey private_key,
 184                                          SilcSKESendPacketCb send_packet,
 185                                          void *context);
 186 SilcSKEStatus silc_ske_initiator_finish(SilcSKE ske,
 187                                         SilcBuffer ke_payload,
 188                                         SilcSKEVerifyCb verify_key,
 189                                         void *verify_context,
 190                                         SilcSKECb callback,
 191                                         void *context);
 192 SilcSKEStatus silc_ske_responder_start(SilcSKE ske, SilcRng rng,
 193                                        SilcSocketConnection sock,
 194                                        char *version,
 195                                        SilcBuffer start_payload,
 196                                        int mutual_auth,
 197                                        SilcSKECb callback,
 198                                        void *context);
 199 SilcSKEStatus silc_ske_responder_phase_1(SilcSKE ske,
 200                                          SilcSKEStartPayload *start_payload,
 201                                          SilcSKESendPacketCb send_packet,
 202                                          void *context);
 203 SilcSKEStatus silc_ske_responder_phase_2(SilcSKE ske,
 204                                          SilcBuffer ke_payload,
 205                                          SilcSKEVerifyCb verify_key,
 206                                          void *verify_context,
 207                                          SilcSKECb callback,
 208                                          void *context);
 209 SilcSKEStatus silc_ske_responder_finish(SilcSKE ske,
 210                                         SilcPublicKey public_key,
 211                                         SilcPrivateKey private_key,
 212                                         SilcSKEPKType pk_type,
 213                                         SilcSKESendPacketCb send_packet,
 214                                         void *context);
 215 SilcSKEStatus silc_ske_end(SilcSKE ske,
 216                            SilcSKESendPacketCb send_packet,
 217                            void *context);
 218 SilcSKEStatus silc_ske_abort(SilcSKE ske, SilcSKEStatus status,
 219                              SilcSKESendPacketCb send_packet,
 220                              void *context);
 221 SilcSKEStatus
 222 silc_ske_assemble_security_properties(SilcSKE ske,
 223                                       unsigned char flags,
 224                                       char *version,
 225                                       SilcSKEStartPayload **return_payload);
 226 SilcSKEStatus
 227 silc_ske_select_security_properties(SilcSKE ske,
 228                                     char *version,
 229                                     SilcSKEStartPayload *payload,
 230                                     SilcSKEStartPayload *remote_payload);
 231 SilcSKEStatus silc_ske_create_rnd(SilcSKE ske, SilcMPInt n,
 232                                   uint32 len,
 233                                   SilcMPInt *rnd);
 234 SilcSKEStatus silc_ske_make_hash(SilcSKE ske,
 235                                  unsigned char *return_hash,
 236                                  uint32 *return_hash_len,
 237                                  int initiator);
 238 SilcSKEStatus
 239 silc_ske_process_key_material_data(unsigned char *data,
 240                                    uint32 data_len,
 241                                    uint32 req_iv_len,
 242                                    uint32 req_enc_key_len,
 243                                    uint32 req_hmac_key_len,
 244                                    SilcHash hash,
 245                                    SilcSKEKeyMaterial *key);
 246 SilcSKEStatus silc_ske_process_key_material(SilcSKE ske,
 247                                             uint32 req_iv_len,
 248                                             uint32 req_enc_key_len,
 249                                             uint32 req_hmac_key_len,
 250                                             SilcSKEKeyMaterial *key);
 251 SilcSKEStatus silc_ske_check_version(SilcSKE ske,
 252                                      unsigned char *version,
 253                                      uint32 version_len);
 254 void silc_ske_free_key_material(SilcSKEKeyMaterial *key);
 255
 256 #endif