lib/silccore/silcauth.h

   1 /*
   2
   3   silcauth.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2001 - 2002 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_data
 152  *
 153  * SYNOPSIS
 154  *
 155  *    unsigned char *silc_auth_get_data(SilcAuthPayload payload,
 156  *                                      SilcUInt32 *auth_len);
 157  *
 158  * DESCRIPTION
 159  *
 160  *    Get the authentication data. The caller must not free the data.  If
 161  *    the authentication method is passphrase, then the returned string
 162  *    is UTF-8 encoded passphrase.
 163  *
 164  ***/
 165 unsigned char *silc_auth_get_data(SilcAuthPayload payload,
 166                                   SilcUInt32 *auth_len);
 167
 168 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate
 169  *
 170  * SYNOPSIS
 171  *
 172  *    SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
 173  *                                                  SilcPrivateKey private_key,
 174  *                                                  SilcRng rng,
 175  *                                                  SilcHash hash,
 176  *                                                  const void *id,
 177  *                                                  SilcIdType type);
 178  *
 179  * DESCRIPTION
 180  *
 181  *    Generates Authentication Payload with authentication data. This is used
 182  *    to do public key based authentication. This generates the random data
 183  *    and the actual authentication data. Returns NULL on error and the
 184  *    encoded Authentication Payload on success.
 185  *
 186  *    The `private_key' is used to sign the payload.  The `public_key', the
 187  *    and the `id' is encoded in the payload and signed.  If the `rng' is
 188  *    NULL then global RNG is used, if non-NULL then `rng' is used as
 189  *    random number generator.  Also random number is encoded in the
 190  *    payload before signing it with `private_key'.
 191  *
 192  ***/
 193 SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
 194                                               SilcPrivateKey private_key,
 195                                               SilcRng rng, SilcHash hash,
 196                                               const void *id, SilcIdType type);
 197
 198 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify
 199  *
 200  * SYNOPSIS
 201  *
 202  *    bool silc_auth_public_key_auth_verify(SilcAuthPayload payload,
 203  *                                          SilcPublicKey public_key,
 204  *                                          SilcHash hash,
 205  *                                          const void *id, SilcIdType type);
 206  *
 207  * DESCRIPTION
 208  *
 209  *    Verifies the authentication data. Returns TRUE if authentication was
 210  *    successful.
 211  *
 212  ***/
 213 bool silc_auth_public_key_auth_verify(SilcAuthPayload payload,
 214                                       SilcPublicKey public_key, SilcHash hash,
 215                                       const void *id, SilcIdType type);
 216
 217 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify_data
 218  *
 219  * SYNOPSIS
 220  *
 221  *    bool silc_auth_public_key_auth_verify_data(const unsigned char *payload,
 222  *                                               SilcUInt32 payload_len,
 223  *                                               SilcPublicKey public_key,
 224  *                                               SilcHash hash,
 225  *                                               const void *id,
 226  *                                               SilcIdType type);
 227  *
 228  * DESCRIPTION
 229  *
 230  *    Same as silc_auth_public_key_auth_verify but the payload has not
 231  *    been parsed yet.  This will parse it.  Returns TRUE if authentication
 232  *    was successful.
 233  *
 234  ***/
 235 bool silc_auth_public_key_auth_verify_data(const unsigned char *payload,
 236                                            SilcUInt32 payload_len,
 237                                            SilcPublicKey public_key,
 238                                            SilcHash hash,
 239                                            const void *id, SilcIdType type);
 240
 241 /****f* silccore/SilcAuthAPI/silc_auth_verify
 242  *
 243  * SYNOPSIS
 244  *
 245  *    bool silc_auth_verify(SilcAuthPayload payload,
 246  *                          SilcAuthMethod auth_method,
 247  *                          const void *auth_data, SilcUInt32 auth_data_len,
 248  *                          SilcHash hash, const void *id, SilcIdType type);
 249  *
 250  * DESCRIPTION
 251  *
 252  *    Verifies the authentication data directly from the Authentication
 253  *    Payload. Supports all authentication methods. If the authentication
 254  *    method is passphrase based then the `auth_data' and `auth_data_len'
 255  *    are the passphrase and its length.  The passphrase MUST be UTF-8
 256  *    encoded.  If the method is public key authentication then the
 257  *    `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
 258  *
 259  ***/
 260 bool silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
 261                       const void *auth_data, SilcUInt32 auth_data_len,
 262                       SilcHash hash, const void *id, SilcIdType type);
 263
 264 /****f* silccore/SilcAuthAPI/silc_auth_verify_data
 265  *
 266  * SYNOPSIS
 267  *
 268  *    bool silc_auth_verify_data(const unsigned char *payload,
 269  *                               SilcUInt32 payload_len,
 270  *                               SilcAuthMethod auth_method,
 271  *                               const void *auth_data,
 272  *                               SilcUInt32 auth_data_len, SilcHash hash,
 273  *                               const void *id, SilcIdType type);
 274  *
 275  * DESCRIPTION
 276  *
 277  *    Same as silc_auth_verify but the payload has not been parsed yet.
 278  *    Verifies the authentication data directly from the Authentication
 279  *    Payload. Supports all authentication methods. If the authentication
 280  *    method is passphrase based then the `auth_data' and `auth_data_len'
 281  *    are the passphrase and its length.  The passphrase MUST be UTF-8
 282  *    encoded.  If the method is public key authentication then the
 283  *    `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
 284  *
 285  ***/
 286 bool silc_auth_verify_data(const unsigned char *payload,
 287                            SilcUInt32 payload_len,
 288                            SilcAuthMethod auth_method, const void *auth_data,
 289                            SilcUInt32 auth_data_len, SilcHash hash,
 290                            const void *id, SilcIdType type);
 291
 292 /****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload
 293  *
 294  * NAME
 295  *
 296  *    typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
 297  *
 298  * DESCRIPTION
 299  *
 300  *    This context is the actual Key Agreement Payload and is allocated
 301  *    by silc_key_agreement_payload_parse and given as argument usually to all
 302  *    silc_key_agreement_* functions.  It is freed by the function
 303  *    silc_key_agreement_payload_free.
 304  *
 305  ***/
 306 typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
 307
 308 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse
 309  *
 310  * SYNOPSIS
 311  *
 312  *    SilcKeyAgreementPayload
 313  *    silc_key_agreement_payload_parse(const unsigned char *payload,
 314  *                                     SilcUInt32 payload_len);
 315  *
 316  * DESCRIPTION
 317  *
 318  *    Parses and returns an allocated Key Agreement payload.
 319  *
 320  ***/
 321 SilcKeyAgreementPayload
 322 silc_key_agreement_payload_parse(const unsigned char *payload,
 323                                  SilcUInt32 payload_len);
 324
 325 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_encode
 326  *
 327  * SYNOPSIS
 328  *
 329  *    SilcBuffer silc_key_agreement_payload_encode(char *hostname,
 330  *                                                 SilcUInt32 port);
 331  *
 332  * DESCRIPTION
 333  *
 334  *    Encodes the Key Agreement protocol and returns the encoded buffer
 335  *
 336  ***/
 337 SilcBuffer silc_key_agreement_payload_encode(const char *hostname,
 338                                              SilcUInt32 port);
 339
 340 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_free
 341  *
 342  * SYNOPSIS
 343  *
 344  *    void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
 345  *
 346  * DESCRIPTION
 347  *
 348  *    Frees the Key Agreement protocol and all data in it.
 349  *
 350  ***/
 351 void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
 352
 353 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_hostname
 354  *
 355  * SYNOPSIS
 356  *
 357  *    char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
 358  *
 359  * DESCRIPTION
 360  *
 361  *    Returns the hostname in the payload. Caller must not free it.
 362  *    The hostname is the host that is able to accept key negotiation
 363  *    using the SILC Key Exchange protocol.
 364  *
 365  ***/
 366 char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
 367
 368 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_port
 369  *
 370  * SYNOPSIS
 371  *
 372  *    SilcUInt32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
 373  *
 374  * DESCRIPTION
 375  *
 376  *    Returns the port in the payload.  The port is the port on the
 377  *    host returned by silc_key_agreement_get_hostname that is running
 378  *    the SILC Key Exchange protocol.
 379  *
 380  ***/
 381 SilcUInt32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
 382
 383 #endif