lib/silccore/silcauth.h

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