gsasl.h

Go to the documentation of this file.
00001 /* gsasl.h --- Header file for GNU SASL Library.
00002  * Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008  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 /* GSASL Windows DLL.  Only needed when this file is used in Visual
00031    Studio.  Export and import happens automatically in MinGW. */
00032 #ifndef GSASL_API
00033 # if defined _MSC_VER && !defined GSASL_STATIC
00034 #  ifdef GSASL_EXPORTS
00035 #   define GSASL_API __declspec(dllexport)
00036 #  else
00037 #   define GSASL_API __declspec(dllimport)
00038 #  endif
00039 # else
00040 #  define GSASL_API
00041 # endif
00042 #endif
00043 
00044 # ifdef __cplusplus
00045 extern "C"
00046 {
00047 # endif
00048 
00056 # define GSASL_VERSION "0.2.29"
00057 
00058   /* RFC 2222: SASL mechanisms are named by strings, from 1 to 20
00059    * characters in length, consisting of upper-case letters, digits,
00060    * hyphens, and/or underscores.  SASL mechanism names must be
00061    * registered with the IANA.
00062    */
00063   enum
00064   {
00065     GSASL_MIN_MECHANISM_SIZE = 1,
00066     GSASL_MAX_MECHANISM_SIZE = 20
00067   };
00068   extern GSASL_API const char *GSASL_VALID_MECHANISM_CHARACTERS;
00069 
00070   /* Error codes */
00071   typedef enum
00072   {
00073     GSASL_OK = 0,
00074     GSASL_NEEDS_MORE = 1,
00075     GSASL_UNKNOWN_MECHANISM = 2,
00076     GSASL_MECHANISM_CALLED_TOO_MANY_TIMES = 3,
00077     GSASL_MALLOC_ERROR = 7,
00078     GSASL_BASE64_ERROR = 8,
00079     GSASL_CRYPTO_ERROR = 9,
00080     GSASL_SASLPREP_ERROR = 29,
00081     GSASL_MECHANISM_PARSE_ERROR = 30,
00082     GSASL_AUTHENTICATION_ERROR = 31,
00083     GSASL_INTEGRITY_ERROR = 33,
00084     GSASL_NO_CLIENT_CODE = 35,
00085     GSASL_NO_SERVER_CODE = 36,
00086     GSASL_NO_CALLBACK = 51,
00087     GSASL_NO_ANONYMOUS_TOKEN = 52,
00088     GSASL_NO_AUTHID = 53,
00089     GSASL_NO_AUTHZID = 54,
00090     GSASL_NO_PASSWORD = 55,
00091     GSASL_NO_PASSCODE = 56,
00092     GSASL_NO_PIN = 57,
00093     GSASL_NO_SERVICE = 58,
00094     GSASL_NO_HOSTNAME = 59,
00095     /* Mechanism specific errors. */
00096     GSASL_GSSAPI_RELEASE_BUFFER_ERROR = 37,
00097     GSASL_GSSAPI_IMPORT_NAME_ERROR = 38,
00098     GSASL_GSSAPI_INIT_SEC_CONTEXT_ERROR = 39,
00099     GSASL_GSSAPI_ACCEPT_SEC_CONTEXT_ERROR = 40,
00100     GSASL_GSSAPI_UNWRAP_ERROR = 41,
00101     GSASL_GSSAPI_WRAP_ERROR = 42,
00102     GSASL_GSSAPI_ACQUIRE_CRED_ERROR = 43,
00103     GSASL_GSSAPI_DISPLAY_NAME_ERROR = 44,
00104     GSASL_GSSAPI_UNSUPPORTED_PROTECTION_ERROR = 45,
00105     GSASL_KERBEROS_V5_INIT_ERROR = 46,
00106     GSASL_KERBEROS_V5_INTERNAL_ERROR = 47,
00107     GSASL_SHISHI_ERROR = GSASL_KERBEROS_V5_INTERNAL_ERROR,
00108     GSASL_SECURID_SERVER_NEED_ADDITIONAL_PASSCODE = 48,
00109     GSASL_SECURID_SERVER_NEED_NEW_PIN = 49
00110   } Gsasl_rc;
00111 
00112   /* Quality of Protection types, used by DIGEST-MD5 */
00113   typedef enum
00114   {
00115     GSASL_QOP_AUTH = 1,
00116     GSASL_QOP_AUTH_INT = 2,
00117     GSASL_QOP_AUTH_CONF = 4
00118   } Gsasl_qop;
00119 
00120   /* Cipher types, used by DIGEST-MD5 */
00121   typedef enum
00122   {
00123     GSASL_CIPHER_DES = 1,
00124     GSASL_CIPHER_3DES = 2,
00125     GSASL_CIPHER_RC4 = 4,
00126     GSASL_CIPHER_RC4_40 = 8,
00127     GSASL_CIPHER_RC4_56 = 16,
00128     GSASL_CIPHER_AES = 32
00129   } Gsasl_cipher;
00130 
00131   /* SASLprep flags, see gsasl_saslprep(). */
00132   typedef enum
00133   {
00134     GSASL_ALLOW_UNASSIGNED = 1
00135   } Gsasl_saslprep_flags;
00136 
00137   /* Library handles */
00138   typedef struct Gsasl Gsasl;
00139   typedef struct Gsasl_session Gsasl_session;
00140 
00141   /* Callback/property types. */
00142   typedef enum
00143   {
00144     /* Information properties, e.g., username. */
00145     GSASL_AUTHID = 1,
00146     GSASL_AUTHZID = 2,
00147     GSASL_PASSWORD = 3,
00148     GSASL_ANONYMOUS_TOKEN = 4,
00149     GSASL_SERVICE = 5,
00150     GSASL_HOSTNAME = 6,
00151     GSASL_GSSAPI_DISPLAY_NAME = 7,
00152     GSASL_PASSCODE = 8,
00153     GSASL_SUGGESTED_PIN = 9,
00154     GSASL_PIN = 10,
00155     GSASL_REALM = 11,
00156     GSASL_DIGEST_MD5_HASHED_PASSWORD = 12,
00157     /* Server validation callback properties. */
00158     GSASL_VALIDATE_SIMPLE = 500,
00159     GSASL_VALIDATE_EXTERNAL = 501,
00160     GSASL_VALIDATE_ANONYMOUS = 502,
00161     GSASL_VALIDATE_GSSAPI = 503,
00162     GSASL_VALIDATE_SECURID = 504
00163   } Gsasl_property;
00164 
00189   typedef int (*Gsasl_callback_function) (Gsasl * ctx, Gsasl_session * sctx,
00190                                           Gsasl_property prop);
00191 
00192   /* Library entry and exit points: version.c, init.c, done.c */
00193   extern GSASL_API int gsasl_init (Gsasl ** ctx);
00194   extern GSASL_API void gsasl_done (Gsasl * ctx);
00195   extern GSASL_API const char *gsasl_check_version (const char *req_version);
00196 
00197   /* Callback handling: callback.c */
00198   extern GSASL_API void gsasl_callback_set (Gsasl * ctx,
00199                                             Gsasl_callback_function cb);
00200   extern GSASL_API int gsasl_callback (Gsasl * ctx, Gsasl_session * sctx,
00201                                        Gsasl_property prop);
00202 
00203   extern GSASL_API void gsasl_callback_hook_set (Gsasl * ctx, void *hook);
00204   extern GSASL_API void *gsasl_callback_hook_get (Gsasl * ctx);
00205 
00206   extern GSASL_API void gsasl_session_hook_set (Gsasl_session * sctx,
00207                                                 void *hook);
00208   extern GSASL_API void *gsasl_session_hook_get (Gsasl_session * sctx);
00209 
00210   /* Property handling: property.c */
00211   extern GSASL_API void gsasl_property_set (Gsasl_session * sctx,
00212                                             Gsasl_property prop,
00213                                             const char *data);
00214   extern GSASL_API void gsasl_property_set_raw (Gsasl_session * sctx,
00215                                                 Gsasl_property prop,
00216                                                 const char *data, size_t len);
00217   extern GSASL_API const char *gsasl_property_get (Gsasl_session * sctx,
00218                                                    Gsasl_property prop);
00219   extern GSASL_API const char *gsasl_property_fast (Gsasl_session * sctx,
00220                                                     Gsasl_property prop);
00221 
00222   /* Mechanism handling: listmech.c, supportp.c, suggest.c */
00223   extern GSASL_API int gsasl_client_mechlist (Gsasl * ctx, char **out);
00224   extern GSASL_API int gsasl_client_support_p (Gsasl * ctx, const char *name);
00225   extern GSASL_API const char *gsasl_client_suggest_mechanism (Gsasl * ctx,
00226                                                                const char
00227                                                                *mechlist);
00228 
00229   extern GSASL_API int gsasl_server_mechlist (Gsasl * ctx, char **out);
00230   extern GSASL_API int gsasl_server_support_p (Gsasl * ctx, const char *name);
00231 
00232   /* Authentication functions: xstart.c, xstep.c, xfinish.c */
00233   extern GSASL_API int gsasl_client_start (Gsasl * ctx, const char *mech,
00234                                            Gsasl_session ** sctx);
00235   extern GSASL_API int gsasl_server_start (Gsasl * ctx, const char *mech,
00236                                            Gsasl_session ** sctx);
00237   extern GSASL_API int gsasl_step (Gsasl_session * sctx,
00238                                    const char *input, size_t input_len,
00239                                    char **output, size_t * output_len);
00240   extern GSASL_API int gsasl_step64 (Gsasl_session * sctx,
00241                                      const char *b64input, char **b64output);
00242   extern GSASL_API void gsasl_finish (Gsasl_session * sctx);
00243 
00244   /* Session functions: xcode.c, mechname.c */
00245   extern GSASL_API int gsasl_encode (Gsasl_session * sctx,
00246                                      const char *input, size_t input_len,
00247                                      char **output, size_t * output_len);
00248   extern GSASL_API int gsasl_decode (Gsasl_session * sctx,
00249                                      const char *input, size_t input_len,
00250                                      char **output, size_t * output_len);
00251   extern GSASL_API const char *gsasl_mechanism_name (Gsasl_session * sctx);
00252 
00253   /* Error handling: error.c */
00254   extern GSASL_API const char *gsasl_strerror (int err);
00255   extern GSASL_API const char *gsasl_strerror_name (int err);
00256 
00257   /* Internationalized string processing: stringprep.c */
00258   extern GSASL_API int gsasl_saslprep (const char *in,
00259                                        Gsasl_saslprep_flags flags, char **out,
00260                                        int *stringpreprc);
00261 
00262   /* Utilities: base64.c, md5pwd.c, crypto.c */
00263   extern GSASL_API int gsasl_simple_getpass (const char *filename,
00264                                              const char *username,
00265                                              char **key);
00266   extern GSASL_API int gsasl_base64_to (const char *in, size_t inlen,
00267                                         char **out, size_t * outlen);
00268   extern GSASL_API int gsasl_base64_from (const char *in, size_t inlen,
00269                                           char **out, size_t * outlen);
00270   extern GSASL_API int gsasl_nonce (char *data, size_t datalen);
00271   extern GSASL_API int gsasl_random (char *data, size_t datalen);
00272   extern GSASL_API int gsasl_md5 (const char *in, size_t inlen,
00273                                   char *out[16]);
00274   extern GSASL_API int gsasl_hmac_md5 (const char *key, size_t keylen,
00275                                        const char *in, size_t inlen,
00276                                        char *outhash[16]);
00277   extern GSASL_API void gsasl_free (void *ptr);
00278 
00279   /* Get the mechanism API. */
00280 # include <gsasl-mech.h>
00281 
00282 #ifndef GSASL_NO_OBSOLETE
00283   /* For compatibility with earlier versions. */
00284 # include <gsasl-compat.h>
00285 #endif
00286 
00287 # ifdef __cplusplus
00288 }
00289 # endif
00290 
00291 #endif                          /* GSASL_H */