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 SilcUInt16 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 SilcUInt16 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(const unsigned char *data,
 107  *                                            SilcUInt32 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(const unsigned char *data,
 116                                         SilcUInt32 data_len);
 117
 118 /****f* silccore/SilcAuthAPI/silc_auth_payload_encode
 119  *
 120  * SYNOPSIS
 121  *
 122  *    SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
 123  *                                        const unsigned char *random_data,
 124  *                                        SilcUInt16 random_len,
 125  *                                        const unsigned char *auth_data,
 126  *                                        SilcUInt16 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                                     const unsigned char *random_data,
 137                                     SilcUInt16 random_len,
 138                                     const unsigned char *auth_data,
 139                                     SilcUInt16 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  *                                      SilcUInt32 *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                                   SilcUInt32 *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  *                                                  const void *id,
 190  *                                                  SilcIdType type);
 191  *
 192  * DESCRIPTION
 193  *
 194  *    Generates Authentication Payload with authentication data. This is used
 195  *    to do public key based authentication. This generates the random data
 196  *    and the actual authentication data. Returns NULL on error and the
 197  *    encoded Authentication Payload on success.
 198  *
 199  ***/
 200 SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
 201                                               SilcPrivateKey private_key,
 202                                               SilcHash hash,
 203                                               const void *id, SilcIdType type);
 204
 205 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify
 206  *
 207  * SYNOPSIS
 208  *
 209  *    bool silc_auth_public_key_auth_verify(SilcAuthPayload payload,
 210  *                                          SilcPublicKey public_key,
 211  *                                          SilcHash hash,
 212  *                                          const void *id, SilcIdType type);
 213  *
 214  * DESCRIPTION
 215  *
 216  *    Verifies the authentication data. Returns TRUE if authentication was
 217  *    successful.
 218  *
 219  ***/
 220 bool silc_auth_public_key_auth_verify(SilcAuthPayload payload,
 221                                       SilcPublicKey public_key, SilcHash hash,
 222                                       const void *id, SilcIdType type);
 223
 224 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify_data
 225  *
 226  * SYNOPSIS
 227  *
 228  *    bool silc_auth_public_key_auth_verify_data(const unsigned char *payload,
 229  *                                               SilcUInt32 payload_len,
 230  *                                               SilcPublicKey public_key,
 231  *                                               SilcHash hash,
 232  *                                               const void *id,
 233  *                                               SilcIdType type);
 234  *
 235  * DESCRIPTION
 236  *
 237  *    Same as silc_auth_public_key_auth_verify but the payload has not
 238  *    been parsed yet.  This will parse it.  Returns TRUE if authentication
 239  *    was successful.
 240  *
 241  ***/
 242 bool silc_auth_public_key_auth_verify_data(const unsigned char *payload,
 243                                            SilcUInt32 payload_len,
 244                                            SilcPublicKey public_key,
 245                                            SilcHash hash,
 246                                            const void *id, SilcIdType type);
 247
 248 /****f* silccore/SilcAuthAPI/silc_auth_verify
 249  *
 250  * SYNOPSIS
 251  *
 252  *    bool silc_auth_verify(SilcAuthPayload payload,
 253  *                          SilcAuthMethod auth_method,
 254  *                          const void *auth_data, SilcUInt32 auth_data_len,
 255  *                          SilcHash hash, const void *id, SilcIdType type);
 256  *
 257  * DESCRIPTION
 258  *
 259  *    Verifies the authentication data directly from the Authentication
 260  *    Payload. Supports all authentication methods. If the authentication
 261  *    method is passphrase based then the `auth_data' and `auth_data_len'
 262  *    are the passphrase and its length. If the method is public key
 263  *    authentication then the `auth_data' is the SilcPublicKey and the
 264  *    `auth_data_len' is ignored.
 265  *
 266  ***/
 267 bool silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
 268                       const void *auth_data, SilcUInt32 auth_data_len,
 269                       SilcHash hash, const void *id, SilcIdType type);
 270
 271 /****f* silccore/SilcAuthAPI/silc_auth_verify_data
 272  *
 273  * SYNOPSIS
 274  *
 275  *    bool silc_auth_verify_data(const unsigned char *payload,
 276  *                               SilcUInt32 payload_len,
 277  *                               SilcAuthMethod auth_method,
 278  *                               const void *auth_data,
 279  *                               SilcUInt32 auth_data_len, SilcHash hash,
 280  *                               const void *id, SilcIdType type);
 281  *
 282  * DESCRIPTION
 283  *
 284  *    Same as silc_auth_verify but the payload has not been parsed yet.
 285  *    Verifies the authentication data directly from the Authentication
 286  *    Payload. Supports all authentication methods. If the authentication
 287  *    method is passphrase based then the `auth_data' and `auth_data_len'
 288  *    are the passphrase and its length. If the method is public key
 289  *    authentication then the `auth_data' is the SilcPublicKey and the
 290  *    `auth_data_len' is ignored.
 291  *
 292  ***/
 293 bool silc_auth_verify_data(const unsigned char *payload, SilcUInt32 payload_len,
 294                            SilcAuthMethod auth_method, const void *auth_data,
 295                            SilcUInt32 auth_data_len, SilcHash hash,
 296                            const void *id, SilcIdType type);
 297
 298 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse
 299  *
 300  * SYNOPSIS
 301  *
 302  *    SilcKeyAgreementPayload
 303  *    silc_key_agreement_payload_parse(const unsigned char *payload,
 304  *                                     SilcUInt32 payload_len);
 305  *
 306  * DESCRIPTION
 307  *
 308  *    Parses and returns an allocated Key Agreement payload.
 309  *
 310  ***/
 311 SilcKeyAgreementPayload
 312 silc_key_agreement_payload_parse(const unsigned char *payload,
 313                                  SilcUInt32 payload_len);
 314
 315 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_encode
 316  *
 317  * SYNOPSIS
 318  *
 319  *    SilcBuffer silc_key_agreement_payload_encode(char *hostname,
 320  *                                                 SilcUInt32 port);
 321  *
 322  * DESCRIPTION
 323  *
 324  *    Encodes the Key Agreement protocol and returns the encoded buffer
 325  *
 326  ***/
 327 SilcBuffer silc_key_agreement_payload_encode(const char *hostname,
 328                                              SilcUInt32 port);
 329
 330 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_free
 331  *
 332  * SYNOPSIS
 333  *
 334  *    void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
 335  *
 336  * DESCRIPTION
 337  *
 338  *    Frees the Key Agreement protocol and all data in it.
 339  *
 340  ***/
 341 void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
 342
 343 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_hostname
 344  *
 345  * SYNOPSIS
 346  *
 347  *    char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
 348  *
 349  * DESCRIPTION
 350  *
 351  *    Returns the hostname in the payload. Caller must not free it.
 352  *    The hostname is the host that is able to accept key negotiation
 353  *    using the SILC Key Exchange protocol.
 354  *
 355  ***/
 356 char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
 357
 358 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_port
 359  *
 360  * SYNOPSIS
 361  *
 362  *    SilcUInt32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
 363  *
 364  * DESCRIPTION
 365  *
 366  *    Returns the port in the payload.  The port is the port on the
 367  *    host returned by silc_key_agreement_get_hostname that is running
 368  *    the SILC Key Exchange protocol.
 369  *
 370  ***/
 371 SilcUInt32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
 372
 373 #endif