gsasl  1.8.0
gsasl.h
Go to the documentation of this file.
00001 /* gsasl.h --- Header file for GNU SASL Library.
00002  * Copyright (C) 2002-2012 Simon Josefsson
00003  *
00004  * This file is part of GNU SASL Library.
00005  *
00006  * GNU SASL Library is free software; you can redistribute it and/or
00007  * modify it under the terms of the GNU Lesser General Public License
00008  * as published by the Free Software Foundation; either version 2.1 of
00009  * the License, or (at your option) any later version.
00010  *
00011  * GNU SASL Library is distributed in the hope that it will be useful,
00012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00014  * Lesser General Public License for more details.
00015  *
00016  * You should have received a copy of the GNU Lesser General Public
00017  * License License along with GNU SASL Library; if not, write to the
00018  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
00019  * Boston, MA 02110-1301, USA.
00020  *
00021  */
00022 
00023 #ifndef GSASL_H
00024 #define GSASL_H
00025 
00026 #include <stdio.h>              /* FILE */
00027 #include <stddef.h>             /* size_t */
00028 #include <unistd.h>             /* ssize_t */
00029 
00030 #ifndef GSASL_API
00031 #if defined GSASL_BUILDING && defined HAVE_VISIBILITY && HAVE_VISIBILITY
00032 #define GSASL_API __attribute__((__visibility__("default")))
00033 #elif defined GSASL_BUILDING && defined _MSC_VER && ! defined GSASL_STATIC
00034 #define GSASL_API __declspec(dllexport)
00035 #elif defined _MSC_VER && ! defined GSASL_STATIC
00036 #define GSASL_API __declspec(dllimport)
00037 #else
00038 #define GSASL_API
00039 #endif
00040 #endif
00041 
00042 #ifdef __cplusplus
00043 extern "C"
00044 {
00045 #endif
00046 
00054 #define GSASL_VERSION "1.8.0"
00055 
00065 #define GSASL_VERSION_MAJOR 1
00066 
00076 #define GSASL_VERSION_MINOR 8
00077 
00087 #define GSASL_VERSION_PATCH 0
00088 
00098 #define GSASL_VERSION_NUMBER 0x010800
00099 
00100   /* RFC 2222: SASL mechanisms are named by strings, from 1 to 20
00101    * characters in length, consisting of upper-case letters, digits,
00102    * hyphens, and/or underscores.  SASL mechanism names must be
00103    * registered with the IANA.
00104    */
00105   enum
00106   {
00107     GSASL_MIN_MECHANISM_SIZE = 1,
00108     GSASL_MAX_MECHANISM_SIZE = 20
00109   };
00110   extern GSASL_API const char *GSASL_VALID_MECHANISM_CHARACTERS;
00111 
00169   typedef enum
00170   {
00171     GSASL_OK = 0,
00172     GSASL_NEEDS_MORE = 1,
00173     GSASL_UNKNOWN_MECHANISM = 2,
00174     GSASL_MECHANISM_CALLED_TOO_MANY_TIMES = 3,
00175     GSASL_MALLOC_ERROR = 7,
00176     GSASL_BASE64_ERROR = 8,
00177     GSASL_CRYPTO_ERROR = 9,
00178     GSASL_SASLPREP_ERROR = 29,
00179     GSASL_MECHANISM_PARSE_ERROR = 30,
00180     GSASL_AUTHENTICATION_ERROR = 31,
00181     GSASL_INTEGRITY_ERROR = 33,
00182     GSASL_NO_CLIENT_CODE = 35,
00183     GSASL_NO_SERVER_CODE = 36,
00184     GSASL_NO_CALLBACK = 51,
00185     GSASL_NO_ANONYMOUS_TOKEN = 52,
00186     GSASL_NO_AUTHID = 53,
00187     GSASL_NO_AUTHZID = 54,
00188     GSASL_NO_PASSWORD = 55,
00189     GSASL_NO_PASSCODE = 56,
00190     GSASL_NO_PIN = 57,
00191     GSASL_NO_SERVICE = 58,
00192     GSASL_NO_HOSTNAME = 59,
00193     GSASL_NO_CB_TLS_UNIQUE = 65,
00194     GSASL_NO_SAML20_IDP_IDENTIFIER = 66,
00195     GSASL_NO_SAML20_REDIRECT_URL = 67,
00196     GSASL_NO_OPENID20_REDIRECT_URL = 68,
00197     /* Mechanism specific errors. */
00198     GSASL_GSSAPI_RELEASE_BUFFER_ERROR = 37,
00199     GSASL_GSSAPI_IMPORT_NAME_ERROR = 38,
00200     GSASL_GSSAPI_INIT_SEC_CONTEXT_ERROR = 39,
00201     GSASL_GSSAPI_ACCEPT_SEC_CONTEXT_ERROR = 40,
00202     GSASL_GSSAPI_UNWRAP_ERROR = 41,
00203     GSASL_GSSAPI_WRAP_ERROR = 42,
00204     GSASL_GSSAPI_ACQUIRE_CRED_ERROR = 43,
00205     GSASL_GSSAPI_DISPLAY_NAME_ERROR = 44,
00206     GSASL_GSSAPI_UNSUPPORTED_PROTECTION_ERROR = 45,
00207     GSASL_KERBEROS_V5_INIT_ERROR = 46,
00208     GSASL_KERBEROS_V5_INTERNAL_ERROR = 47,
00209     GSASL_SHISHI_ERROR = GSASL_KERBEROS_V5_INTERNAL_ERROR,
00210     GSASL_SECURID_SERVER_NEED_ADDITIONAL_PASSCODE = 48,
00211     GSASL_SECURID_SERVER_NEED_NEW_PIN = 49,
00212     GSASL_GSSAPI_ENCAPSULATE_TOKEN_ERROR = 60,
00213     GSASL_GSSAPI_DECAPSULATE_TOKEN_ERROR = 61,
00214     GSASL_GSSAPI_INQUIRE_MECH_FOR_SASLNAME_ERROR = 62,
00215     GSASL_GSSAPI_TEST_OID_SET_MEMBER_ERROR = 63,
00216     GSASL_GSSAPI_RELEASE_OID_SET_ERROR = 64
00217       /* When adding new values, note that integers are not necessarily
00218          assigned monotonously increasingly. */
00219   } Gsasl_rc;
00220 
00233   typedef enum
00234   {
00235     GSASL_QOP_AUTH = 1,
00236     GSASL_QOP_AUTH_INT = 2,
00237     GSASL_QOP_AUTH_CONF = 4
00238   } Gsasl_qop;
00239 
00253   typedef enum
00254   {
00255     GSASL_CIPHER_DES = 1,
00256     GSASL_CIPHER_3DES = 2,
00257     GSASL_CIPHER_RC4 = 4,
00258     GSASL_CIPHER_RC4_40 = 8,
00259     GSASL_CIPHER_RC4_56 = 16,
00260     GSASL_CIPHER_AES = 32
00261   } Gsasl_cipher;
00262 
00270   typedef enum
00271   {
00272     GSASL_ALLOW_UNASSIGNED = 1
00273   } Gsasl_saslprep_flags;
00274 
00280   typedef struct Gsasl Gsasl;
00281 
00287   typedef struct Gsasl_session Gsasl_session;
00288 
00329   typedef enum
00330   {
00331     /* Information properties, e.g., username. */
00332     GSASL_AUTHID = 1,
00333     GSASL_AUTHZID = 2,
00334     GSASL_PASSWORD = 3,
00335     GSASL_ANONYMOUS_TOKEN = 4,
00336     GSASL_SERVICE = 5,
00337     GSASL_HOSTNAME = 6,
00338     GSASL_GSSAPI_DISPLAY_NAME = 7,
00339     GSASL_PASSCODE = 8,
00340     GSASL_SUGGESTED_PIN = 9,
00341     GSASL_PIN = 10,
00342     GSASL_REALM = 11,
00343     GSASL_DIGEST_MD5_HASHED_PASSWORD = 12,
00344     GSASL_QOPS = 13,
00345     GSASL_QOP = 14,
00346     GSASL_SCRAM_ITER = 15,
00347     GSASL_SCRAM_SALT = 16,
00348     GSASL_SCRAM_SALTED_PASSWORD = 17,
00349     GSASL_CB_TLS_UNIQUE = 18,
00350     GSASL_SAML20_IDP_IDENTIFIER = 19,
00351     GSASL_SAML20_REDIRECT_URL = 20,
00352     GSASL_OPENID20_REDIRECT_URL = 21,
00353     GSASL_OPENID20_OUTCOME_DATA = 22,
00354     /* Client callbacks. */
00355     GSASL_SAML20_AUTHENTICATE_IN_BROWSER = 250,
00356     GSASL_OPENID20_AUTHENTICATE_IN_BROWSER = 251,
00357     /* Server validation callback properties. */
00358     GSASL_VALIDATE_SIMPLE = 500,
00359     GSASL_VALIDATE_EXTERNAL = 501,
00360     GSASL_VALIDATE_ANONYMOUS = 502,
00361     GSASL_VALIDATE_GSSAPI = 503,
00362     GSASL_VALIDATE_SECURID = 504,
00363     GSASL_VALIDATE_SAML20 = 505,
00364     GSASL_VALIDATE_OPENID20 = 506
00365   } Gsasl_property;
00366 
00391   typedef int (*Gsasl_callback_function) (Gsasl * ctx, Gsasl_session * sctx,
00392                                           Gsasl_property prop);
00393 
00394   /* Library entry and exit points: version.c, init.c, done.c */
00395   extern GSASL_API int gsasl_init (Gsasl ** ctx);
00396   extern GSASL_API void gsasl_done (Gsasl * ctx);
00397   extern GSASL_API const char *gsasl_check_version (const char *req_version);
00398 
00399   /* Callback handling: callback.c */
00400   extern GSASL_API void gsasl_callback_set (Gsasl * ctx,
00401                                             Gsasl_callback_function cb);
00402   extern GSASL_API int gsasl_callback (Gsasl * ctx, Gsasl_session * sctx,
00403                                        Gsasl_property prop);
00404 
00405   extern GSASL_API void gsasl_callback_hook_set (Gsasl * ctx, void *hook);
00406   extern GSASL_API void *gsasl_callback_hook_get (Gsasl * ctx);
00407 
00408   extern GSASL_API void gsasl_session_hook_set (Gsasl_session * sctx,
00409                                                 void *hook);
00410   extern GSASL_API void *gsasl_session_hook_get (Gsasl_session * sctx);
00411 
00412   /* Property handling: property.c */
00413   extern GSASL_API void gsasl_property_set (Gsasl_session * sctx,
00414                                             Gsasl_property prop,
00415                                             const char *data);
00416   extern GSASL_API void gsasl_property_set_raw (Gsasl_session * sctx,
00417                                                 Gsasl_property prop,
00418                                                 const char *data, size_t len);
00419   extern GSASL_API const char *gsasl_property_get (Gsasl_session * sctx,
00420                                                    Gsasl_property prop);
00421   extern GSASL_API const char *gsasl_property_fast (Gsasl_session * sctx,
00422                                                     Gsasl_property prop);
00423 
00424   /* Mechanism handling: listmech.c, supportp.c, suggest.c */
00425   extern GSASL_API int gsasl_client_mechlist (Gsasl * ctx, char **out);
00426   extern GSASL_API int gsasl_client_support_p (Gsasl * ctx, const char *name);
00427   extern GSASL_API const char *gsasl_client_suggest_mechanism (Gsasl * ctx,
00428                                                                const char
00429                                                                *mechlist);
00430 
00431   extern GSASL_API int gsasl_server_mechlist (Gsasl * ctx, char **out);
00432   extern GSASL_API int gsasl_server_support_p (Gsasl * ctx, const char *name);
00433 
00434   /* Authentication functions: xstart.c, xstep.c, xfinish.c */
00435   extern GSASL_API int gsasl_client_start (Gsasl * ctx, const char *mech,
00436                                            Gsasl_session ** sctx);
00437   extern GSASL_API int gsasl_server_start (Gsasl * ctx, const char *mech,
00438                                            Gsasl_session ** sctx);
00439   extern GSASL_API int gsasl_step (Gsasl_session * sctx,
00440                                    const char *input, size_t input_len,
00441                                    char **output, size_t * output_len);
00442   extern GSASL_API int gsasl_step64 (Gsasl_session * sctx,
00443                                      const char *b64input, char **b64output);
00444   extern GSASL_API void gsasl_finish (Gsasl_session * sctx);
00445 
00446   /* Session functions: xcode.c, mechname.c */
00447   extern GSASL_API int gsasl_encode (Gsasl_session * sctx,
00448                                      const char *input, size_t input_len,
00449                                      char **output, size_t * output_len);
00450   extern GSASL_API int gsasl_decode (Gsasl_session * sctx,
00451                                      const char *input, size_t input_len,
00452                                      char **output, size_t * output_len);
00453   extern GSASL_API const char *gsasl_mechanism_name (Gsasl_session * sctx);
00454 
00455   /* Error handling: error.c */
00456   extern GSASL_API const char *gsasl_strerror (int err);
00457   extern GSASL_API const char *gsasl_strerror_name (int err);
00458 
00459   /* Internationalized string processing: stringprep.c */
00460   extern GSASL_API int gsasl_saslprep (const char *in,
00461                                        Gsasl_saslprep_flags flags, char **out,
00462                                        int *stringpreprc);
00463 
00464   /* Utilities: base64.c, md5pwd.c, crypto.c */
00465   extern GSASL_API int gsasl_simple_getpass (const char *filename,
00466                                              const char *username,
00467                                              char **key);
00468   extern GSASL_API int gsasl_base64_to (const char *in, size_t inlen,
00469                                         char **out, size_t * outlen);
00470   extern GSASL_API int gsasl_base64_from (const char *in, size_t inlen,
00471                                           char **out, size_t * outlen);
00472   extern GSASL_API int gsasl_nonce (char *data, size_t datalen);
00473   extern GSASL_API int gsasl_random (char *data, size_t datalen);
00474   extern GSASL_API int gsasl_md5 (const char *in, size_t inlen,
00475                                   char *out[16]);
00476   extern GSASL_API int gsasl_hmac_md5 (const char *key, size_t keylen,
00477                                        const char *in, size_t inlen,
00478                                        char *outhash[16]);
00479   extern GSASL_API int gsasl_sha1 (const char *in, size_t inlen,
00480                                    char *out[20]);
00481   extern GSASL_API int gsasl_hmac_sha1 (const char *key, size_t keylen,
00482                                         const char *in, size_t inlen,
00483                                         char *outhash[20]);
00484   extern GSASL_API void gsasl_free (void *ptr);
00485 
00486   /* Get the mechanism API. */
00487 #include <gsasl-mech.h>
00488 
00489 #ifndef GSASL_NO_OBSOLETE
00490   /* For compatibility with earlier versions. */
00491 #include <gsasl-compat.h>
00492 #endif
00493 
00494 #ifdef __cplusplus
00495 }
00496 #endif
00497 
00498 #endif                          /* GSASL_H */