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(const unsigned char *data,
 101  *                                            SilcUInt32 data_len);
 102  *
 103  * DESCRIPTION
 104  *
 105  *    Parses and returns Authentication Payload.  The `data' and the
 106  *    `data_len' are the raw payload buffer.
 107  *
 108  ***/
 109 SilcAuthPayload silc_auth_payload_parse(const unsigned char *data,
 110                                         SilcUInt32 data_len);
 111
 112 /****f* silccore/SilcAuthAPI/silc_auth_payload_encode
 113  *
 114  * SYNOPSIS
 115  *
 116  *    SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
 117  *                                        const unsigned char *random_data,
 118  *                                        SilcUInt16 random_len,
 119  *                                        const unsigned char *auth_data,
 120  *                                        SilcUInt16 auth_len);
 121  *
 122  * DESCRIPTION
 123  *
 124  *    Encodes authentication payload into buffer and returns it.
 125  *    The `random_data' is provided only if doing public key authentication.
 126  *    The `auth_data' is the actual authentication data.  If the
 127  *    `method' is SILC_AUTH_PASSWORD the passphase in `auth_data' sent as
 128  *    argument SHOULD be UTF-8 encoded, if not library will attempt to
 129  *    encode it.
 130  *
 131  ***/
 132 SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
 133                                     const unsigned char *random_data,
 134                                     SilcUInt16 random_len,
 135                                     const unsigned char *auth_data,
 136                                     SilcUInt16 auth_len);
 137
 138 /****f* silccore/SilcAuthAPI/silc_auth_payload_free
 139  *
 140  * SYNOPSIS
 141  *
 142  *    void silc_auth_payload_free(SilcAuthPayload payload);
 143  *
 144  * DESCRIPTION
 145  *
 146  *    Frees authentication payload and all data in it.
 147  *
 148  ***/
 149 void silc_auth_payload_free(SilcAuthPayload payload);
 150
 151 /****f* silccore/SilcAuthAPI/silc_auth_get_method
 152  *
 153  * SYNOPSIS
 154  *
 155  *    SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
 156  *
 157  * DESCRIPTION
 158  *
 159  *    Get authentication method.
 160  *
 161  ***/
 162 SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
 163
 164 /****f* silccore/SilcAuthAPI/silc_auth_get_public_data
 165  *
 166  * SYNOPSIS
 167  *
 168  *    unsigned char *silc_auth_get_public_data(SilcAuthPayload payload,
 169  *                                             SilcUInt32 *pubdata_len);
 170  *
 171  * DESCRIPTION
 172  *
 173  *    Returns the public data (usually random data) from the payload.
 174  *    Caller must not free the returned data.
 175  *
 176  ***/
 177 unsigned char *silc_auth_get_public_data(SilcAuthPayload payload,
 178                                          SilcUInt32 *pubdata_len);
 179
 180 /****f* silccore/SilcAuthAPI/silc_auth_get_data
 181  *
 182  * SYNOPSIS
 183  *
 184  *    unsigned char *silc_auth_get_data(SilcAuthPayload payload,
 185  *                                      SilcUInt32 *auth_len);
 186  *
 187  * DESCRIPTION
 188  *
 189  *    Get the authentication data. The caller must not free the data.  If
 190  *    the authentication method is passphrase, then the returned string
 191  *    is UTF-8 encoded passphrase.
 192  *
 193  ***/
 194 unsigned char *silc_auth_get_data(SilcAuthPayload payload,
 195                                   SilcUInt32 *auth_len);
 196
 197 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate
 198  *
 199  * SYNOPSIS
 200  *
 201  *    SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
 202  *                                                  SilcPrivateKey private_key,
 203  *                                                  SilcRng rng,
 204  *                                                  SilcHash hash,
 205  *                                                  const void *id,
 206  *                                                  SilcIdType type);
 207  *
 208  * DESCRIPTION
 209  *
 210  *    Generates Authentication Payload with authentication data. This is used
 211  *    to do public key based authentication. This generates the random data
 212  *    and the actual authentication data. Returns NULL on error and the
 213  *    encoded Authentication Payload on success.
 214  *
 215  *    The `private_key' is used to sign the payload.  The `public_key', the
 216  *    and the `id' is encoded in the payload and signed.  If the `rng' is
 217  *    NULL then global RNG is used, if non-NULL then `rng' is used as
 218  *    random number generator.  Also random number is encoded in the
 219  *    payload before signing it with `private_key'.
 220  *
 221  ***/
 222 SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
 223                                               SilcPrivateKey private_key,
 224                                               SilcRng rng, SilcHash hash,
 225                                               const void *id, SilcIdType type);
 226
 227 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate_wpub
 228  *
 229  * SYNOPSIS
 230  *
 231  *    SilcBuffer
 232  *    silc_auth_public_key_auth_generate_wpub(SilcPublicKey public_key,
 233  *                                            SilcPrivateKey private_key,
 234  *                                            const unsigned char *pubdata,
 235  *                                            SilcUInt32 pubdata_len,
 236  *                                            SilcHash hash,
 237  *                                            const void *id,
 238  *                                            SilcIdType type);
 239  *
 240  * DESCRIPTION
 241  *
 242  *    Same as silc_auth_public_key_auth_generate but takes the public data
 243  *    (usually random data) as argument.  This function can be used when
 244  *    the public data must be something else than purely random or its
 245  *    structure mut be set before signing.
 246  *
 247  ***/
 248 SilcBuffer
 249 silc_auth_public_key_auth_generate_wpub(SilcPublicKey public_key,
 250                                         SilcPrivateKey private_key,
 251                                         const unsigned char *pubdata,
 252                                         SilcUInt32 pubdata_len,
 253                                         SilcHash hash,
 254                                         const void *id, SilcIdType type);
 255
 256 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify
 257  *
 258  * SYNOPSIS
 259  *
 260  *    SilcBool silc_auth_public_key_auth_verify(SilcAuthPayload payload,
 261  *                                          SilcPublicKey public_key,
 262  *                                          SilcHash hash,
 263  *                                          const void *id, SilcIdType type);
 264  *
 265  * DESCRIPTION
 266  *
 267  *    Verifies the authentication data. Returns TRUE if authentication was
 268  *    successful.
 269  *
 270  ***/
 271 SilcBool silc_auth_public_key_auth_verify(SilcAuthPayload payload,
 272                                           SilcPublicKey public_key,
 273                                           SilcHash hash,
 274                                           const void *id,
 275                                           SilcIdType type);
 276
 277 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify_data
 278  *
 279  * SYNOPSIS
 280  *
 281  *    SilcBool silc_auth_public_key_auth_verify_data(const unsigned char *payload,
 282  *                                               SilcUInt32 payload_len,
 283  *                                               SilcPublicKey public_key,
 284  *                                               SilcHash hash,
 285  *                                               const void *id,
 286  *                                               SilcIdType type);
 287  *
 288  * DESCRIPTION
 289  *
 290  *    Same as silc_auth_public_key_auth_verify but the payload has not
 291  *    been parsed yet.  This will parse it.  Returns TRUE if authentication
 292  *    was successful.
 293  *
 294  ***/
 295 SilcBool silc_auth_public_key_auth_verify_data(const unsigned char *payload,
 296                                                SilcUInt32 payload_len,
 297                                                SilcPublicKey public_key,
 298                                                SilcHash hash,
 299                                                const void *id,
 300                                                SilcIdType type);
 301
 302 /****f* silccore/SilcAuthAPI/silc_auth_verify
 303  *
 304  * SYNOPSIS
 305  *
 306  *    SilcBool silc_auth_verify(SilcAuthPayload payload,
 307  *                          SilcAuthMethod auth_method,
 308  *                          const void *auth_data, SilcUInt32 auth_data_len,
 309  *                          SilcHash hash, const void *id, SilcIdType type);
 310  *
 311  * DESCRIPTION
 312  *
 313  *    Verifies the authentication data directly from the Authentication
 314  *    Payload. Supports all authentication methods. If the authentication
 315  *    method is passphrase based then the `auth_data' and `auth_data_len'
 316  *    are the passphrase and its length.  The passphrase MUST be UTF-8
 317  *    encoded.  If the method is public key authentication then the
 318  *    `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
 319  *
 320  ***/
 321 SilcBool silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
 322                           const void *auth_data, SilcUInt32 auth_data_len,
 323                           SilcHash hash, const void *id, SilcIdType type);
 324
 325 /****f* silccore/SilcAuthAPI/silc_auth_verify_data
 326  *
 327  * SYNOPSIS
 328  *
 329  *    SilcBool silc_auth_verify_data(const unsigned char *payload,
 330  *                               SilcUInt32 payload_len,
 331  *                               SilcAuthMethod auth_method,
 332  *                               const void *auth_data,
 333  *                               SilcUInt32 auth_data_len, SilcHash hash,
 334  *                               const void *id, SilcIdType type);
 335  *
 336  * DESCRIPTION
 337  *
 338  *    Same as silc_auth_verify but the payload has not been parsed yet.
 339  *    Verifies the authentication data directly from the Authentication
 340  *    Payload. Supports all authentication methods. If the authentication
 341  *    method is passphrase based then the `auth_data' and `auth_data_len'
 342  *    are the passphrase and its length.  The passphrase MUST be UTF-8
 343  *    encoded.  If the method is public key authentication then the
 344  *    `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
 345  *
 346  ***/
 347 SilcBool silc_auth_verify_data(const unsigned char *payload,
 348                                SilcUInt32 payload_len,
 349                                SilcAuthMethod auth_method,
 350                                const void *auth_data,
 351                                SilcUInt32 auth_data_len, SilcHash hash,
 352                                const void *id, SilcIdType type);
 353
 354 /****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload
 355  *
 356  * NAME
 357  *
 358  *    typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
 359  *
 360  * DESCRIPTION
 361  *
 362  *    This context is the actual Key Agreement Payload and is allocated
 363  *    by silc_key_agreement_payload_parse and given as argument usually to all
 364  *    silc_key_agreement_* functions.  It is freed by the function
 365  *    silc_key_agreement_payload_free.
 366  *
 367  ***/
 368 typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
 369
 370 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse
 371  *
 372  * SYNOPSIS
 373  *
 374  *    SilcKeyAgreementPayload
 375  *    silc_key_agreement_payload_parse(const unsigned char *payload,
 376  *                                     SilcUInt32 payload_len);
 377  *
 378  * DESCRIPTION
 379  *
 380  *    Parses and returns an allocated Key Agreement payload.
 381  *
 382  ***/
 383 SilcKeyAgreementPayload
 384 silc_key_agreement_payload_parse(const unsigned char *payload,
 385                                  SilcUInt32 payload_len);
 386
 387 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_encode
 388  *
 389  * SYNOPSIS
 390  *
 391  *    SilcBuffer silc_key_agreement_payload_encode(char *hostname,
 392  *                                                 SilcUInt16 protocol,
 393  *                                                 SilcUInt16 port);
 394  *
 395  * DESCRIPTION
 396  *
 397  *    Encodes the Key Agreement payload and returns the encoded buffer.
 398  *    The `protocol' is 0 for TCP and 1 for UDP.
 399  *
 400  ***/
 401 SilcBuffer silc_key_agreement_payload_encode(const char *hostname,
 402                                              SilcUInt16 protocol,
 403                                              SilcUInt16 port);
 404
 405 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_free
 406  *
 407  * SYNOPSIS
 408  *
 409  *    void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
 410  *
 411  * DESCRIPTION
 412  *
 413  *    Frees the Key Agreement payload and all data in it.
 414  *
 415  ***/
 416 void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
 417
 418 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_hostname
 419  *
 420  * SYNOPSIS
 421  *
 422  *    char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
 423  *
 424  * DESCRIPTION
 425  *
 426  *    Returns the hostname in the payload. Caller must not free it.
 427  *    The hostname is the host that is able to accept key negotiation
 428  *    using the SILC Key Exchange protocol.
 429  *
 430  ***/
 431 char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
 432
 433 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_protocol
 434  *
 435  * SYNOPSIS
 436  *
 437  *    SilcUInt16
 438  *    silc_key_agreement_get_protocol(SilcKeyAgreementPayload payload);
 439  *
 440  * DESCRIPTION
 441  *
 442  *    Returns the protocol in the payload.  The protocol is either TCP (0)
 443  *    or UDP (1).
 444  *
 445  ***/
 446 SilcUInt16 silc_key_agreement_get_protocol(SilcKeyAgreementPayload payload);
 447
 448 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_port
 449  *
 450  * SYNOPSIS
 451  *
 452  *    SilcUInt16 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
 453  *
 454  * DESCRIPTION
 455  *
 456  *    Returns the port in the payload.  The port is the port on the
 457  *    host returned by silc_key_agreement_get_hostname that is running
 458  *    the SILC Key Exchange protocol.
 459  *
 460  ***/
 461 SilcUInt16 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
 462
 463 #endif