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.  If
  89  *    neither `passphrase' or `repository' is set but TRUE is returned,
  90  *    authentication is not required.
  91  *
  92  *    If this connection is not configured at all this returns FALSE which
  93  *    will result into authentication failure.  Otherwise TRUE must be
  94  *    returned.
  95  *
  96  ***/
  97 typedef SilcBool (*SilcConnAuthGetAuthData)(SilcConnAuth connauth,
  98                                             SilcConnectionType conn_type,
  99                                             unsigned char **passphrase,
 100                                             SilcUInt32 *passphrase_len,
 101                                             SilcSKR *repository,
 102                                             void *context);
 103
 104 /****f* silcske/SilcConnAuthAPI/SilcConnAuthCompletion
 105  *
 106  * SYNOPSIS
 107  *
 108  *    typedef void (*SilcConnAuthCompletion)(SilcConnAuth connauth,
 109  *                                           SilcBool success,
 110  *                                           void *context);
 111  *
 112  * DESCRIPTION
 113  *
 114  *    Completion callback called to indicated the result of the connection
 115  *    authentication protocol.  If the `success' is FALSE the authentication
 116  *    was a failure.  The authentication protocol is over after this callback
 117  *    is called.
 118  *
 119  ***/
 120 typedef void (*SilcConnAuthCompletion)(SilcConnAuth connauth,
 121                                        SilcBool success,
 122                                        void *context);
 123
 124 /****f* silcske/SilcConnAuthAPI/silc_connauth_alloc
 125  *
 126  * SYNOPSIS
 127  *
 128  *    SilcConnAuth silc_connauth_alloc(SilcSchedule schedule, SilcSKE ske,
 129  *                                     SilcUInt32 timeout_secs);
 130  *
 131  * DESCRIPTION
 132  *
 133  *    Allocates the connection authentication protocol context.  The `ske'
 134  *    is the successfully completed key exchange context.  The `timeout_secs'
 135  *    is the maximum time we are waiting for the protocol to finish before
 136  *    it is timedout.  Returns NULL on error.
 137  *
 138  ***/
 139 SilcConnAuth silc_connauth_alloc(SilcSchedule schedule, SilcSKE ske,
 140                                  SilcUInt32 timeout_secs);
 141
 142 /****f* silcske/SilcConnAuthAPI/silc_connauth_free
 143  *
 144  * SYNOPSIS
 145  *
 146  *    void silc_connauth_free(SilcConnAuth connauth);
 147  *
 148  * DESCRIPTION
 149  *
 150  *    Frees the connection authentication protocol context `connauth'.
 151  *
 152  ***/
 153 void silc_connauth_free(SilcConnAuth connauth);
 154
 155 /****f* silcske/SilcConnAuthAPI/silc_connauth_get_ske
 156  *
 157  * SYNOPSIS
 158  *
 159  *    SilcSKE silc_connauth_get_ske(SilcConnAuth connauth);
 160  *
 161  * DESCRIPTION
 162  *
 163  *    Returns the associated SilcSKE context from the `connauth'.  It is the
 164  *    pointer given as argument to silc_connauth_alloc.
 165  *
 166  ***/
 167 SilcSKE silc_connauth_get_ske(SilcConnAuth connauth);
 168
 169 /****f* silcske/SilcConnAuthAPI/silc_connauth_initiator
 170  *
 171  * SYNOPSIS
 172  *
 173  *    SilcAsyncOperation
 174  *    silc_connauth_initiator(SilcConnAuth connauth,
 175  *                            SilcConnectionType conn_type,
 176  *                            SilcAuthMethod auth_method, void *auth_data,
 177  *                            SilcUInt32 auth_data_len,
 178  *                            SilcConnAuthCompletion completion,
 179  *                            void *context);
 180  *
 181  * DESCRIPTION
 182  *
 183  *    Starts the connection authentication protocol as initiator.  The
 184  *    `conn_type' is the type of connection we are.  The `auth_method' is
 185  *    the authentication method.  If it is SILC_AUTH_PASSWORD the `auth_data'
 186  *    and `auth_data_len' is the passphrase and its length, respectively.
 187  *    If it is SILC_AUTH_PUBLIC_KEY the `auth_data' is the SilcPrivateKey
 188  *    used to produce the digital signature.  The `auth_data_len' is 0.
 189  *    The `completion' with `context' will be called after the protocol
 190  *    has completed.
 191  *
 192  *    This returns SilcAsyncOperation context which can be used to abort
 193  *    the protocol before it is completed.  Returns NULL on error.
 194  *
 195  ***/
 196 SilcAsyncOperation
 197 silc_connauth_initiator(SilcConnAuth connauth,
 198                         SilcConnectionType conn_type,
 199                         SilcAuthMethod auth_method, void *auth_data,
 200                         SilcUInt32 auth_data_len,
 201                         SilcConnAuthCompletion completion,
 202                         void *context);
 203
 204 /****f* silcske/SilcConnAuthAPI/silc_connauth_responder
 205  *
 206  * SYNOPSIS
 207  *
 208  *    SilcAsyncOperation
 209  *    silc_connauth_responder(SilcConnAuth connauth,
 210  *                            SilcConnAuthGetAuthData get_auth_data,
 211  *                            SilcConnAuthCompletion completion,
 212  *                            void *context);
 213  *
 214  * DESCRIPTION
 215  *
 216  *    Starts the connection authentication protocol as responder.  The
 217  *    `get_auth_data' is called to retrieve the authentication data for
 218  *    this connection.  The `completion' will be called after the protocol
 219  *    has completed.
 220  *
 221  *    This returns SilcAsyncOperation context which can be used to abort
 222  *    the protocol before it is completed.  Returns NULL on error.
 223  *
 224  ***/
 225 SilcAsyncOperation
 226 silc_connauth_responder(SilcConnAuth connauth,
 227                         SilcConnAuthGetAuthData get_auth_data,
 228                         SilcConnAuthCompletion completion,
 229                         void *context);
 230
 231 #endif /* SILCCONNAUTH_H */