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