lib/silccore/silcauth.h

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