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  * This interface defines also the SILC_MESSAGE_FLAG_SIGNED Payload,
  36  * which defines how channel messages and private messages can be digitally
  37  * signed.  This interface provides the payload parsing, encoding,
  38  * signature computing and signature verification routines.
  39  *
  40  ***/
  41
  42 #ifndef SILCAUTH_H
  43 #define SILCAUTH_H
  44
  45 /****d* silccore/SilcAuthAPI/SilcAuthMethod
  46  *
  47  * NAME
  48  *
  49  *    typedef SilcUInt16 SilcAuthMethod;
  50  *
  51  * DESCRIPTION
  52  *
  53  *    Authentication method type definition, the authentication methods
  54  *    and the authentication status'.  The status defines are used by
  55  *    all authentication protocols in the SILC.
  56  *
  57  * SOURCE
  58  */
  59 typedef SilcUInt16 SilcAuthMethod;
  60
  61 #define SILC_AUTH_NONE        0            /* No authentication */
  62 #define SILC_AUTH_PASSWORD    1            /* Passphrase authentication */
  63 #define SILC_AUTH_PUBLIC_KEY  2            /* Public key authentication */
  64
  65 /* Authentication protocol status message (used by all authentication
  66    protocols in the SILC). */
  67 #define SILC_AUTH_OK          0
  68 #define SILC_AUTH_FAILED      1
  69 /***/
  70
  71 /****s* silccore/SilcAuthAPI/SilcAuthPayload
  72  *
  73  * NAME
  74  *
  75  *    typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
  76  *
  77  *
  78  * DESCRIPTION
  79  *
  80  *    This context is the actual Authentication Payload and is allocated
  81  *    by silc_auth_payload_parse and given as argument usually to all
  82  *    silc_auth_payload_* functions.  It is freed by silc_auth_payload_free
  83  *    function.
  84  *
  85  ***/
  86 typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
  87
  88 /****f* silccore/SilcAuthAPI/silc_auth_payload_parse
  89  *
  90  * SYNOPSIS
  91  *
  92  *    SilcAuthPayload silc_auth_payload_parse(const unsigned char *data,
  93  *                                            SilcUInt32 data_len);
  94  *
  95  * DESCRIPTION
  96  *
  97  *    Parses and returns Authentication Payload.  The `data' and the
  98  *    `data_len' are the raw payload buffer.
  99  *
 100  ***/
 101 SilcAuthPayload silc_auth_payload_parse(const unsigned char *data,
 102                                         SilcUInt32 data_len);
 103
 104 /****f* silccore/SilcAuthAPI/silc_auth_payload_encode
 105  *
 106  * SYNOPSIS
 107  *
 108  *    SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
 109  *                                        const unsigned char *random_data,
 110  *                                        SilcUInt16 random_len,
 111  *                                        const unsigned char *auth_data,
 112  *                                        SilcUInt16 auth_len);
 113  *
 114  * DESCRIPTION
 115  *
 116  *    Encodes authentication payload into buffer and returns it.
 117  *    The `random_data' is provided only if doing public key authentication.
 118  *    The `auth_data' is the actual authentication data.  If the
 119  *    `method' is SILC_AUTH_PASSWORD the passphase in `auth_data' sent as
 120  *    argument SHOULD be UTF-8 encoded, if not library will attempt to
 121  *    encode it.
 122  *
 123  ***/
 124 SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
 125                                     const unsigned char *random_data,
 126                                     SilcUInt16 random_len,
 127                                     const unsigned char *auth_data,
 128                                     SilcUInt16 auth_len);
 129
 130 /****f* silccore/SilcAuthAPI/silc_auth_payload_free
 131  *
 132  * SYNOPSIS
 133  *
 134  *    void silc_auth_payload_free(SilcAuthPayload payload);
 135  *
 136  * DESCRIPTION
 137  *
 138  *    Frees authentication payload and all data in it.
 139  *
 140  ***/
 141 void silc_auth_payload_free(SilcAuthPayload payload);
 142
 143 /****f* silccore/SilcAuthAPI/silc_auth_get_method
 144  *
 145  * SYNOPSIS
 146  *
 147  *    SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
 148  *
 149  * DESCRIPTION
 150  *
 151  *    Get authentication method.
 152  *
 153  ***/
 154 SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
 155
 156 /****f* silccore/SilcAuthAPI/silc_auth_get_data
 157  *
 158  * SYNOPSIS
 159  *
 160  *    unsigned char *silc_auth_get_data(SilcAuthPayload payload,
 161  *                                      SilcUInt32 *auth_len);
 162  *
 163  * DESCRIPTION
 164  *
 165  *    Get the authentication data. The caller must not free the data.  If
 166  *    the authentication method is passphrase, then the returned string
 167  *    is UTF-8 encoded passphrase.
 168  *
 169  ***/
 170 unsigned char *silc_auth_get_data(SilcAuthPayload payload,
 171                                   SilcUInt32 *auth_len);
 172
 173 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate
 174  *
 175  * SYNOPSIS
 176  *
 177  *    SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
 178  *                                                  SilcPrivateKey private_key,
 179  *                                                  SilcRng rng,
 180  *                                                  SilcHash hash,
 181  *                                                  const void *id,
 182  *                                                  SilcIdType type);
 183  *
 184  * DESCRIPTION
 185  *
 186  *    Generates Authentication Payload with authentication data. This is used
 187  *    to do public key based authentication. This generates the random data
 188  *    and the actual authentication data. Returns NULL on error and the
 189  *    encoded Authentication Payload on success.
 190  *
 191  *    The `private_key' is used to sign the payload.  The `public_key', the
 192  *    and the `id' is encoded in the payload and signed.  If the `rng' is
 193  *    NULL then global RNG is used, if non-NULL then `rng' is used as
 194  *    random number generator.  Also random number is encoded in the
 195  *    payload before signing it with `private_key'.
 196  *
 197  ***/
 198 SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
 199                                               SilcPrivateKey private_key,
 200                                               SilcRng rng, SilcHash hash,
 201                                               const void *id, SilcIdType type);
 202
 203 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify
 204  *
 205  * SYNOPSIS
 206  *
 207  *    bool silc_auth_public_key_auth_verify(SilcAuthPayload payload,
 208  *                                          SilcPublicKey public_key,
 209  *                                          SilcHash hash,
 210  *                                          const void *id, SilcIdType type);
 211  *
 212  * DESCRIPTION
 213  *
 214  *    Verifies the authentication data. Returns TRUE if authentication was
 215  *    successful.
 216  *
 217  ***/
 218 bool silc_auth_public_key_auth_verify(SilcAuthPayload payload,
 219                                       SilcPublicKey public_key, SilcHash hash,
 220                                       const void *id, SilcIdType type);
 221
 222 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify_data
 223  *
 224  * SYNOPSIS
 225  *
 226  *    bool silc_auth_public_key_auth_verify_data(const unsigned char *payload,
 227  *                                               SilcUInt32 payload_len,
 228  *                                               SilcPublicKey public_key,
 229  *                                               SilcHash hash,
 230  *                                               const void *id,
 231  *                                               SilcIdType type);
 232  *
 233  * DESCRIPTION
 234  *
 235  *    Same as silc_auth_public_key_auth_verify but the payload has not
 236  *    been parsed yet.  This will parse it.  Returns TRUE if authentication
 237  *    was successful.
 238  *
 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, SilcIdType type);
 245
 246 /****f* silccore/SilcAuthAPI/silc_auth_verify
 247  *
 248  * SYNOPSIS
 249  *
 250  *    bool silc_auth_verify(SilcAuthPayload payload,
 251  *                          SilcAuthMethod auth_method,
 252  *                          const void *auth_data, SilcUInt32 auth_data_len,
 253  *                          SilcHash hash, const void *id, SilcIdType type);
 254  *
 255  * DESCRIPTION
 256  *
 257  *    Verifies the authentication data directly from the Authentication
 258  *    Payload. Supports all authentication methods. If the authentication
 259  *    method is passphrase based then the `auth_data' and `auth_data_len'
 260  *    are the passphrase and its length.  The passphrase MUST be UTF-8
 261  *    encoded.  If the method is public key authentication then the
 262  *    `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
 263  *
 264  ***/
 265 bool silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
 266                       const void *auth_data, SilcUInt32 auth_data_len,
 267                       SilcHash hash, const void *id, SilcIdType type);
 268
 269 /****f* silccore/SilcAuthAPI/silc_auth_verify_data
 270  *
 271  * SYNOPSIS
 272  *
 273  *    bool silc_auth_verify_data(const unsigned char *payload,
 274  *                               SilcUInt32 payload_len,
 275  *                               SilcAuthMethod auth_method,
 276  *                               const void *auth_data,
 277  *                               SilcUInt32 auth_data_len, SilcHash hash,
 278  *                               const void *id, SilcIdType type);
 279  *
 280  * DESCRIPTION
 281  *
 282  *    Same as silc_auth_verify but the payload has not been parsed yet.
 283  *    Verifies the authentication data directly from the Authentication
 284  *    Payload. Supports all authentication methods. If the authentication
 285  *    method is passphrase based then the `auth_data' and `auth_data_len'
 286  *    are the passphrase and its length.  The passphrase MUST be UTF-8
 287  *    encoded.  If the method is public key authentication then the
 288  *    `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
 289  *
 290  ***/
 291 bool silc_auth_verify_data(const unsigned char *payload,
 292                            SilcUInt32 payload_len,
 293                            SilcAuthMethod auth_method, const void *auth_data,
 294                            SilcUInt32 auth_data_len, SilcHash hash,
 295                            const void *id, SilcIdType type);
 296
 297 /****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload
 298  *
 299  * NAME
 300  *
 301  *    typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
 302  *
 303  * DESCRIPTION
 304  *
 305  *    This context is the actual Key Agreement Payload and is allocated
 306  *    by silc_key_agreement_payload_parse and given as argument usually to all
 307  *    silc_key_agreement_* functions.  It is freed by the function
 308  *    silc_key_agreement_payload_free.
 309  *
 310  ***/
 311 typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
 312
 313 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse
 314  *
 315  * SYNOPSIS
 316  *
 317  *    SilcKeyAgreementPayload
 318  *    silc_key_agreement_payload_parse(const unsigned char *payload,
 319  *                                     SilcUInt32 payload_len);
 320  *
 321  * DESCRIPTION
 322  *
 323  *    Parses and returns an allocated Key Agreement payload.
 324  *
 325  ***/
 326 SilcKeyAgreementPayload
 327 silc_key_agreement_payload_parse(const unsigned char *payload,
 328                                  SilcUInt32 payload_len);
 329
 330 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_encode
 331  *
 332  * SYNOPSIS
 333  *
 334  *    SilcBuffer silc_key_agreement_payload_encode(char *hostname,
 335  *                                                 SilcUInt32 port);
 336  *
 337  * DESCRIPTION
 338  *
 339  *    Encodes the Key Agreement protocol and returns the encoded buffer
 340  *
 341  ***/
 342 SilcBuffer silc_key_agreement_payload_encode(const char *hostname,
 343                                              SilcUInt32 port);
 344
 345 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_free
 346  *
 347  * SYNOPSIS
 348  *
 349  *    void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
 350  *
 351  * DESCRIPTION
 352  *
 353  *    Frees the Key Agreement protocol and all data in it.
 354  *
 355  ***/
 356 void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
 357
 358 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_hostname
 359  *
 360  * SYNOPSIS
 361  *
 362  *    char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
 363  *
 364  * DESCRIPTION
 365  *
 366  *    Returns the hostname in the payload. Caller must not free it.
 367  *    The hostname is the host that is able to accept key negotiation
 368  *    using the SILC Key Exchange protocol.
 369  *
 370  ***/
 371 char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
 372
 373 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_port
 374  *
 375  * SYNOPSIS
 376  *
 377  *    SilcUInt32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
 378  *
 379  * DESCRIPTION
 380  *
 381  *    Returns the port in the payload.  The port is the port on the
 382  *    host returned by silc_key_agreement_get_hostname that is running
 383  *    the SILC Key Exchange protocol.
 384  *
 385  ***/
 386 SilcUInt32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
 387
 388 /****s* silccore/SilcAuthAPI/SilcSignedPayload
 389  *
 390  * NAME
 391  *
 392  *    typedef struct SilcSignedPayloadStruct *SilcSignedPayload;
 393  *
 394  *
 395  * DESCRIPTION
 396  *
 397  *    This context represents the SILC_MESSAGE_FLAG_SIGNED Payload which
 398  *    is used with channel messages and private messages to indicate that
 399  *    the message is digitally signed.  This payload may include the
 400  *    message sender's public key and it includes the digital signature.
 401  *    This payload MUST NOT be used in any other context except with
 402  *    channel and private message sending and reception.
 403  *
 404  ***/
 405 typedef struct SilcSignedPayloadStruct *SilcSignedPayload;
 406
 407 /****f* silccore/SilcAuthAPI/silc_signed_payload_parse
 408  *
 409  * SYNOPSIS
 410  *
 411  *    SilcSignedPayload silc_signed_payload_parse(const unsigned char *data,
 412  *                                                SilcUInt32 data_len);
 413  *
 414  * DESCRIPTION
 415  *
 416  *    Parses the SILC_MESSAGE_FLAG_SIGNED Payload from the `data' of
 417  *    length of `data_len' bytes.  The `data' must be payload without
 418  *    the actual message payload.  Returns the parsed payload or NULL
 419  *    on error.  Caller must free the returned payload.
 420  *
 421  ***/
 422 SilcSignedPayload silc_signed_payload_parse(const unsigned char *data,
 423                                             SilcUInt32 data_len);
 424
 425 /****f* silccore/SilcAuthAPI/silc_signed_payload_encode
 426  *
 427  * SYNOPSIS
 428  *
 429  *    SilcBuffer
 430  *    silc_signed_payload_encode(const unsigned char *message_payload,
 431  *                               SilcUInt32 message_payload_len,
 432  *                               SilcPublicKey public_key,
 433  *                               SilcPrivateKey private_key,
 434  *                               bool include_public_key);
 435  *
 436  * DESCRIPTION
 437  *
 438  *    Encodes the SILC_MESSAGE_FLAG_SIGNED Payload and computes the
 439  *    digital signature.  The `message_payload' is the message data that
 440  *    is used in the signature computation.  The encoding of the buffer
 441  *    is specified in the SILC protocol.  If `include_public_key' is
 442  *    TRUE then the public key included in the payload.  The `private_key'
 443  *    is used to produce the signature.  This function returns the encoded
 444  *    payload with the signature or NULL on error.  Caller must free the
 445  *    returned buffer.
 446  *
 447  ***/
 448 SilcBuffer silc_signed_payload_encode(const unsigned char *message_payload,
 449                                       SilcUInt32 message_payload_len,
 450                                       SilcPublicKey public_key,
 451                                       SilcPrivateKey private_key,
 452                                       SilcHash hash,
 453                                       bool include_public_key);
 454
 455 /****f* silccore/SilcAuthAPI/silc_signed_payload_free
 456  *
 457  * SYNOPSIS
 458  *
 459  *    void silc_signed_payload_free(SilcSignedPayload sig);
 460  *
 461  * DESCRIPTION
 462  *
 463  *    Frees the SILC_MESSAGE_FLAG_SIGNED Payload.
 464  *
 465  ***/
 466 void silc_signed_payload_free(SilcSignedPayload sig);
 467
 468 /****f* silccore/SilcAuthAPI/silc_signed_payload_verify
 469  *
 470  * SYNOPSIS
 471  *
 472  *    int silc_signed_payload_verify(SilcSignedPayload sig,
 473  *                                   bool channel_message,
 474  *                                   void *message_payload,
 475  *                                   SilcPublicKey remote_public_key,
 476  *                                   SilcHash hash);
 477  *
 478  * DESCRIPTION
 479  *
 480  *    This routine can be used to verify the signature found in
 481  *    SILC_MESSAGE_FLAG_SIGNED Payload.  The `remote_public_key' is the
 482  *    sender's public key and is used in the verification.  If the
 483  *    `channel_message' is TRUE then `message_payload' must include the
 484  *    SilcChannelMessagePayload.  If it is FALSE then it must include
 485  *    SilcPrivateMessagePayload.  This returns SILC_AUTH_OK if the
 486  *    signature verification was successful.
 487  *
 488  ***/
 489 int silc_signed_payload_verify(SilcSignedPayload sig,
 490                                bool channel_message,
 491                                void *message_payload,
 492                                SilcPublicKey remote_public_key,
 493                                SilcHash hash);
 494
 495 /****f* silccore/SilcAuthAPI/silc_signed_payload_get_public_key
 496  *
 497  * SYNOPSIS
 498  *
 499  *    SilcPublicKey silc_signed_payload_get_public_key(SilcSignedPayload sig);
 500  *
 501  * DESCRIPTION
 502  *
 503  *    Returns the public key from the SILC_MESSAGE_FLAG_SIGNED Payload
 504  *    or NULL if it does not include public key.  The caller must free
 505  *    the returned public key.
 506  *
 507  ***/
 508 SilcPublicKey silc_signed_payload_get_public_key(SilcSignedPayload sig);
 509
 510 #endif