mingw/include/gsasl.h

   1 /* gsasl.h --- Header file for GNU SASL Library.
   2  * Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009  Simon Josefsson
   3  *
   4  * This file is part of GNU SASL Library.
   5  *
   6  * GNU SASL Library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public License
   8  * as published by the Free Software Foundation; either version 2.1 of
   9  * the License, or (at your option) any later version.
  10  *
  11  * GNU SASL Library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License License along with GNU SASL Library; if not, write to the
  18  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  19  * Boston, MA 02110-1301, USA.
  20  *
  21  */
  22
  23 #ifndef GSASL_H
  24 # define GSASL_H
  25
  26 # include <stdio.h>             /* FILE */
  27 # include <stddef.h>            /* size_t */
  28 # include <unistd.h>            /* ssize_t */
  29
  30 # ifndef GSASL_API
  31 #  if defined GSASL_BUILDING && defined HAVE_VISIBILITY && HAVE_VISIBILITY
  32 #   define GSASL_API __attribute__((__visibility__("default")))
  33 #  elif defined GSASL_BUILDING && defined _MSC_VER && ! defined GSASL_STATIC
  34 #   define GSASL_API __declspec(dllexport)
  35 #  elif defined _MSC_VER && ! defined GSASL_STATIC
  36 #   define GSASL_API __declspec(dllimport)
  37 #  else
  38 #   define GSASL_API
  39 #  endif
  40 # endif
  41
  42 # ifdef __cplusplus
  43 extern "C"
  44 {
  45 # endif
  46
  47   /**
  48    * GSASL_VERSION
  49    *
  50    * Pre-processor symbol with a string that describe the header file
  51    * version number.  Used together with gsasl_check_version() to
  52    * verify header file and run-time library consistency.
  53    */
  54 # define GSASL_VERSION "1.2"
  55
  56   /**
  57    * GSASL_VERSION_MAJOR
  58    *
  59    * Pre-processor symbol with a decimal value that describe the major
  60    * level of the header file version number.  For example, when the
  61    * header version is 1.2.3 this symbol will be 1.
  62    *
  63    * Since: 1.1
  64    */
  65 # define GSASL_VERSION_MAJOR 1
  66
  67   /**
  68    * GSASL_VERSION_MINOR
  69    *
  70    * Pre-processor symbol with a decimal value that describe the minor
  71    * level of the header file version number.  For example, when the
  72    * header version is 1.2.3 this symbol will be 2.
  73    *
  74    * Since: 1.1
  75    */
  76 # define GSASL_VERSION_MINOR 2
  77
  78   /**
  79    * GSASL_VERSION_PATCH
  80    *
  81    * Pre-processor symbol with a decimal value that describe the patch
  82    * level of the header file version number.  For example, when the
  83    * header version is 1.2.3 this symbol will be 3.
  84    *
  85    * Since: 1.1
  86    */
  87 # define GSASL_VERSION_PATCH 0
  88
  89   /**
  90    * GSASL_VERSION_NUMBER
  91    *
  92    * Pre-processor symbol with a hexadecimal value describing the
  93    * header file version number.  For example, when the header version
  94    * is 1.2.3 this symbol will have the value 0x010203.
  95    *
  96    * Since: 1.1
  97    */
  98 # define GSASL_VERSION_NUMBER 0x010200
  99
 100   /* RFC 2222: SASL mechanisms are named by strings, from 1 to 20
 101    * characters in length, consisting of upper-case letters, digits,
 102    * hyphens, and/or underscores.  SASL mechanism names must be
 103    * registered with the IANA.
 104    */
 105   enum
 106   {
 107     GSASL_MIN_MECHANISM_SIZE = 1,
 108     GSASL_MAX_MECHANISM_SIZE = 20
 109   };
 110   extern GSASL_API const char *GSASL_VALID_MECHANISM_CHARACTERS;
 111
 112   /* Error codes */
 113   typedef enum
 114   {
 115     GSASL_OK = 0,
 116     GSASL_NEEDS_MORE = 1,
 117     GSASL_UNKNOWN_MECHANISM = 2,
 118     GSASL_MECHANISM_CALLED_TOO_MANY_TIMES = 3,
 119     GSASL_MALLOC_ERROR = 7,
 120     GSASL_BASE64_ERROR = 8,
 121     GSASL_CRYPTO_ERROR = 9,
 122     GSASL_SASLPREP_ERROR = 29,
 123     GSASL_MECHANISM_PARSE_ERROR = 30,
 124     GSASL_AUTHENTICATION_ERROR = 31,
 125     GSASL_INTEGRITY_ERROR = 33,
 126     GSASL_NO_CLIENT_CODE = 35,
 127     GSASL_NO_SERVER_CODE = 36,
 128     GSASL_NO_CALLBACK = 51,
 129     GSASL_NO_ANONYMOUS_TOKEN = 52,
 130     GSASL_NO_AUTHID = 53,
 131     GSASL_NO_AUTHZID = 54,
 132     GSASL_NO_PASSWORD = 55,
 133     GSASL_NO_PASSCODE = 56,
 134     GSASL_NO_PIN = 57,
 135     GSASL_NO_SERVICE = 58,
 136     GSASL_NO_HOSTNAME = 59,
 137     /* Mechanism specific errors. */
 138     GSASL_GSSAPI_RELEASE_BUFFER_ERROR = 37,
 139     GSASL_GSSAPI_IMPORT_NAME_ERROR = 38,
 140     GSASL_GSSAPI_INIT_SEC_CONTEXT_ERROR = 39,
 141     GSASL_GSSAPI_ACCEPT_SEC_CONTEXT_ERROR = 40,
 142     GSASL_GSSAPI_UNWRAP_ERROR = 41,
 143     GSASL_GSSAPI_WRAP_ERROR = 42,
 144     GSASL_GSSAPI_ACQUIRE_CRED_ERROR = 43,
 145     GSASL_GSSAPI_DISPLAY_NAME_ERROR = 44,
 146     GSASL_GSSAPI_UNSUPPORTED_PROTECTION_ERROR = 45,
 147     GSASL_KERBEROS_V5_INIT_ERROR = 46,
 148     GSASL_KERBEROS_V5_INTERNAL_ERROR = 47,
 149     GSASL_SHISHI_ERROR = GSASL_KERBEROS_V5_INTERNAL_ERROR,
 150     GSASL_SECURID_SERVER_NEED_ADDITIONAL_PASSCODE = 48,
 151     GSASL_SECURID_SERVER_NEED_NEW_PIN = 49
 152   } Gsasl_rc;
 153
 154   /* Quality of Protection types, used by DIGEST-MD5 */
 155   typedef enum
 156   {
 157     GSASL_QOP_AUTH = 1,
 158     GSASL_QOP_AUTH_INT = 2,
 159     GSASL_QOP_AUTH_CONF = 4
 160   } Gsasl_qop;
 161
 162   /* Cipher types, used by DIGEST-MD5 */
 163   typedef enum
 164   {
 165     GSASL_CIPHER_DES = 1,
 166     GSASL_CIPHER_3DES = 2,
 167     GSASL_CIPHER_RC4 = 4,
 168     GSASL_CIPHER_RC4_40 = 8,
 169     GSASL_CIPHER_RC4_56 = 16,
 170     GSASL_CIPHER_AES = 32
 171   } Gsasl_cipher;
 172
 173   /* SASLprep flags, see gsasl_saslprep(). */
 174   typedef enum
 175   {
 176     GSASL_ALLOW_UNASSIGNED = 1
 177   } Gsasl_saslprep_flags;
 178
 179   /* Library handles */
 180   typedef struct Gsasl Gsasl;
 181   typedef struct Gsasl_session Gsasl_session;
 182
 183   /* Callback/property types. */
 184   typedef enum
 185   {
 186     /* Information properties, e.g., username. */
 187     GSASL_AUTHID = 1,
 188     GSASL_AUTHZID = 2,
 189     GSASL_PASSWORD = 3,
 190     GSASL_ANONYMOUS_TOKEN = 4,
 191     GSASL_SERVICE = 5,
 192     GSASL_HOSTNAME = 6,
 193     GSASL_GSSAPI_DISPLAY_NAME = 7,
 194     GSASL_PASSCODE = 8,
 195     GSASL_SUGGESTED_PIN = 9,
 196     GSASL_PIN = 10,
 197     GSASL_REALM = 11,
 198     GSASL_DIGEST_MD5_HASHED_PASSWORD = 12,
 199     GSASL_QOPS = 13,
 200     GSASL_QOP = 14,
 201     /* Server validation callback properties. */
 202     GSASL_VALIDATE_SIMPLE = 500,
 203     GSASL_VALIDATE_EXTERNAL = 501,
 204     GSASL_VALIDATE_ANONYMOUS = 502,
 205     GSASL_VALIDATE_GSSAPI = 503,
 206     GSASL_VALIDATE_SECURID = 504
 207   } Gsasl_property;
 208
 209   /**
 210    * Gsasl_callback_function:
 211    * @ctx: libgsasl handle.
 212    * @sctx: session handle, may be NULL.
 213    * @prop: enumerated value of Gsasl_property type.
 214    *
 215    * Prototype of function that the application should implement.  Use
 216    * gsasl_callback_set() to inform the library about your callback
 217    * function.
 218    *
 219    * It is called by the SASL library when it need some information
 220    * from the application.  Depending on the value of @prop, it should
 221    * either set some property (e.g., username or password) using
 222    * gsasl_property_set(), or it should extract some properties (e.g.,
 223    * authentication and authorization identities) using
 224    * gsasl_property_fast() and use them to make a policy decision,
 225    * perhaps returning GSASL_AUTHENTICATION_ERROR or GSASL_OK
 226    * depending on whether the policy permitted the operation.
 227    *
 228    * Return value: Any valid return code, the interpretation of which
 229    *   depend on the @prop value.
 230    *
 231    * Since: 0.2.0
 232    **/
 233   typedef int (*Gsasl_callback_function) (Gsasl * ctx, Gsasl_session * sctx,
 234                                           Gsasl_property prop);
 235
 236   /* Library entry and exit points: version.c, init.c, done.c */
 237   extern GSASL_API int gsasl_init (Gsasl ** ctx);
 238   extern GSASL_API void gsasl_done (Gsasl * ctx);
 239   extern GSASL_API const char *gsasl_check_version (const char *req_version);
 240
 241   /* Callback handling: callback.c */
 242   extern GSASL_API void gsasl_callback_set (Gsasl * ctx,
 243                                             Gsasl_callback_function cb);
 244   extern GSASL_API int gsasl_callback (Gsasl * ctx, Gsasl_session * sctx,
 245                                        Gsasl_property prop);
 246
 247   extern GSASL_API void gsasl_callback_hook_set (Gsasl * ctx, void *hook);
 248   extern GSASL_API void *gsasl_callback_hook_get (Gsasl * ctx);
 249
 250   extern GSASL_API void gsasl_session_hook_set (Gsasl_session * sctx,
 251                                                 void *hook);
 252   extern GSASL_API void *gsasl_session_hook_get (Gsasl_session * sctx);
 253
 254   /* Property handling: property.c */
 255   extern GSASL_API void gsasl_property_set (Gsasl_session * sctx,
 256                                             Gsasl_property prop,
 257                                             const char *data);
 258   extern GSASL_API void gsasl_property_set_raw (Gsasl_session * sctx,
 259                                                 Gsasl_property prop,
 260                                                 const char *data, size_t len);
 261   extern GSASL_API const char *gsasl_property_get (Gsasl_session * sctx,
 262                                                    Gsasl_property prop);
 263   extern GSASL_API const char *gsasl_property_fast (Gsasl_session * sctx,
 264                                                     Gsasl_property prop);
 265
 266   /* Mechanism handling: listmech.c, supportp.c, suggest.c */
 267   extern GSASL_API int gsasl_client_mechlist (Gsasl * ctx, char **out);
 268   extern GSASL_API int gsasl_client_support_p (Gsasl * ctx, const char *name);
 269   extern GSASL_API const char *gsasl_client_suggest_mechanism (Gsasl * ctx,
 270                                                                const char
 271                                                                *mechlist);
 272
 273   extern GSASL_API int gsasl_server_mechlist (Gsasl * ctx, char **out);
 274   extern GSASL_API int gsasl_server_support_p (Gsasl * ctx, const char *name);
 275
 276   /* Authentication functions: xstart.c, xstep.c, xfinish.c */
 277   extern GSASL_API int gsasl_client_start (Gsasl * ctx, const char *mech,
 278                                            Gsasl_session ** sctx);
 279   extern GSASL_API int gsasl_server_start (Gsasl * ctx, const char *mech,
 280                                            Gsasl_session ** sctx);
 281   extern GSASL_API int gsasl_step (Gsasl_session * sctx,
 282                                    const char *input, size_t input_len,
 283                                    char **output, size_t * output_len);
 284   extern GSASL_API int gsasl_step64 (Gsasl_session * sctx,
 285                                      const char *b64input, char **b64output);
 286   extern GSASL_API void gsasl_finish (Gsasl_session * sctx);
 287
 288   /* Session functions: xcode.c, mechname.c */
 289   extern GSASL_API int gsasl_encode (Gsasl_session * sctx,
 290                                      const char *input, size_t input_len,
 291                                      char **output, size_t * output_len);
 292   extern GSASL_API int gsasl_decode (Gsasl_session * sctx,
 293                                      const char *input, size_t input_len,
 294                                      char **output, size_t * output_len);
 295   extern GSASL_API const char *gsasl_mechanism_name (Gsasl_session * sctx);
 296
 297   /* Error handling: error.c */
 298   extern GSASL_API const char *gsasl_strerror (int err);
 299   extern GSASL_API const char *gsasl_strerror_name (int err);
 300
 301   /* Internationalized string processing: stringprep.c */
 302   extern GSASL_API int gsasl_saslprep (const char *in,
 303                                        Gsasl_saslprep_flags flags, char **out,
 304                                        int *stringpreprc);
 305
 306   /* Utilities: base64.c, md5pwd.c, crypto.c */
 307   extern GSASL_API int gsasl_simple_getpass (const char *filename,
 308                                              const char *username,
 309                                              char **key);
 310   extern GSASL_API int gsasl_base64_to (const char *in, size_t inlen,
 311                                         char **out, size_t * outlen);
 312   extern GSASL_API int gsasl_base64_from (const char *in, size_t inlen,
 313                                           char **out, size_t * outlen);
 314   extern GSASL_API int gsasl_nonce (char *data, size_t datalen);
 315   extern GSASL_API int gsasl_random (char *data, size_t datalen);
 316   extern GSASL_API int gsasl_md5 (const char *in, size_t inlen,
 317                                   char *out[16]);
 318   extern GSASL_API int gsasl_hmac_md5 (const char *key, size_t keylen,
 319                                        const char *in, size_t inlen,
 320                                        char *outhash[16]);
 321   extern GSASL_API void gsasl_free (void *ptr);
 322
 323   /* Get the mechanism API. */
 324 # include <gsasl-mech.h>
 325
 326 #ifndef GSASL_NO_OBSOLETE
 327   /* For compatibility with earlier versions. */
 328 # include <gsasl-compat.h>
 329 #endif
 330
 331 # ifdef __cplusplus
 332 }
 333 # endif
 334
 335 #endif                          /* GSASL_H */