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  *                                            const void *id,
 271  *                                            SilcIdType type,
 272  *                                            SilcAuthGenerated generated,
 273  *                                            void *context);
 274  *
 275  * DESCRIPTION
 276  *
 277  *    Same as silc_auth_public_key_auth_generate but takes the public data
 278  *    (usually random data) as argument.  This function can be used when
 279  *    the public data must be something else than purely random or its
 280  *    structure mut be set before signing.
 281  *
 282  *    The `generated' is called to deliver the generated Authentication
 283  *    Payload.
 284  *
 285  ***/
 286 SilcAsyncOperation
 287 silc_auth_public_key_auth_generate_wpub(SilcPublicKey public_key,
 288                                         SilcPrivateKey private_key,
 289                                         const unsigned char *pubdata,
 290                                         SilcUInt32 pubdata_len,
 291                                         SilcHash hash,
 292                                         const void *id, SilcIdType type,
 293                                         SilcAuthGenerated generated,
 294                                         void *context);
 295
 296 /****f* silccore/SilcAuthAPI/SilcAuthResult
 297  *
 298  * SYNOPSIS
 299  *
 300  *    typedef void (*SilcAuthResult)(SilcBool success, void *context);
 301  *
 302  * DESCRIPTION
 303  *
 304  *    Callback of this type is given as argument to silc_auth_verify,
 305  *    silc_auth_verify_data, silc_auth_public_key_auth_verify and
 306  *    silc_auth_public_key_auth_verify_data to deliver the result of
 307  *    the authentication verification.  If `success' is FALSE the
 308  *    authentication failed.
 309  *
 310  ***/
 311 typedef void (*SilcAuthResultCb)(SilcBool success, void *context);
 312
 313 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify
 314  *
 315  * SYNOPSIS
 316  *
 317  *    SilcAsyncOperation
 318  *   silc_auth_public_key_auth_verify(SilcAuthPayload payload,
 319  *                                    SilcPublicKey public_key,
 320  *                                    SilcHash hash,
 321  *                                    const void *id,
 322  *                                    SilcIdType type,
 323  *                                    SilcAuthResult result,
 324  *                                    void *context);
 325  *
 326  * DESCRIPTION
 327  *
 328  *    Verifies the authentication data.  Calls the `result' to deliver
 329  *    the result of the verification.
 330  *
 331  ***/
 332 SilcAsyncOperation
 333 silc_auth_public_key_auth_verify(SilcAuthPayload payload,
 334                                  SilcPublicKey public_key,
 335                                  SilcHash hash,
 336                                  const void *id,
 337                                  SilcIdType type,
 338                                  SilcAuthResultCb result,
 339                                  void *context);
 340
 341 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify_data
 342  *
 343  * SYNOPSIS
 344  *
 345  *    SilcAsyncOperation
 346  *    silc_auth_public_key_auth_verify_data(const unsigned char *payload,
 347  *                                          SilcUInt32 payload_len,
 348  *                                          SilcPublicKey public_key,
 349  *                                          SilcHash hash,
 350  *                                          const void *id,
 351  *                                          SilcIdType type,
 352  *                                          SilcAuthResult result,
 353  *                                          void *context);
 354  *
 355  * DESCRIPTION
 356  *
 357  *    Same as silc_auth_public_key_auth_verify but the payload has not
 358  *    been parsed yet.  This will parse it.  Calls the `result' to deliver
 359  *    the result of the verification.
 360  *
 361  ***/
 362 SilcAsyncOperation
 363 silc_auth_public_key_auth_verify_data(const unsigned char *payload,
 364                                       SilcUInt32 payload_len,
 365                                       SilcPublicKey public_key,
 366                                       SilcHash hash,
 367                                       const void *id,
 368                                       SilcIdType type,
 369                                       SilcAuthResultCb result,
 370                                       void *context);
 371
 372 /****f* silccore/SilcAuthAPI/silc_auth_verify
 373  *
 374  * SYNOPSIS
 375  *
 376  *    SilcAsyncOperation
 377  *    silc_auth_verify(SilcAuthPayload payload,
 378  *                     SilcAuthMethod auth_method,
 379  *                     const void *auth_data,
 380  *                     SilcUInt32 auth_data_len,
 381  *                     SilcHash hash,
 382  *                     const void *id, SilcIdType type,
 383  *                     SilcAuthResult result, void *context);
 384  *
 385  * DESCRIPTION
 386  *
 387  *    Verifies the authentication data directly from the Authentication
 388  *    Payload. Supports all authentication methods. If the authentication
 389  *    method is passphrase based then the `auth_data' and `auth_data_len'
 390  *    are the passphrase and its length.  The passphrase MUST be UTF-8
 391  *    encoded.  If the method is public key authentication then the
 392  *    `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
 393  *    Calls the `result' to deliver the result of the verification.
 394  *
 395  ***/
 396 SilcAsyncOperation
 397 silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
 398                  const void *auth_data, SilcUInt32 auth_data_len,
 399                  SilcHash hash, const void *id, SilcIdType type,
 400                  SilcAuthResultCb result, void *context);
 401
 402 /****f* silccore/SilcAuthAPI/silc_auth_verify_data
 403  *
 404  * SYNOPSIS
 405  *
 406  *    SilcAsyncOperation
 407  *    silc_auth_verify_data(const unsigned char *payload,
 408  *                          SilcUInt32 payload_len,
 409  *                          SilcAuthMethod auth_method,
 410  *                          const void *auth_data,
 411  *                          SilcUInt32 auth_data_len, SilcHash hash,
 412  *                          const void *id, SilcIdType type,
 413  *                          SilcAuthResult result, void *context);
 414  *
 415  * DESCRIPTION
 416  *
 417  *    Same as silc_auth_verify but the payload has not been parsed yet.
 418  *    Verifies the authentication data directly from the Authentication
 419  *    Payload. Supports all authentication methods. If the authentication
 420  *    method is passphrase based then the `auth_data' and `auth_data_len'
 421  *    are the passphrase and its length.  The passphrase MUST be UTF-8
 422  *    encoded.  If the method is public key authentication then the
 423  *    `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
 424  *    Calls the `result' to deliver the result of the verification.
 425  *
 426  ***/
 427 SilcAsyncOperation
 428 silc_auth_verify_data(const unsigned char *payload,
 429                       SilcUInt32 payload_len,
 430                       SilcAuthMethod auth_method,
 431                       const void *auth_data,
 432                       SilcUInt32 auth_data_len, SilcHash hash,
 433                       const void *id, SilcIdType type,
 434                       SilcAuthResultCb result, void *context);
 435
 436 /****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload
 437  *
 438  * NAME
 439  *
 440  *    typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
 441  *
 442  * DESCRIPTION
 443  *
 444  *    This context is the actual Key Agreement Payload and is allocated
 445  *    by silc_key_agreement_payload_parse and given as argument usually to all
 446  *    silc_key_agreement_* functions.  It is freed by the function
 447  *    silc_key_agreement_payload_free.
 448  *
 449  ***/
 450 typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
 451
 452 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse
 453  *
 454  * SYNOPSIS
 455  *
 456  *    SilcKeyAgreementPayload
 457  *    silc_key_agreement_payload_parse(const unsigned char *payload,
 458  *                                     SilcUInt32 payload_len);
 459  *
 460  * DESCRIPTION
 461  *
 462  *    Parses and returns an allocated Key Agreement payload.
 463  *
 464  ***/
 465 SilcKeyAgreementPayload
 466 silc_key_agreement_payload_parse(const unsigned char *payload,
 467                                  SilcUInt32 payload_len);
 468
 469 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_encode
 470  *
 471  * SYNOPSIS
 472  *
 473  *    SilcBuffer silc_key_agreement_payload_encode(char *hostname,
 474  *                                                 SilcUInt16 protocol,
 475  *                                                 SilcUInt16 port);
 476  *
 477  * DESCRIPTION
 478  *
 479  *    Encodes the Key Agreement payload and returns the encoded buffer.
 480  *    The `protocol' is 0 for TCP and 1 for UDP.
 481  *
 482  ***/
 483 SilcBuffer silc_key_agreement_payload_encode(const char *hostname,
 484                                              SilcUInt16 protocol,
 485                                              SilcUInt16 port);
 486
 487 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_free
 488  *
 489  * SYNOPSIS
 490  *
 491  *    void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
 492  *
 493  * DESCRIPTION
 494  *
 495  *    Frees the Key Agreement payload and all data in it.
 496  *
 497  ***/
 498 void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
 499
 500 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_hostname
 501  *
 502  * SYNOPSIS
 503  *
 504  *    char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
 505  *
 506  * DESCRIPTION
 507  *
 508  *    Returns the hostname in the payload. Caller must not free it.
 509  *    The hostname is the host that is able to accept key negotiation
 510  *    using the SILC Key Exchange protocol.
 511  *
 512  ***/
 513 char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
 514
 515 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_protocol
 516  *
 517  * SYNOPSIS
 518  *
 519  *    SilcUInt16
 520  *    silc_key_agreement_get_protocol(SilcKeyAgreementPayload payload);
 521  *
 522  * DESCRIPTION
 523  *
 524  *    Returns the protocol in the payload.  The protocol is either TCP (0)
 525  *    or UDP (1).
 526  *
 527  ***/
 528 SilcUInt16 silc_key_agreement_get_protocol(SilcKeyAgreementPayload payload);
 529
 530 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_port
 531  *
 532  * SYNOPSIS
 533  *
 534  *    SilcUInt16 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
 535  *
 536  * DESCRIPTION
 537  *
 538  *    Returns the port in the payload.  The port is the port on the
 539  *    host returned by silc_key_agreement_get_hostname that is running
 540  *    the SILC Key Exchange protocol.
 541  *
 542  ***/
 543 SilcUInt16 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
 544
 545 #endif