lib/silccore/silcauth.h

   1 /*
   2
   3   silcauth.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 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 /****h* silccore/SilcAuthAPI
  22  *
  23  * DESCRIPTION
  24  *
  25  * Implementations of the Silc Authentication Payload and authentication
  26  * routines.  The SILC Authentication Payload is used to deliver
  27  * authentication data usually from client to server in purpose of
  28  * gaining access to some service.  The Payload and the authentication
  29  * routines supports both passphrase and public key (signature) based
  30  * authentication.
  31  *
  32  * This interface defines also the SILC Key Agreement Payload that is
  33  * used by client to agree on key material usually with another client
  34  * in the network.
  35  *
  36  ***/
  37
  38 #ifndef SILCAUTH_H
  39 #define SILCAUTH_H
  40
  41 /****s* silccore/SilcAuthAPI/SilcAuthPayload
  42  *
  43  * NAME
  44  *
  45  *    typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
  46  *
  47  *
  48  * DESCRIPTION
  49  *
  50  *    This context is the actual Authentication Payload and is allocated
  51  *    by silc_auth_payload_parse and given as argument usually to all
  52  *    silc_auth_payload_* functions.  It is freed by silc_auth_payload_free
  53  *    function.
  54  *
  55  ***/
  56 typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
  57
  58 /****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload
  59  *
  60  * NAME
  61  *
  62  *    typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
  63  *
  64  * DESCRIPTION
  65  *
  66  *    This context is the actual Key Agreement Payload and is allocated
  67  *    by silc_key_agreement_payload_parse and given as argument usually to all
  68  *    silc_key_agreement_* functions.  It is freed by the function
  69  *    silc_key_agreement_payload_free.
  70  *
  71  ***/
  72 typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
  73
  74 /****d* silccore/SilcAuthAPI/SilcAuthMethod
  75  *
  76  * NAME
  77  *
  78  *    typedef uint16 SilcAuthMethod;
  79  *
  80  * DESCRIPTION
  81  *
  82  *    Authentication method type definition, the authentication methods
  83  *    and the authentication status'.  The status defines are used by
  84  *    all authentication protocols in the SILC.
  85  *
  86  * SOURCE
  87  */
  88 typedef uint16 SilcAuthMethod;
  89
  90 #define SILC_AUTH_NONE        0            /* No authentication */
  91 #define SILC_AUTH_PASSWORD    1            /* Passphrase authentication */
  92 #define SILC_AUTH_PUBLIC_KEY  2            /* Public key authentication */
  93
  94 /* Authentication protocol status message (used by all authentication
  95    protocols in the SILC). */
  96 #define SILC_AUTH_OK          0
  97 #define SILC_AUTH_FAILED      1
  98 /***/
  99
 100 /* Prototypes */
 101
 102 /****f* silccore/SilcAuthAPI/silc_auth_payload_parse
 103  *
 104  * SYNOPSIS
 105  *
 106  *    SilcAuthPayload silc_auth_payload_parse(unsigned char *data,
 107  *                                            uint32 data_len);
 108  *
 109  * DESCRIPTION
 110  *
 111  *    Parses and returns Authentication Payload.  The `data' and the
 112  *    `data_len' are the raw payload buffer.
 113  *
 114  ***/
 115 SilcAuthPayload silc_auth_payload_parse(unsigned char *data,
 116                                         uint32 data_len);
 117
 118 /****f* silccore/SilcAuthAPI/silc_auth_payload_encode
 119  *
 120  * SYNOPSIS
 121  *
 122  *    SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
 123  *                                        unsigned char *random_data,
 124  *                                        uint16 random_len,
 125  *                                        unsigned char *auth_data,
 126  *                                        uint16 auth_len);
 127  *
 128  * DESCRIPTION
 129  *
 130  *    Encodes authentication payload into buffer and returns it.
 131  *    The `random_data' is provided only if doing public key authentication.
 132  *    The `auth_data' is the actual authentication data.
 133  *
 134  ***/
 135 SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
 136                                     unsigned char *random_data,
 137                                     uint16 random_len,
 138                                     unsigned char *auth_data,
 139                                     uint16 auth_len);
 140
 141 /****f* silccore/SilcAuthAPI/silc_auth_payload_free
 142  *
 143  * SYNOPSIS
 144  *
 145  *    void silc_auth_payload_free(SilcAuthPayload payload);
 146  *
 147  * DESCRIPTION
 148  *
 149  *    Frees authentication payload and all data in it.
 150  *
 151  ***/
 152 void silc_auth_payload_free(SilcAuthPayload payload);
 153
 154 /****f* silccore/SilcAuthAPI/silc_auth_get_method
 155  *
 156  * SYNOPSIS
 157  *
 158  *    SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
 159  *
 160  * DESCRIPTION
 161  *
 162  *    Get authentication method.
 163  *
 164  ***/
 165 SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
 166
 167 /****f* silccore/SilcAuthAPI/silc_auth_get_data
 168  *
 169  * SYNOPSIS
 170  *
 171  *    unsigned char *silc_auth_get_data(SilcAuthPayload payload,
 172  *                                      uint32 *auth_len);
 173  *
 174  * DESCRIPTION
 175  *
 176  *    Get the authentication data. The caller must not free the data.
 177  *
 178  ***/
 179 unsigned char *silc_auth_get_data(SilcAuthPayload payload,
 180                                   uint32 *auth_len);
 181
 182 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate
 183  *
 184  * SYNOPSIS
 185  *
 186  *    SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
 187  *                                                  SilcPrivateKey private_key,
 188  *                                                  SilcHash hash,
 189  *                                                  void *id, SilcIdType type);
 190  *
 191  * DESCRIPTION
 192  *
 193  *    Generates Authentication Payload with authentication data. This is used
 194  *    to do public key based authentication. This generates the random data
 195  *    and the actual authentication data. Returns NULL on error and the
 196  *    encoded Authentication Payload on success.
 197  *
 198  ***/
 199 SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
 200                                               SilcPrivateKey private_key,
 201                                               SilcHash hash,
 202                                               void *id, SilcIdType type);
 203
 204 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify
 205  *
 206  * SYNOPSIS
 207  *
 208  *    int silc_auth_public_key_auth_verify(SilcAuthPayload payload,
 209  *                                         SilcPublicKey public_key,
 210  *                                         SilcHash hash,
 211  *                                         void *id, SilcIdType type);
 212  *
 213  * DESCRIPTION
 214  *
 215  *    Verifies the authentication data. Returns TRUE if authentication was
 216  *    successful.
 217  *
 218  ***/
 219 int silc_auth_public_key_auth_verify(SilcAuthPayload payload,
 220                                      SilcPublicKey public_key, SilcHash hash,
 221                                      void *id, SilcIdType type);
 222
 223 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify_data
 224  *
 225  * SYNOPSIS
 226  *
 227  *    int silc_auth_public_key_auth_verify_data(SilcBuffer payload,
 228  *                                              SilcPublicKey public_key,
 229  *                                              SilcHash hash,
 230  *                                              void *id, SilcIdType type);
 231  *
 232  * DESCRIPTION
 233  *
 234  *    Same as silc_auth_public_key_auth_verify but the payload has not
 235  *    been parsed yet.  This will parse it.  Returns TRUE if authentication
 236  *    was successful.
 237  *
 238  ***/
 239 int silc_auth_public_key_auth_verify_data(SilcBuffer payload,
 240                                           SilcPublicKey public_key,
 241                                           SilcHash hash,
 242                                           void *id, SilcIdType type);
 243
 244 /****f* silccore/SilcAuthAPI/silc_auth_verify
 245  *
 246  * SYNOPSIS
 247  *
 248  *    int silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
 249  *                         void *auth_data, uint32 auth_data_len,
 250  *                         SilcHash hash, void *id, SilcIdType type);
 251  *
 252  * DESCRIPTION
 253  *
 254  *    Verifies the authentication data directly from the Authentication
 255  *    Payload. Supports all authentication methods. If the authentication
 256  *    method is passphrase based then the `auth_data' and `auth_data_len'
 257  *    are the passphrase and its length. If the method is public key
 258  *    authentication then the `auth_data' is the SilcPublicKey and the
 259  *    `auth_data_len' is ignored.
 260  *
 261  ***/
 262 int silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
 263                      void *auth_data, uint32 auth_data_len,
 264                      SilcHash hash, void *id, SilcIdType type);
 265
 266 /****f* silccore/SilcAuthAPI/silc_auth_verify_data
 267  *
 268  * SYNOPSIS
 269  *
 270  *    int silc_auth_verify_data(unsigned char *payload, uint32 payload_len,
 271  *                              SilcAuthMethod auth_method, void *auth_data,
 272  *                              uint32 auth_data_len, SilcHash hash,
 273  *                              void *id, SilcIdType type);
 274  *
 275  * DESCRIPTION
 276  *
 277  *    Same as silc_auth_verify but the payload has not been parsed yet.
 278  *    Verifies the authentication data directly from the Authentication
 279  *    Payload. Supports all authentication methods. If the authentication
 280  *    method is passphrase based then the `auth_data' and `auth_data_len'
 281  *    are the passphrase and its length. If the method is public key
 282  *    authentication then the `auth_data' is the SilcPublicKey and the
 283  *    `auth_data_len' is ignored.
 284  *
 285  ***/
 286 int silc_auth_verify_data(unsigned char *payload, uint32 payload_len,
 287                           SilcAuthMethod auth_method, void *auth_data,
 288                           uint32 auth_data_len, SilcHash hash,
 289                           void *id, SilcIdType type);
 290
 291 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse
 292  *
 293  * SYNOPSIS
 294  *
 295  *    SilcKeyAgreementPayload
 296  *    silc_key_agreement_payload_parse(SilcBuffer buffer);
 297  *
 298  * DESCRIPTION
 299  *
 300  *    Parses and returns an allocated Key Agreement payload.
 301  *
 302  ***/
 303 SilcKeyAgreementPayload silc_key_agreement_payload_parse(SilcBuffer buffer);
 304
 305 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_encode
 306  *
 307  * SYNOPSIS
 308  *
 309  *    SilcBuffer silc_key_agreement_payload_encode(char *hostname,
 310  *                                                 uint32 port);
 311  *
 312  * DESCRIPTION
 313  *
 314  *    Encodes the Key Agreement protocol and returns the encoded buffer
 315  *
 316  ***/
 317 SilcBuffer silc_key_agreement_payload_encode(char *hostname,
 318                                              uint32 port);
 319
 320 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_free
 321  *
 322  * SYNOPSIS
 323  *
 324  *    void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
 325  *
 326  * DESCRIPTION
 327  *
 328  *    Frees the Key Agreement protocol and all data in it.
 329  *
 330  ***/
 331 void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
 332
 333 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_hostname
 334  *
 335  * SYNOPSIS
 336  *
 337  *    char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
 338  *
 339  * DESCRIPTION
 340  *
 341  *    Returns the hostname in the payload. Caller must not free it.
 342  *    The hostname is the host that is able to accept key negotiation
 343  *    using the SILC Key Exchange protocol.
 344  *
 345  ***/
 346 char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
 347
 348 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_port
 349  *
 350  * SYNOPSIS
 351  *
 352  *    uint32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
 353  *
 354  * DESCRIPTION
 355  *
 356  *    Returns the port in the payload.  The port is the port on the
 357  *    host returned by silc_key_agreement_get_hostname that is running
 358  *    the SILC Key Exchange protocol.
 359  *
 360  ***/
 361 uint32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
 362
 363 #endif