lib/silccore/silcauth.h

   1 /*
   2
   3   silcauth.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2001 - 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* silccore/SILC Authentication Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * Implementations of the SILC Authentication Payload and authentication
  25  * routines.  The SILC Authentication Payload is used to deliver
  26  * authentication data usually from client to server in purpose of
  27  * gaining access to some service.  The Payload and the authentication
  28  * routines supports both passphrase and public key (signature) based
  29  * authentication.
  30  *
  31  * This interface defines also the SILC Key Agreement Payload that is
  32  * used by client to agree on key material usually with another client
  33  * in the network.
  34  *
  35  ***/
  36
  37 #ifndef SILCAUTH_H
  38 #define SILCAUTH_H
  39
  40 /****d* silccore/SilcAuthAPI/SilcAuthMethod
  41  *
  42  * NAME
  43  *
  44  *    typedef SilcUInt16 SilcAuthMethod;
  45  *
  46  * DESCRIPTION
  47  *
  48  *    Authentication method type definition, the authentication methods
  49  *    and the authentication status'.  The status defines are used by
  50  *    all authentication protocols in the SILC.
  51  *
  52  * SOURCE
  53  */
  54 typedef SilcUInt16 SilcAuthMethod;
  55
  56 #define SILC_AUTH_NONE        0            /* No authentication */
  57 #define SILC_AUTH_PASSWORD    1            /* Passphrase authentication */
  58 #define SILC_AUTH_PUBLIC_KEY  2            /* Public key authentication */
  59
  60 /****d* silccore/SilcAuthAPI/SilcAuthResult
  61  *
  62  * NAME
  63  *
  64  *    typedef SilcUInt32 SilcAuthResult;
  65  *
  66  * DESCRIPTION
  67  *
  68  *    Authentication protocol status.  Used by all authentication protocols
  69  *    in SILC.
  70  *
  71  * SOURCE
  72  */
  73 typedef SilcUInt32 SilcAuthResult;
  74
  75 #define SILC_AUTH_OK          0              /* Authentication successful */
  76 #define SILC_AUTH_FAILED      1              /* Authentication failed */
  77 /***/
  78
  79 /****s* silccore/SilcAuthAPI/SilcAuthPayload
  80  *
  81  * NAME
  82  *
  83  *    typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
  84  *
  85  *
  86  * DESCRIPTION
  87  *
  88  *    This context is the actual Authentication Payload and is allocated
  89  *    by silc_auth_payload_parse and given as argument usually to all
  90  *    silc_auth_payload_* functions.  It is freed by silc_auth_payload_free
  91  *    function.
  92  *
  93  ***/
  94 typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
  95
  96 /****f* silccore/SilcAuthAPI/silc_auth_payload_parse
  97  *
  98  * SYNOPSIS
  99  *
 100  *    SilcAuthPayload silc_auth_payload_parse(SilcStack stack,
 101  *                                            const unsigned char *data,
 102  *                                            SilcUInt32 data_len);
 103  *
 104  * DESCRIPTION
 105  *
 106  *    Parses and returns Authentication Payload.  The `data' and the
 107  *    `data_len' are the raw payload buffer.  If `stack' is non-NULL the
 108  *    memory is allcoated from `stack'.
 109  *
 110  ***/
 111 SilcAuthPayload silc_auth_payload_parse(SilcStack stack,
 112                                         const unsigned char *data,
 113                                         SilcUInt32 data_len);
 114
 115 /****f* silccore/SilcAuthAPI/silc_auth_payload_encode
 116  *
 117  * SYNOPSIS
 118  *
 119  *    SilcBuffer silc_auth_payload_encode(SilcStack stack,
 120  *                                        SilcAuthMethod method,
 121  *                                        const unsigned char *random_data,
 122  *                                        SilcUInt16 random_len,
 123  *                                        const unsigned char *auth_data,
 124  *                                        SilcUInt16 auth_len);
 125  *
 126  * DESCRIPTION
 127  *
 128  *    Encodes authentication payload into buffer and returns it.
 129  *    The `random_data' is provided only if doing public key authentication.
 130  *    The `auth_data' is the actual authentication data.  If the
 131  *    `method' is SILC_AUTH_PASSWORD the passphase in `auth_data' sent as
 132  *    argument SHOULD be UTF-8 encoded, if not library will attempt to
 133  *    encode it.
 134  *
 135  *    If `stack' is non-NULL the returned buffer is allocated from `stack'.
 136  *    This call consumes the `stack' so caller should push the stack before
 137  *    calling this function and then later pop it.
 138  *
 139  ***/
 140 SilcBuffer silc_auth_payload_encode(SilcStack stack,
 141                                     SilcAuthMethod method,
 142                                     const unsigned char *random_data,
 143                                     SilcUInt16 random_len,
 144                                     const unsigned char *auth_data,
 145                                     SilcUInt16 auth_len);
 146
 147 /****f* silccore/SilcAuthAPI/silc_auth_payload_free
 148  *
 149  * SYNOPSIS
 150  *
 151  *    void silc_auth_payload_free(SilcAuthPayload payload);
 152  *
 153  * DESCRIPTION
 154  *
 155  *    Frees authentication payload and all data in it.
 156  *
 157  ***/
 158 void silc_auth_payload_free(SilcAuthPayload payload);
 159
 160 /****f* silccore/SilcAuthAPI/silc_auth_get_method
 161  *
 162  * SYNOPSIS
 163  *
 164  *    SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
 165  *
 166  * DESCRIPTION
 167  *
 168  *    Get authentication method.
 169  *
 170  ***/
 171 SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
 172
 173 /****f* silccore/SilcAuthAPI/silc_auth_get_public_data
 174  *
 175  * SYNOPSIS
 176  *
 177  *    unsigned char *silc_auth_get_public_data(SilcAuthPayload payload,
 178  *                                             SilcUInt32 *pubdata_len);
 179  *
 180  * DESCRIPTION
 181  *
 182  *    Returns the public data (usually random data) from the payload.
 183  *    Caller must not free the returned data.
 184  *
 185  ***/
 186 unsigned char *silc_auth_get_public_data(SilcAuthPayload payload,
 187                                          SilcUInt32 *pubdata_len);
 188
 189 /****f* silccore/SilcAuthAPI/silc_auth_get_data
 190  *
 191  * SYNOPSIS
 192  *
 193  *    unsigned char *silc_auth_get_data(SilcAuthPayload payload,
 194  *                                      SilcUInt32 *auth_len);
 195  *
 196  * DESCRIPTION
 197  *
 198  *    Get the authentication data. The caller must not free the data.  If
 199  *    the authentication method is passphrase, then the returned string
 200  *    is UTF-8 encoded passphrase.
 201  *
 202  ***/
 203 unsigned char *silc_auth_get_data(SilcAuthPayload payload,
 204                                   SilcUInt32 *auth_len);
 205
 206 /****f* silccore/SilcAuthAPI/SilcAuthGenerated
 207  *
 208  * SYNOPSIS
 209  *
 210  *    typedef void (*SilcAuthGenerated)(const SilcBuffer data, void *context);
 211  *
 212  * DESCRIPTION
 213  *
 214  *    Callback of this type is given as argument to
 215  *    silc_auth_public_key_auth_generate and
 216  *    silc_auth_public_key_auth_generate_wpub to deliver the generated
 217  *    Authentication Payload.  If `data' is NULL the generating failed.
 218  *
 219  ***/
 220 typedef void (*SilcAuthGenerated)(const SilcBuffer data, void *context);
 221
 222 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate
 223  *
 224  * SYNOPSIS
 225  *
 226  *    SilcAsyncOperation
 227  *    silc_auth_public_key_auth_generate(SilcPublicKey public_key,
 228  *                                       SilcPrivateKey private_key,
 229  *                                       SilcRng rng,
 230  *                                       SilcHash hash,
 231  *                                       const void *id,
 232  *                                       SilcIdType type,
 233  *                                       SilcAuthGenerated generated,
 234  *                                       void *context);
 235  *
 236  * DESCRIPTION
 237  *
 238  *    Generates Authentication Payload with authentication data. This is used
 239  *    to do public key based authentication. This generates the random data
 240  *    and the actual authentication data.
 241  *
 242  *    The `private_key' is used to sign the payload.  The `public_key', the
 243  *    and the `id' is encoded in the payload and signed.  If the `rng' is
 244  *    NULL then global RNG is used, if non-NULL then `rng' is used as
 245  *    random number generator.  Also random number is encoded in the
 246  *    payload before signing it with `private_key'.
 247  *
 248  *    The `generated' is called to deliver the generated Authentication
 249  *    Payload.
 250  *
 251  ***/
 252 SilcAsyncOperation
 253 silc_auth_public_key_auth_generate(SilcPublicKey public_key,
 254                                    SilcPrivateKey private_key,
 255                                    SilcRng rng, SilcHash hash,
 256                                    const void *id, SilcIdType type,
 257                                    SilcAuthGenerated generated,
 258                                    void *context);
 259
 260 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate_wpub
 261  *
 262  * SYNOPSIS
 263  *
 264  *    SilcAsyncOperation
 265  *    silc_auth_public_key_auth_generate_wpub(SilcPublicKey public_key,
 266  *                                            SilcPrivateKey private_key,
 267  *                                            const unsigned char *pubdata,
 268  *                                            SilcUInt32 pubdata_len,
 269  *                                            SilcHash hash,
 270  *                                            SilcRng rng,
 271  *                                            const void *id,
 272  *                                            SilcIdType type,
 273  *                                            SilcAuthGenerated generated,
 274  *                                            void *context);
 275  *
 276  * DESCRIPTION
 277  *
 278  *    Same as silc_auth_public_key_auth_generate but takes the public data
 279  *    (usually random data) as argument.  This function can be used when
 280  *    the public data must be something else than purely random or its
 281  *    structure mut be set before signing.
 282  *
 283  *    The `generated' is called to deliver the generated Authentication
 284  *    Payload.
 285  *
 286  ***/
 287 SilcAsyncOperation
 288 silc_auth_public_key_auth_generate_wpub(SilcPublicKey public_key,
 289                                         SilcPrivateKey private_key,
 290                                         const unsigned char *pubdata,
 291                                         SilcUInt32 pubdata_len,
 292                                         SilcHash hash,
 293                                         SilcRng rng,
 294                                         const void *id, SilcIdType type,
 295                                         SilcAuthGenerated generated,
 296                                         void *context);
 297
 298 /****f* silccore/SilcAuthAPI/SilcAuthResult
 299  *
 300  * SYNOPSIS
 301  *
 302  *    typedef void (*SilcAuthResult)(SilcBool success, void *context);
 303  *
 304  * DESCRIPTION
 305  *
 306  *    Callback of this type is given as argument to silc_auth_verify,
 307  *    silc_auth_verify_data, silc_auth_public_key_auth_verify and
 308  *    silc_auth_public_key_auth_verify_data to deliver the result of
 309  *    the authentication verification.  If `success' is FALSE the
 310  *    authentication failed.
 311  *
 312  ***/
 313 typedef void (*SilcAuthResultCb)(SilcBool success, void *context);
 314
 315 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify
 316  *
 317  * SYNOPSIS
 318  *
 319  *    SilcAsyncOperation
 320  *   silc_auth_public_key_auth_verify(SilcAuthPayload payload,
 321  *                                    SilcPublicKey public_key,
 322  *                                    SilcHash hash,
 323  *                                    const void *id,
 324  *                                    SilcIdType type,
 325  *                                    SilcAuthResult result,
 326  *                                    void *context);
 327  *
 328  * DESCRIPTION
 329  *
 330  *    Verifies the authentication data.  Calls the `result' to deliver
 331  *    the result of the verification.
 332  *
 333  ***/
 334 SilcAsyncOperation
 335 silc_auth_public_key_auth_verify(SilcAuthPayload payload,
 336                                  SilcPublicKey public_key,
 337                                  SilcHash hash,
 338                                  const void *id,
 339                                  SilcIdType type,
 340                                  SilcAuthResultCb result,
 341                                  void *context);
 342
 343 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify_data
 344  *
 345  * SYNOPSIS
 346  *
 347  *    SilcAsyncOperation
 348  *    silc_auth_public_key_auth_verify_data(const unsigned char *payload,
 349  *                                          SilcUInt32 payload_len,
 350  *                                          SilcPublicKey public_key,
 351  *                                          SilcHash hash,
 352  *                                          const void *id,
 353  *                                          SilcIdType type,
 354  *                                          SilcAuthResult result,
 355  *                                          void *context);
 356  *
 357  * DESCRIPTION
 358  *
 359  *    Same as silc_auth_public_key_auth_verify but the payload has not
 360  *    been parsed yet.  This will parse it.  Calls the `result' to deliver
 361  *    the result of the verification.
 362  *
 363  ***/
 364 SilcAsyncOperation
 365 silc_auth_public_key_auth_verify_data(const unsigned char *payload,
 366                                       SilcUInt32 payload_len,
 367                                       SilcPublicKey public_key,
 368                                       SilcHash hash,
 369                                       const void *id,
 370                                       SilcIdType type,
 371                                       SilcAuthResultCb result,
 372                                       void *context);
 373
 374 /****f* silccore/SilcAuthAPI/silc_auth_verify
 375  *
 376  * SYNOPSIS
 377  *
 378  *    SilcAsyncOperation
 379  *    silc_auth_verify(SilcAuthPayload payload,
 380  *                     SilcAuthMethod auth_method,
 381  *                     const void *auth_data,
 382  *                     SilcUInt32 auth_data_len,
 383  *                     SilcHash hash,
 384  *                     const void *id, SilcIdType type,
 385  *                     SilcAuthResult result, void *context);
 386  *
 387  * DESCRIPTION
 388  *
 389  *    Verifies the authentication data directly from the Authentication
 390  *    Payload. Supports all authentication methods. If the authentication
 391  *    method is passphrase based then the `auth_data' and `auth_data_len'
 392  *    are the passphrase and its length.  The passphrase MUST be UTF-8
 393  *    encoded.  If the method is public key authentication then the
 394  *    `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
 395  *    Calls the `result' to deliver the result of the verification.
 396  *
 397  ***/
 398 SilcAsyncOperation
 399 silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
 400                  const void *auth_data, SilcUInt32 auth_data_len,
 401                  SilcHash hash, const void *id, SilcIdType type,
 402                  SilcAuthResultCb result, void *context);
 403
 404 /****f* silccore/SilcAuthAPI/silc_auth_verify_data
 405  *
 406  * SYNOPSIS
 407  *
 408  *    SilcAsyncOperation
 409  *    silc_auth_verify_data(const unsigned char *payload,
 410  *                          SilcUInt32 payload_len,
 411  *                          SilcAuthMethod auth_method,
 412  *                          const void *auth_data,
 413  *                          SilcUInt32 auth_data_len, SilcHash hash,
 414  *                          const void *id, SilcIdType type,
 415  *                          SilcAuthResult result, void *context);
 416  *
 417  * DESCRIPTION
 418  *
 419  *    Same as silc_auth_verify but the payload has not been parsed yet.
 420  *    Verifies the authentication data directly from the Authentication
 421  *    Payload. Supports all authentication methods. If the authentication
 422  *    method is passphrase based then the `auth_data' and `auth_data_len'
 423  *    are the passphrase and its length.  The passphrase MUST be UTF-8
 424  *    encoded.  If the method is public key authentication then the
 425  *    `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
 426  *    Calls the `result' to deliver the result of the verification.
 427  *
 428  ***/
 429 SilcAsyncOperation
 430 silc_auth_verify_data(const unsigned char *payload,
 431                       SilcUInt32 payload_len,
 432                       SilcAuthMethod auth_method,
 433                       const void *auth_data,
 434                       SilcUInt32 auth_data_len, SilcHash hash,
 435                       const void *id, SilcIdType type,
 436                       SilcAuthResultCb result, void *context);
 437
 438 /****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload
 439  *
 440  * NAME
 441  *
 442  *    typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
 443  *
 444  * DESCRIPTION
 445  *
 446  *    This context is the actual Key Agreement Payload and is allocated
 447  *    by silc_key_agreement_payload_parse and given as argument usually to all
 448  *    silc_key_agreement_* functions.  It is freed by the function
 449  *    silc_key_agreement_payload_free.
 450  *
 451  ***/
 452 typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
 453
 454 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse
 455  *
 456  * SYNOPSIS
 457  *
 458  *    SilcKeyAgreementPayload
 459  *    silc_key_agreement_payload_parse(const unsigned char *payload,
 460  *                                     SilcUInt32 payload_len);
 461  *
 462  * DESCRIPTION
 463  *
 464  *    Parses and returns an allocated Key Agreement payload.
 465  *
 466  ***/
 467 SilcKeyAgreementPayload
 468 silc_key_agreement_payload_parse(const unsigned char *payload,
 469                                  SilcUInt32 payload_len);
 470
 471 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_encode
 472  *
 473  * SYNOPSIS
 474  *
 475  *    SilcBuffer silc_key_agreement_payload_encode(char *hostname,
 476  *                                                 SilcUInt16 protocol,
 477  *                                                 SilcUInt16 port);
 478  *
 479  * DESCRIPTION
 480  *
 481  *    Encodes the Key Agreement payload and returns the encoded buffer.
 482  *    The `protocol' is 0 for TCP and 1 for UDP.
 483  *
 484  ***/
 485 SilcBuffer silc_key_agreement_payload_encode(const char *hostname,
 486                                              SilcUInt16 protocol,
 487                                              SilcUInt16 port);
 488
 489 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_free
 490  *
 491  * SYNOPSIS
 492  *
 493  *    void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
 494  *
 495  * DESCRIPTION
 496  *
 497  *    Frees the Key Agreement payload and all data in it.
 498  *
 499  ***/
 500 void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
 501
 502 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_hostname
 503  *
 504  * SYNOPSIS
 505  *
 506  *    char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
 507  *
 508  * DESCRIPTION
 509  *
 510  *    Returns the hostname in the payload. Caller must not free it.
 511  *    The hostname is the host that is able to accept key negotiation
 512  *    using the SILC Key Exchange protocol.
 513  *
 514  ***/
 515 char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
 516
 517 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_protocol
 518  *
 519  * SYNOPSIS
 520  *
 521  *    SilcUInt16
 522  *    silc_key_agreement_get_protocol(SilcKeyAgreementPayload payload);
 523  *
 524  * DESCRIPTION
 525  *
 526  *    Returns the protocol in the payload.  The protocol is either TCP (0)
 527  *    or UDP (1).
 528  *
 529  ***/
 530 SilcUInt16 silc_key_agreement_get_protocol(SilcKeyAgreementPayload payload);
 531
 532 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_port
 533  *
 534  * SYNOPSIS
 535  *
 536  *    SilcUInt16 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
 537  *
 538  * DESCRIPTION
 539  *
 540  *    Returns the port in the payload.  The port is the port on the
 541  *    host returned by silc_key_agreement_get_hostname that is running
 542  *    the SILC Key Exchange protocol.
 543  *
 544  ***/
 545 SilcUInt16 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
 546
 547 #endif