lib/gsasl.h.in

   1 /* gsasl.h      header file for libgsasl -*- c -*-
   2  * Copyright (C) 2002  Simon Josefsson
   3  *
   4  * This file is part of libgsasl.
   5  *
   6  * Libgsasl is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * Libgsasl 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 along with libgsasl; if not, write to the Free Software
  18  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  19  *
  20  */
  21
  22 #ifndef _GSASL_H
  23 #define _GSASL_H
  24
  25 #include <stdio.h>
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #if 0 /* keep Emacsens's auto-indent happy */
  30 }
  31 #endif
  32 #endif
  33
  34 #define GSASL_VERSION "@PACKAGE_VERSION@"
  35
  36 /* Quoting RFC 2222:
  37    SASL mechanisms are named by strings, from 1 to 20 characters in
  38    length, consisting of upper-case letters, digits, hyphens, and/or
  39    underscores.  SASL mechanism names must be registered with the IANA. */
  40 enum {
  41   GSASL_MIN_MECHANISM_SIZE = 1,
  42   GSASL_MAX_MECHANISM_SIZE = 20
  43 };
  44 extern const char *GSASL_VALID_MECHANISM_CHARACTERS;
  45
  46 /* Error codes */
  47 enum {
  48   GSASL_OK = 0,
  49   GSASL_NEEDS_MORE,
  50   GSASL_UNKNOWN_MECHANISM,
  51   GSASL_MECHANISM_CALLED_TOO_MANY_TIMES,
  52   GSASL_TOO_SMALL_BUFFER,
  53   GSASL_FOPEN_ERROR,
  54   GSASL_FCLOSE_ERROR,
  55   GSASL_MALLOC_ERROR,
  56   GSASL_BASE64_ERROR,
  57   GSASL_GCRYPT_ERROR,
  58   GSASL_GSSAPI_RELEASE_BUFFER_ERROR,
  59   GSASL_GSSAPI_IMPORT_NAME_ERROR,
  60   GSASL_GSSAPI_INIT_SEC_CONTEXT_ERROR,
  61   GSASL_GSSAPI_ACCEPT_SEC_CONTEXT_ERROR,
  62   GSASL_GSSAPI_UNWRAP_ERROR,
  63   GSASL_GSSAPI_WRAP_ERROR,
  64   GSASL_GSSAPI_ACQUIRE_CRED_ERROR,
  65   GSASL_GSSAPI_DISPLAY_NAME_ERROR,
  66   GSASL_GSSAPI_UNSUPPORTED_PROTECTION_ERROR,
  67   GSASL_NEED_CLIENT_ANONYMOUS_CALLBACK,
  68   GSASL_NEED_CLIENT_PASSWORD_CALLBACK,
  69   GSASL_NEED_CLIENT_PASSCODE_CALLBACK,
  70   GSASL_NEED_CLIENT_PIN_CALLBACK,
  71   GSASL_NEED_CLIENT_AUTHORIZATION_ID_CALLBACK,
  72   GSASL_NEED_CLIENT_AUTHENTICATION_ID_CALLBACK,
  73   GSASL_NEED_CLIENT_SERVICE_CALLBACK,
  74   GSASL_NEED_SERVER_VALIDATE_CALLBACK,
  75   GSASL_NEED_SERVER_CRAM_MD5_CALLBACK,
  76   GSASL_NEED_SERVER_DIGEST_MD5_CALLBACK,
  77   GSASL_NEED_SERVER_EXTERNAL_CALLBACK,
  78   GSASL_NEED_SERVER_ANONYMOUS_CALLBACK,
  79   GSASL_NEED_SERVER_REALM_CALLBACK,
  80   GSASL_NEED_SERVER_SECURID_CALLBACK,
  81   GSASL_NEED_SERVER_SERVICE_CALLBACK,
  82   GSASL_NEED_SERVER_GSSAPI_CALLBACK,
  83   GSASL_SECURID_SERVER_NEED_ADDITIONAL_PASSCODE,
  84   GSASL_SECURID_SERVER_NEED_NEW_PIN,
  85   GSASL_UNICODE_NORMALIZATION_ERROR,
  86   GSASL_MECHANISM_PARSE_ERROR,
  87   GSASL_AUTHENTICATION_ERROR,
  88   GSASL_CANNOT_GET_CTX,
  89   GSASL_NO_MORE_REALMS
  90 };
  91
  92 /* Quality of Protection types, used by DIGEST-MD5 */
  93 enum Gsasl_qop {
  94   GSASL_QOP_AUTH = 1,
  95   GSASL_QOP_AUTH_INT = 2,
  96   GSASL_QOP_AUTH_CONF = 4
  97 };
  98 typedef enum Gsasl_qop Gsasl_qop;
  99
 100 /* Cipher types, used by DIGEST-MD5 */
 101 enum Gsasl_cipher {
 102   GSASL_CIPHER_DES = 1,
 103   GSASL_CIPHER_3DES = 2,
 104   GSASL_CIPHER_RC4 = 4,
 105   GSASL_CIPHER_RC4_40 = 8,
 106   GSASL_CIPHER_RC4_56 = 16,
 107   GSASL_CIPHER_AES = 32
 108 };
 109 typedef enum Gsasl_cipher Gsasl_cipher;
 110
 111 /* Library handles */
 112 typedef struct Gsasl_ctx Gsasl_ctx;
 113 typedef struct Gsasl_session_ctx Gsasl_session_ctx;
 114
 115 /* Library entry and exit points: version.c, init.c, done.c */
 116 extern int gsasl_init (Gsasl_ctx **ctx);
 117 extern void gsasl_done (Gsasl_ctx *ctx);
 118 extern const char *gsasl_check_version (const char *req_version);
 119
 120 /* Callback handling */
 121 extern void gsasl_application_data_set (Gsasl_ctx *ctx,
 122                                         void *application_data);
 123 extern void *gsasl_application_data_get (Gsasl_ctx *ctx);
 124
 125 /* Mechanism handling: listmech.c, supportp.c, suggest.c */
 126 extern int gsasl_client_listmech (Gsasl_ctx *ctx, char *out, size_t *outlen);
 127 extern int gsasl_client_support_p (Gsasl_ctx *ctx, const char *name);
 128 extern const char *gsasl_client_suggest_mechanism (Gsasl_ctx *ctx,
 129                                                    const char *mechlist);
 130
 131 extern int gsasl_server_listmech (Gsasl_ctx *ctx, char *out, size_t *outlen);
 132 extern int gsasl_server_support_p (Gsasl_ctx *ctx, const char *name);
 133 extern const char *gsasl_server_suggest_mechanism (Gsasl_ctx *ctx,
 134                                                    const char *mechlist);
 135
 136 /* Authentication functions: xstart.c, xstep.c, xfinish.c */
 137 extern int gsasl_client_start (Gsasl_ctx *ctx, const char *mech,
 138                                Gsasl_session_ctx **cctx);
 139 extern int gsasl_client_step (Gsasl_session_ctx *xctx,
 140                               const char *input, size_t input_len,
 141                               char *output, size_t *output_len);
 142 extern int gsasl_client_step_base64 (Gsasl_session_ctx *xctx,
 143                                      const char *b64input,
 144                                      char *b64output,
 145                                      size_t b64output_len);
 146 extern void gsasl_client_finish (Gsasl_session_ctx *xctx);
 147 extern int gsasl_server_start (Gsasl_ctx *ctx, const char *mech,
 148                                Gsasl_session_ctx **sctx);
 149 extern int gsasl_server_step (Gsasl_session_ctx *xctx,
 150                               const char *input, size_t input_len,
 151                               char *output, size_t *output_len);
 152 extern int gsasl_server_step_base64 (Gsasl_session_ctx *xctx,
 153                                      const char *b64input,
 154                                      char *b64output,
 155                                      size_t b64output_len);
 156 extern void gsasl_server_finish (Gsasl_session_ctx *xctx);
 157
 158 /* Error handling: error.c */
 159 extern const char *gsasl_strerror (int err);
 160
 161 /* Utilities: base64.c, hexdump.c, md5pwd.c */
 162 extern int gsasl_base64_encode (unsigned char const *src,
 163                                 size_t srclength,
 164                                 char *target,
 165                                 size_t targsize);
 166 extern int gsasl_base64_decode (char const *src,
 167                                 unsigned char *target,
 168                                 size_t targsize);
 169 extern void gsasl_hexdump (FILE *fh, const char *buffer, size_t len);
 170 extern int gsasl_md5pwd_get_password (const char *filename,
 171                                       const char *username,
 172                                       char *key,
 173                                       size_t *keylen);
 174 extern char *gsasl_utf8_nfkc_normalize (const char *str,
 175                                         int len);
 176
 177 /* Callback prototypes */
 178 typedef int (*Gsasl_client_callback_anonymous) (Gsasl_session_ctx *ctx,
 179                                                 char *out,
 180                                                 size_t *outlen);
 181 typedef int (*Gsasl_client_callback_authentication_id) (Gsasl_session_ctx *ctx,
 182                                                         char *out,
 183                                                         size_t *outlen);
 184 typedef int (*Gsasl_client_callback_authorization_id) (Gsasl_session_ctx *ctx,
 185                                                        char *out,
 186                                                        size_t *outlen);
 187 typedef int (*Gsasl_client_callback_password) (Gsasl_session_ctx *ctx,
 188                                                char *out,
 189                                                size_t *outlen);
 190 typedef int (*Gsasl_client_callback_passcode) (Gsasl_session_ctx *ctx,
 191                                                char *out,
 192                                                size_t *outlen);
 193 typedef int (*Gsasl_client_callback_pin) (Gsasl_session_ctx *ctx,
 194                                           char *suggestion,
 195                                           char *out,
 196                                           size_t *outlen);
 197 typedef int (*Gsasl_client_callback_service) (Gsasl_session_ctx *ctx,
 198                                               char *service,
 199                                               size_t *servicelen,
 200                                               char *hostname,
 201                                               size_t *hostnamelen,
 202                                               char *servicename,
 203                                               size_t *servicenamelen);
 204 typedef Gsasl_qop (*Gsasl_client_callback_qop) (Gsasl_session_ctx *ctx,
 205                                                 Gsasl_qop serverqops);
 206 typedef int (*Gsasl_client_callback_maxbuf) (Gsasl_session_ctx *ctx,
 207                                              int servermaxbuf);
 208 typedef int (*Gsasl_server_callback_retrieve) (Gsasl_session_ctx *ctx,
 209                                                char *authentication_id,
 210                                                char *authorization_id,
 211                                                char *realm,
 212                                                char *key,
 213                                                size_t *keylen);
 214 typedef int (*Gsasl_server_callback_validate) (Gsasl_session_ctx *ctx,
 215                                                char *authorization_id,
 216                                                char *authentication_id,
 217                                                char *password);
 218 typedef int (*Gsasl_server_callback_gssapi) (Gsasl_session_ctx *ctx,
 219                                              char *clientname,
 220                                              char *authentication_id);
 221 typedef int (*Gsasl_server_callback_securid) (Gsasl_session_ctx *ctx,
 222                                               char *authentication_id,
 223                                               char *authorization_id,
 224                                               char *passcode,
 225                                               char *pin,
 226                                               char *suggestpin,
 227                                               size_t *suggestpinlen);
 228 typedef int (*Gsasl_server_callback_cram_md5) (Gsasl_session_ctx *ctx,
 229                                                char *username,
 230                                                char *challenge,
 231                                                char *response);
 232 typedef int (*Gsasl_server_callback_digest_md5) (Gsasl_session_ctx *ctx,
 233                                                  unsigned char *username,
 234                                                  unsigned char *realm,
 235                                                  unsigned char *secrethash);
 236 typedef int (*Gsasl_server_callback_service) (Gsasl_session_ctx *ctx,
 237                                               char *service,
 238                                               size_t *servicelen,
 239                                               char *hostname,
 240                                               size_t *hostnamelen);
 241 typedef int (*Gsasl_server_callback_external) (Gsasl_session_ctx *ctx);
 242 typedef int (*Gsasl_server_callback_anonymous) (Gsasl_session_ctx *ctx,
 243                                                 const char *token);
 244 typedef int (*Gsasl_server_callback_realm) (Gsasl_session_ctx *ctx,
 245                                             char *out,
 246                                             size_t *outlen,
 247                                             size_t nth);
 248 typedef Gsasl_qop (*Gsasl_server_callback_qop) (Gsasl_session_ctx *ctx);
 249 typedef int (*Gsasl_server_callback_maxbuf) (Gsasl_session_ctx *ctx);
 250 typedef Gsasl_cipher (*Gsasl_server_callback_cipher) (Gsasl_session_ctx *ctx);
 251
 252 /* Client callbacks */
 253 extern Gsasl_ctx *gsasl_client_ctx_get (Gsasl_session_ctx *cctx);
 254
 255 extern void gsasl_client_application_data_set (Gsasl_session_ctx *xctx,
 256                                                void *application_data);
 257 extern void *gsasl_client_application_data_get (Gsasl_session_ctx *ctx);
 258
 259 extern void gsasl_client_callback_authorization_id_set (Gsasl_ctx *ctx,
 260                                 Gsasl_client_callback_authorization_id cb);
 261 extern Gsasl_client_callback_authorization_id
 262         gsasl_client_callback_authorization_id_get (Gsasl_ctx *ctx);
 263
 264 extern void gsasl_client_callback_authentication_id_set (Gsasl_ctx *ctx,
 265                                 Gsasl_client_callback_authentication_id cb);
 266 extern Gsasl_client_callback_authentication_id
 267         gsasl_client_callback_authentication_id_get (Gsasl_ctx *ctx);
 268
 269 extern void gsasl_client_callback_anonymous_set (Gsasl_ctx *ctx,
 270                                 Gsasl_client_callback_anonymous cb);
 271 extern Gsasl_client_callback_anonymous
 272         gsasl_client_callback_anonymous_get (Gsasl_ctx *ctx);
 273
 274 extern void gsasl_client_callback_password_set (Gsasl_ctx *ctx,
 275                                 Gsasl_client_callback_password cb);
 276 extern Gsasl_client_callback_password
 277         gsasl_client_callback_password_get (Gsasl_ctx *ctx);
 278
 279 extern void gsasl_client_callback_passcode_set (Gsasl_ctx *ctx,
 280                                 Gsasl_client_callback_passcode cb);
 281 extern Gsasl_client_callback_passcode
 282         gsasl_client_callback_passcode_get (Gsasl_ctx *ctx);
 283
 284 extern void gsasl_client_callback_pin_set (Gsasl_ctx *ctx,
 285                                            Gsasl_client_callback_pin cb);
 286 extern Gsasl_client_callback_pin
 287         gsasl_client_callback_pin_get (Gsasl_ctx *ctx);
 288
 289 extern void gsasl_client_callback_service_set (Gsasl_ctx *ctx,
 290                                            Gsasl_client_callback_service cb);
 291 extern Gsasl_client_callback_service
 292         gsasl_client_callback_service_get (Gsasl_ctx *ctx);
 293
 294 extern void gsasl_client_callback_qop_set (Gsasl_ctx *ctx,
 295                                            Gsasl_client_callback_qop cb);
 296 extern Gsasl_client_callback_qop
 297         gsasl_client_callback_qop_get (Gsasl_ctx *ctx);
 298
 299 extern void gsasl_client_callback_maxbuf_set (Gsasl_ctx *ctx,
 300                                               Gsasl_client_callback_maxbuf cb);
 301 extern Gsasl_client_callback_maxbuf
 302         gsasl_client_callback_maxbuf_get (Gsasl_ctx *ctx);
 303
 304 /* Server callbacks */
 305 extern Gsasl_ctx *gsasl_server_ctx_get (Gsasl_session_ctx *sctx);
 306
 307 extern void gsasl_server_application_data_set (Gsasl_session_ctx *xctx,
 308                                                void *application_data);
 309 extern void *gsasl_server_application_data_get (Gsasl_session_ctx *ctx);
 310
 311 extern void gsasl_server_callback_validate_set (Gsasl_ctx *ctx,
 312                                      Gsasl_server_callback_validate cb);
 313 extern Gsasl_server_callback_validate
 314         gsasl_server_callback_validate_get (Gsasl_ctx *ctx);
 315
 316 extern void gsasl_server_callback_retrieve_set (Gsasl_ctx *ctx,
 317                                      Gsasl_server_callback_retrieve cb);
 318 extern Gsasl_server_callback_retrieve
 319         gsasl_server_callback_retrieve_get (Gsasl_ctx *ctx);
 320
 321 extern void gsasl_server_callback_cram_md5_set (Gsasl_ctx *ctx,
 322                                         Gsasl_server_callback_cram_md5 cb);
 323 extern Gsasl_server_callback_cram_md5
 324         gsasl_server_callback_cram_md5_get (Gsasl_ctx *ctx);
 325
 326 extern void gsasl_server_callback_digest_md5_set (Gsasl_ctx *ctx,
 327                                         Gsasl_server_callback_digest_md5 cb);
 328 extern Gsasl_server_callback_digest_md5
 329         gsasl_server_callback_digest_md5_get (Gsasl_ctx *ctx);
 330
 331 extern void gsasl_server_callback_external_set (Gsasl_ctx *ctx,
 332                                            Gsasl_server_callback_external cb);
 333 extern Gsasl_server_callback_external
 334         gsasl_server_callback_external_get (Gsasl_ctx *ctx);
 335
 336 extern void gsasl_server_callback_anonymous_set (Gsasl_ctx *ctx,
 337                                           Gsasl_server_callback_anonymous cb);
 338 extern Gsasl_server_callback_anonymous
 339         gsasl_server_callback_anonymous_get (Gsasl_ctx *ctx);
 340
 341 extern void gsasl_server_callback_realm_set (Gsasl_ctx *ctx,
 342                                              Gsasl_server_callback_realm cb);
 343 extern Gsasl_server_callback_realm
 344         gsasl_server_callback_realm_get (Gsasl_ctx *ctx);
 345
 346 extern void gsasl_server_callback_qop_set (Gsasl_ctx *ctx,
 347                                            Gsasl_server_callback_qop cb);
 348 extern Gsasl_server_callback_qop
 349         gsasl_server_callback_qop_get (Gsasl_ctx *ctx);
 350
 351 extern void gsasl_server_callback_maxbuf_set (Gsasl_ctx *ctx,
 352                                               Gsasl_server_callback_maxbuf cb);
 353 extern Gsasl_server_callback_maxbuf
 354         gsasl_server_callback_maxbuf_get (Gsasl_ctx *ctx);
 355
 356 extern void gsasl_server_callback_cipher_set (Gsasl_ctx *ctx,
 357                                               Gsasl_server_callback_cipher cb);
 358 extern Gsasl_server_callback_cipher
 359         gsasl_server_callback_cipher_get (Gsasl_ctx *ctx);
 360
 361 extern void gsasl_server_callback_securid_set (Gsasl_ctx *ctx,
 362                                              Gsasl_server_callback_securid cb);
 363 extern Gsasl_server_callback_securid
 364         gsasl_server_callback_securid_get (Gsasl_ctx *ctx);
 365
 366 extern void gsasl_server_callback_gssapi_set (Gsasl_ctx *ctx,
 367                                               Gsasl_server_callback_gssapi cb);
 368 extern Gsasl_server_callback_gssapi
 369         gsasl_server_callback_gssapi_get (Gsasl_ctx *ctx);
 370
 371 extern void gsasl_server_callback_service_set (Gsasl_ctx *ctx,
 372                                              Gsasl_server_callback_service cb);
 373 extern Gsasl_server_callback_service
 374         gsasl_server_callback_service_get (Gsasl_ctx *ctx);
 375
 376 #ifdef __cplusplus
 377 }
 378 #endif
 379
 380 #endif /* _GSASL_H */