lib/silccore/silcauth.h

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