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