lib/silcske/silcconnauth.h

   1 /*
   2
   3   silcconnauth.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2005 - 2007 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; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcske/SILC Connection Authentication
  21  *
  22  * DESCRIPTION
  23  *
  24  * SILC Connection Authenetication protocol API is used to perform the
  25  * connection authentication after successful SILC Key Exchange protocol.
  26  * The interface supports authentication based on passphrases and digital
  27  * signatures.  It is also possible to have no authentication at all.
  28  *
  29  ***/
  30
  31 #ifndef SILCCONNAUTH_H
  32 #define SILCCONNAUTH_H
  33
  34 /****s* silcske/SilcConnAuthAPI/SilcConnAuth
  35  *
  36  * NAME
  37  *
  38  *    typedef struct SilcConnAuthStruct *SilcConnAuth;
  39  *
  40  * DESCRIPTION
  41  *
  42  *    The connection authentication context allocated by silc_connauth_alloc
  43  *    and given as arguments to all silc_connauth_* functions.  It is freed
  44  *    by silc_connauth_free.
  45  *
  46  ***/
  47 typedef struct SilcConnAuthStruct *SilcConnAuth;
  48
  49 /****d* silcske/SilcConnAuthAPI/SilcConnectionType
  50  *
  51  * NAME
  52  *
  53  *    typedef enum { ... } SilcConnectionType;
  54  *
  55  * DESCRIPTION
  56  *
  57  *    The type of the connection.
  58  *
  59  * SOURCE
  60  */
  61 typedef enum {
  62   SILC_CONN_UNKNOWN  = 0,       /* Unknown type, cannot be sent */
  63   SILC_CONN_CLIENT   = 1,       /* Client connection */
  64   SILC_CONN_SERVER   = 2,       /* Server connection */
  65   SILC_CONN_ROUTER   = 3        /* Router connection */
  66 } SilcConnectionType;
  67 /***/
  68
  69 /****f* silcske/SilcConnAuthAPI/SilcConnAuthGetAuthData
  70  *
  71  * SYNOPSIS
  72  *
  73  *    typedef SilcBool
  74  *    (*SilcConnAuthGetAuthData)(SilcConnAuth connauth,
  75  *                               SilcConnectionType conn_type,
  76  *                               unsigned char **passphrase,
  77  *                               SilcUInt32 *passphrase_len,
  78  *                               SilcSKR *repository,
  79  *                               void *context);
  80  *
  81  * DESCRIPTION
  82  *
  83  *    Authentication callback to retrieve the authentication data from the
  84  *    application.  This is responder callback.  If the authentication
  85  *    method is passphrase it must be returned to `passphrase' pointer.
  86  *    If it is digital signatures the key repository pointer must be
  87  *    returned into `repository' pointer, which the library will use to
  88  *    find the correct public key to verify the digital signature.
  89  *
  90  *    If this connection is not configured at all this returns FALSE which
  91  *    will result into authentication failure.  Otherwise TRUE must be
  92  *    returned.
  93  *
  94  ***/
  95 typedef SilcBool (*SilcConnAuthGetAuthData)(SilcConnAuth connauth,
  96                                             SilcConnectionType conn_type,
  97                                             unsigned char **passphrase,
  98                                             SilcUInt32 *passphrase_len,
  99                                             SilcSKR *repository,
 100                                             void *context);
 101
 102 /****f* silcske/SilcConnAuthAPI/SilcConnAuthCompletion
 103  *
 104  * SYNOPSIS
 105  *
 106  *    typedef void (*SilcConnAuthCompletion)(SilcConnAuth connauth,
 107  *                                           SilcBool success,
 108  *                                           void *context);
 109  *
 110  * DESCRIPTION
 111  *
 112  *    Completion callback called to indicated the result of the connection
 113  *    authentication protocol.  If the `success' is FALSE the authentication
 114  *    was a failure.  The authentication protocol is over after this callback
 115  *    is called.
 116  *
 117  ***/
 118 typedef void (*SilcConnAuthCompletion)(SilcConnAuth connauth,
 119                                        SilcBool success,
 120                                        void *context);
 121
 122 /****f* silcske/SilcConnAuthAPI/silc_connauth_alloc
 123  *
 124  * SYNOPSIS
 125  *
 126  *    SilcConnAuth silc_connauth_alloc(SilcSchedule schedule, SilcSKE ske,
 127  *                                     SilcUInt32 timeout_secs);
 128  *
 129  * DESCRIPTION
 130  *
 131  *    Allocates the connection authentication protocol context.  The `ske'
 132  *    is the successfully completed key exchange context.  The `timeout_secs'
 133  *    is the maximum time we are waiting for the protocol to finish before
 134  *    it is timedout.  Returns NULL on error.
 135  *
 136  ***/
 137 SilcConnAuth silc_connauth_alloc(SilcSchedule schedule, SilcSKE ske,
 138                                  SilcUInt32 timeout_secs);
 139
 140 /****f* silcske/SilcConnAuthAPI/silc_connauth_free
 141  *
 142  * SYNOPSIS
 143  *
 144  *    void silc_connauth_free(SilcConnAuth connauth);
 145  *
 146  * DESCRIPTION
 147  *
 148  *    Frees the connection authentication protocol context `connauth'.
 149  *
 150  ***/
 151 void silc_connauth_free(SilcConnAuth connauth);
 152
 153 /****f* silcske/SilcConnAuthAPI/silc_connauth_get_ske
 154  *
 155  * SYNOPSIS
 156  *
 157  *    SilcSKE silc_connauth_get_ske(SilcConnAuth connauth);
 158  *
 159  * DESCRIPTION
 160  *
 161  *    Returns the associated SilcSKE context from the `connauth'.  It is the
 162  *    pointer given as argument to silc_connauth_alloc.
 163  *
 164  ***/
 165 SilcSKE silc_connauth_get_ske(SilcConnAuth connauth);
 166
 167 /****f* silcske/SilcConnAuthAPI/silc_connauth_initiator
 168  *
 169  * SYNOPSIS
 170  *
 171  *    SilcAsyncOperation
 172  *    silc_connauth_initiator(SilcConnAuth connauth,
 173  *                            SilcConnectionType conn_type,
 174  *                            SilcAuthMethod auth_method, void *auth_data,
 175  *                            SilcUInt32 auth_data_len,
 176  *                            SilcConnAuthCompletion completion,
 177  *                            void *context);
 178  *
 179  * DESCRIPTION
 180  *
 181  *    Starts the connection authentication protocol as initiator.  The
 182  *    `conn_type' is the type of connection we are.  The `auth_method' is
 183  *    the authentication method.  If it is SILC_AUTH_PASSWORD the `auth_data'
 184  *    and `auth_data_len' is the passphrase and its length, respectively.
 185  *    If it is SILC_AUTH_PUBLIC_KEY the `auth_data' is the SilcPrivateKey
 186  *    used to produce the digital signature.  The `auth_data_len' is 0.
 187  *    The `completion' with `context' will be called after the protocol
 188  *    has completed.
 189  *
 190  *    This returns SilcAsyncOperation context which can be used to abort
 191  *    the protocol before it is completed.  Returns NULL on error.
 192  *
 193  ***/
 194 SilcAsyncOperation
 195 silc_connauth_initiator(SilcConnAuth connauth,
 196                         SilcConnectionType conn_type,
 197                         SilcAuthMethod auth_method, void *auth_data,
 198                         SilcUInt32 auth_data_len,
 199                         SilcConnAuthCompletion completion,
 200                         void *context);
 201
 202 /****f* silcske/SilcConnAuthAPI/silc_connauth_responder
 203  *
 204  * SYNOPSIS
 205  *
 206  *    SilcAsyncOperation
 207  *    silc_connauth_responder(SilcConnAuth connauth,
 208  *                            SilcConnAuthGetAuthData get_auth_data,
 209  *                            SilcConnAuthCompletion completion,
 210  *                            void *context);
 211  *
 212  * DESCRIPTION
 213  *
 214  *    Starts the connection authentication protocol as responder.  The
 215  *    `get_auth_data' is called to retrieve the authentication data for
 216  *    this connection.  The `completion' will be called after the protocol
 217  *    has completed.
 218  *
 219  *    This returns SilcAsyncOperation context which can be used to abort
 220  *    the protocol before it is completed.  Returns NULL on error.
 221  *
 222  ***/
 223 SilcAsyncOperation
 224 silc_connauth_responder(SilcConnAuth connauth,
 225                         SilcConnAuthGetAuthData get_auth_data,
 226                         SilcConnAuthCompletion completion,
 227                         void *context);
 228
 229 #endif /* SILCCONNAUTH_H */