lib/silccore/silcauth.h

   1 /*
   2
   3   silcauth.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2001 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; either version 2 of the License, or
  12   (at your option) any later version.
  13
  14   This program is distributed in the hope that it will be useful,
  15   but WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17   GNU General Public License for more details.
  18
  19 */
  20
  21 /****h* silccore/SILC Authentication Interface
  22  *
  23  * DESCRIPTION
  24  *
  25  * Implementations of the SILC Authentication Payload and authentication
  26  * routines.  The SILC Authentication Payload is used to deliver
  27  * authentication data usually from client to server in purpose of
  28  * gaining access to some service.  The Payload and the authentication
  29  * routines supports both passphrase and public key (signature) based
  30  * authentication.
  31  *
  32  * This interface defines also the SILC Key Agreement Payload that is
  33  * used by client to agree on key material usually with another client
  34  * in the network.
  35  *
  36  ***/
  37
  38 #ifndef SILCAUTH_H
  39 #define SILCAUTH_H
  40
  41 /****s* silccore/SilcAuthAPI/SilcAuthPayload
  42  *
  43  * NAME
  44  *
  45  *    typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
  46  *
  47  *
  48  * DESCRIPTION
  49  *
  50  *    This context is the actual Authentication Payload and is allocated
  51  *    by silc_auth_payload_parse and given as argument usually to all
  52  *    silc_auth_payload_* functions.  It is freed by silc_auth_payload_free
  53  *    function.
  54  *
  55  ***/
  56 typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
  57
  58 /****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload
  59  *
  60  * NAME
  61  *
  62  *    typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
  63  *
  64  * DESCRIPTION
  65  *
  66  *    This context is the actual Key Agreement Payload and is allocated
  67  *    by silc_key_agreement_payload_parse and given as argument usually to all
  68  *    silc_key_agreement_* functions.  It is freed by the function
  69  *    silc_key_agreement_payload_free.
  70  *
  71  ***/
  72 typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
  73
  74 /****d* silccore/SilcAuthAPI/SilcAuthMethod
  75  *
  76  * NAME
  77  *
  78  *    typedef SilcUInt16 SilcAuthMethod;
  79  *
  80  * DESCRIPTION
  81  *
  82  *    Authentication method type definition, the authentication methods
  83  *    and the authentication status'.  The status defines are used by
  84  *    all authentication protocols in the SILC.
  85  *
  86  * SOURCE
  87  */
  88 typedef SilcUInt16 SilcAuthMethod;
  89
  90 #define SILC_AUTH_NONE        0            /* No authentication */
  91 #define SILC_AUTH_PASSWORD    1            /* Passphrase authentication */
  92 #define SILC_AUTH_PUBLIC_KEY  2            /* Public key authentication */
  93
  94 /* Authentication protocol status message (used by all authentication
  95    protocols in the SILC). */
  96 #define SILC_AUTH_OK          0
  97 #define SILC_AUTH_FAILED      1
  98 /***/
  99
 100 /* Prototypes */
 101
 102 /****f* silccore/SilcAuthAPI/silc_auth_payload_parse
 103  *
 104  * SYNOPSIS
 105  *
 106  *    SilcAuthPayload silc_auth_payload_parse(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.
 113  *
 114  ***/
 115 SilcAuthPayload silc_auth_payload_parse(const unsigned char *data,
 116                                         SilcUInt32 data_len);
 117
 118 /****f* silccore/SilcAuthAPI/silc_auth_payload_encode
 119  *
 120  * SYNOPSIS
 121  *
 122  *    SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
 123  *                                        const unsigned char *random_data,
 124  *                                        SilcUInt16 random_len,
 125  *                                        const unsigned char *auth_data,
 126  *                                        SilcUInt16 auth_len);
 127  *
 128  * DESCRIPTION
 129  *
 130  *    Encodes authentication payload into buffer and returns it.
 131  *    The `random_data' is provided only if doing public key authentication.
 132  *    The `auth_data' is the actual authentication data.  If the
 133  *    `method' is SILC_AUTH_PASSWORD the passphase in `auth_data' sent as
 134  *    argument SHOULD be UTF-8 encoded, if not library will attempt to
 135  *    encode it.
 136  *
 137  ***/
 138 SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
 139                                     const unsigned char *random_data,
 140                                     SilcUInt16 random_len,
 141                                     const unsigned char *auth_data,
 142                                     SilcUInt16 auth_len);
 143
 144 /****f* silccore/SilcAuthAPI/silc_auth_payload_free
 145  *
 146  * SYNOPSIS
 147  *
 148  *    void silc_auth_payload_free(SilcAuthPayload payload);
 149  *
 150  * DESCRIPTION
 151  *
 152  *    Frees authentication payload and all data in it.
 153  *
 154  ***/
 155 void silc_auth_payload_free(SilcAuthPayload payload);
 156
 157 /****f* silccore/SilcAuthAPI/silc_auth_get_method
 158  *
 159  * SYNOPSIS
 160  *
 161  *    SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
 162  *
 163  * DESCRIPTION
 164  *
 165  *    Get authentication method.
 166  *
 167  ***/
 168 SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
 169
 170 /****f* silccore/SilcAuthAPI/silc_auth_get_data
 171  *
 172  * SYNOPSIS
 173  *
 174  *    unsigned char *silc_auth_get_data(SilcAuthPayload payload,
 175  *                                      SilcUInt32 *auth_len);
 176  *
 177  * DESCRIPTION
 178  *
 179  *    Get the authentication data. The caller must not free the data.  If
 180  *    the authentication method is passphrase, then the returned string
 181  *    is UTF-8 encoded passphrase.
 182  *
 183  ***/
 184 unsigned char *silc_auth_get_data(SilcAuthPayload payload,
 185                                   SilcUInt32 *auth_len);
 186
 187 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate
 188  *
 189  * SYNOPSIS
 190  *
 191  *    SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
 192  *                                                  SilcPrivateKey private_key,
 193  *                                                  SilcRng rng,
 194  *                                                  SilcHash hash,
 195  *                                                  const void *id,
 196  *                                                  SilcIdType type);
 197  *
 198  * DESCRIPTION
 199  *
 200  *    Generates Authentication Payload with authentication data. This is used
 201  *    to do public key based authentication. This generates the random data
 202  *    and the actual authentication data. Returns NULL on error and the
 203  *    encoded Authentication Payload on success.
 204  *
 205  *    The `private_key' is used to sign the payload.  The `public_key', the
 206  *    and the `id' is encoded in the payload and signed.  If the `rng' is
 207  *    NULL then global RNG is used, if non-NULL then `rng' is used as
 208  *    random number generator.  Also random number is encoded in the
 209  *    payload before signing it with `private_key'.
 210  *
 211  ***/
 212 SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
 213                                               SilcPrivateKey private_key,
 214                                               SilcRng rng, SilcHash hash,
 215                                               const void *id, SilcIdType type);
 216
 217 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify
 218  *
 219  * SYNOPSIS
 220  *
 221  *    bool silc_auth_public_key_auth_verify(SilcAuthPayload payload,
 222  *                                          SilcPublicKey public_key,
 223  *                                          SilcHash hash,
 224  *                                          const void *id, SilcIdType type);
 225  *
 226  * DESCRIPTION
 227  *
 228  *    Verifies the authentication data. Returns TRUE if authentication was
 229  *    successful.
 230  *
 231  ***/
 232 bool silc_auth_public_key_auth_verify(SilcAuthPayload payload,
 233                                       SilcPublicKey public_key, SilcHash hash,
 234                                       const void *id, SilcIdType type);
 235
 236 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify_data
 237  *
 238  * SYNOPSIS
 239  *
 240  *    bool silc_auth_public_key_auth_verify_data(const unsigned char *payload,
 241  *                                               SilcUInt32 payload_len,
 242  *                                               SilcPublicKey public_key,
 243  *                                               SilcHash hash,
 244  *                                               const void *id,
 245  *                                               SilcIdType type);
 246  *
 247  * DESCRIPTION
 248  *
 249  *    Same as silc_auth_public_key_auth_verify but the payload has not
 250  *    been parsed yet.  This will parse it.  Returns TRUE if authentication
 251  *    was successful.
 252  *
 253  ***/
 254 bool silc_auth_public_key_auth_verify_data(const unsigned char *payload,
 255                                            SilcUInt32 payload_len,
 256                                            SilcPublicKey public_key,
 257                                            SilcHash hash,
 258                                            const void *id, SilcIdType type);
 259
 260 /****f* silccore/SilcAuthAPI/silc_auth_verify
 261  *
 262  * SYNOPSIS
 263  *
 264  *    bool silc_auth_verify(SilcAuthPayload payload,
 265  *                          SilcAuthMethod auth_method,
 266  *                          const void *auth_data, SilcUInt32 auth_data_len,
 267  *                          SilcHash hash, const void *id, SilcIdType type);
 268  *
 269  * DESCRIPTION
 270  *
 271  *    Verifies the authentication data directly from the Authentication
 272  *    Payload. Supports all authentication methods. If the authentication
 273  *    method is passphrase based then the `auth_data' and `auth_data_len'
 274  *    are the passphrase and its length.  The passphrase MUST be UTF-8
 275  *    encoded.  If the method is public key authentication then the
 276  *    `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
 277  *
 278  ***/
 279 bool silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
 280                       const void *auth_data, SilcUInt32 auth_data_len,
 281                       SilcHash hash, const void *id, SilcIdType type);
 282
 283 /****f* silccore/SilcAuthAPI/silc_auth_verify_data
 284  *
 285  * SYNOPSIS
 286  *
 287  *    bool silc_auth_verify_data(const unsigned char *payload,
 288  *                               SilcUInt32 payload_len,
 289  *                               SilcAuthMethod auth_method,
 290  *                               const void *auth_data,
 291  *                               SilcUInt32 auth_data_len, SilcHash hash,
 292  *                               const void *id, SilcIdType type);
 293  *
 294  * DESCRIPTION
 295  *
 296  *    Same as silc_auth_verify but the payload has not been parsed yet.
 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_data(const unsigned char *payload,
 306                            SilcUInt32 payload_len,
 307                            SilcAuthMethod auth_method, const void *auth_data,
 308                            SilcUInt32 auth_data_len, SilcHash hash,
 309                            const void *id, SilcIdType type);
 310
 311 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse
 312  *
 313  * SYNOPSIS
 314  *
 315  *    SilcKeyAgreementPayload
 316  *    silc_key_agreement_payload_parse(const unsigned char *payload,
 317  *                                     SilcUInt32 payload_len);
 318  *
 319  * DESCRIPTION
 320  *
 321  *    Parses and returns an allocated Key Agreement payload.
 322  *
 323  ***/
 324 SilcKeyAgreementPayload
 325 silc_key_agreement_payload_parse(const unsigned char *payload,
 326                                  SilcUInt32 payload_len);
 327
 328 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_encode
 329  *
 330  * SYNOPSIS
 331  *
 332  *    SilcBuffer silc_key_agreement_payload_encode(char *hostname,
 333  *                                                 SilcUInt32 port);
 334  *
 335  * DESCRIPTION
 336  *
 337  *    Encodes the Key Agreement protocol and returns the encoded buffer
 338  *
 339  ***/
 340 SilcBuffer silc_key_agreement_payload_encode(const char *hostname,
 341                                              SilcUInt32 port);
 342
 343 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_free
 344  *
 345  * SYNOPSIS
 346  *
 347  *    void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
 348  *
 349  * DESCRIPTION
 350  *
 351  *    Frees the Key Agreement protocol and all data in it.
 352  *
 353  ***/
 354 void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
 355
 356 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_hostname
 357  *
 358  * SYNOPSIS
 359  *
 360  *    char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
 361  *
 362  * DESCRIPTION
 363  *
 364  *    Returns the hostname in the payload. Caller must not free it.
 365  *    The hostname is the host that is able to accept key negotiation
 366  *    using the SILC Key Exchange protocol.
 367  *
 368  ***/
 369 char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
 370
 371 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_port
 372  *
 373  * SYNOPSIS
 374  *
 375  *    SilcUInt32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
 376  *
 377  * DESCRIPTION
 378  *
 379  *    Returns the port in the payload.  The port is the port on the
 380  *    host returned by silc_key_agreement_get_hostname that is running
 381  *    the SILC Key Exchange protocol.
 382  *
 383  ***/
 384 SilcUInt32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
 385
 386 #endif