lib/silccore/silcauth.h

   1 /*
   2
   3   silcauth.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2001 - 2003 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  *    bool 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 bool silc_auth_public_key_auth_verify(SilcAuthPayload payload,
 259                                       SilcPublicKey public_key, SilcHash hash,
 260                                       const void *id, SilcIdType type);
 261
 262 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify_data
 263  *
 264  * SYNOPSIS
 265  *
 266  *    bool silc_auth_public_key_auth_verify_data(const unsigned char *payload,
 267  *                                               SilcUInt32 payload_len,
 268  *                                               SilcPublicKey public_key,
 269  *                                               SilcHash hash,
 270  *                                               const void *id,
 271  *                                               SilcIdType type);
 272  *
 273  * DESCRIPTION
 274  *
 275  *    Same as silc_auth_public_key_auth_verify but the payload has not
 276  *    been parsed yet.  This will parse it.  Returns TRUE if authentication
 277  *    was successful.
 278  *
 279  ***/
 280 bool silc_auth_public_key_auth_verify_data(const unsigned char *payload,
 281                                            SilcUInt32 payload_len,
 282                                            SilcPublicKey public_key,
 283                                            SilcHash hash,
 284                                            const void *id, SilcIdType type);
 285
 286 /****f* silccore/SilcAuthAPI/silc_auth_verify
 287  *
 288  * SYNOPSIS
 289  *
 290  *    bool silc_auth_verify(SilcAuthPayload payload,
 291  *                          SilcAuthMethod auth_method,
 292  *                          const void *auth_data, SilcUInt32 auth_data_len,
 293  *                          SilcHash hash, const void *id, SilcIdType type);
 294  *
 295  * DESCRIPTION
 296  *
 297  *    Verifies the authentication data directly from the Authentication
 298  *    Payload. Supports all authentication methods. If the authentication
 299  *    method is passphrase based then the `auth_data' and `auth_data_len'
 300  *    are the passphrase and its length.  The passphrase MUST be UTF-8
 301  *    encoded.  If the method is public key authentication then the
 302  *    `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
 303  *
 304  ***/
 305 bool silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
 306                       const void *auth_data, SilcUInt32 auth_data_len,
 307                       SilcHash hash, const void *id, SilcIdType type);
 308
 309 /****f* silccore/SilcAuthAPI/silc_auth_verify_data
 310  *
 311  * SYNOPSIS
 312  *
 313  *    bool silc_auth_verify_data(const unsigned char *payload,
 314  *                               SilcUInt32 payload_len,
 315  *                               SilcAuthMethod auth_method,
 316  *                               const void *auth_data,
 317  *                               SilcUInt32 auth_data_len, SilcHash hash,
 318  *                               const void *id, SilcIdType type);
 319  *
 320  * DESCRIPTION
 321  *
 322  *    Same as silc_auth_verify but the payload has not been parsed yet.
 323  *    Verifies the authentication data directly from the Authentication
 324  *    Payload. Supports all authentication methods. If the authentication
 325  *    method is passphrase based then the `auth_data' and `auth_data_len'
 326  *    are the passphrase and its length.  The passphrase MUST be UTF-8
 327  *    encoded.  If the method is public key authentication then the
 328  *    `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
 329  *
 330  ***/
 331 bool silc_auth_verify_data(const unsigned char *payload,
 332                            SilcUInt32 payload_len,
 333                            SilcAuthMethod auth_method, const void *auth_data,
 334                            SilcUInt32 auth_data_len, SilcHash hash,
 335                            const void *id, SilcIdType type);
 336
 337 /****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload
 338  *
 339  * NAME
 340  *
 341  *    typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
 342  *
 343  * DESCRIPTION
 344  *
 345  *    This context is the actual Key Agreement Payload and is allocated
 346  *    by silc_key_agreement_payload_parse and given as argument usually to all
 347  *    silc_key_agreement_* functions.  It is freed by the function
 348  *    silc_key_agreement_payload_free.
 349  *
 350  ***/
 351 typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
 352
 353 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse
 354  *
 355  * SYNOPSIS
 356  *
 357  *    SilcKeyAgreementPayload
 358  *    silc_key_agreement_payload_parse(const unsigned char *payload,
 359  *                                     SilcUInt32 payload_len);
 360  *
 361  * DESCRIPTION
 362  *
 363  *    Parses and returns an allocated Key Agreement payload.
 364  *
 365  ***/
 366 SilcKeyAgreementPayload
 367 silc_key_agreement_payload_parse(const unsigned char *payload,
 368                                  SilcUInt32 payload_len);
 369
 370 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_encode
 371  *
 372  * SYNOPSIS
 373  *
 374  *    SilcBuffer silc_key_agreement_payload_encode(char *hostname,
 375  *                                                 SilcUInt32 port);
 376  *
 377  * DESCRIPTION
 378  *
 379  *    Encodes the Key Agreement protocol and returns the encoded buffer
 380  *
 381  ***/
 382 SilcBuffer silc_key_agreement_payload_encode(const char *hostname,
 383                                              SilcUInt32 port);
 384
 385 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_free
 386  *
 387  * SYNOPSIS
 388  *
 389  *    void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
 390  *
 391  * DESCRIPTION
 392  *
 393  *    Frees the Key Agreement protocol and all data in it.
 394  *
 395  ***/
 396 void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
 397
 398 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_hostname
 399  *
 400  * SYNOPSIS
 401  *
 402  *    char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
 403  *
 404  * DESCRIPTION
 405  *
 406  *    Returns the hostname in the payload. Caller must not free it.
 407  *    The hostname is the host that is able to accept key negotiation
 408  *    using the SILC Key Exchange protocol.
 409  *
 410  ***/
 411 char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
 412
 413 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_port
 414  *
 415  * SYNOPSIS
 416  *
 417  *    SilcUInt32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
 418  *
 419  * DESCRIPTION
 420  *
 421  *    Returns the port in the payload.  The port is the port on the
 422  *    host returned by silc_key_agreement_get_hostname that is running
 423  *    the SILC Key Exchange protocol.
 424  *
 425  ***/
 426 SilcUInt32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
 427
 428 #endif