gsasl.h

Go to the documentation of this file.

/* gsasl.h --- Header file for GNU SASL Library.
 * Copyright (C) 2002-2025 Simon Josefsson
 *
 * This file is part of GNU SASL Library.
 *
 * GNU SASL Library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * GNU SASL Library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with GNU SASL Library; if not, see
 * <https://www.gnu.org/licenses/>.
 *
 */
 
#ifndef GSASL_H
# define GSASL_H
 
# include <stdio.h>             /* FILE */
# include <stddef.h>            /* size_t */
# include <sys/types.h>         /* ssize_t */
 
/* Get version symbols. */
# include <gsasl-version.h>
 
# ifndef _GSASL_API
#  if defined GSASL_BUILDING && defined HAVE_VISIBILITY && HAVE_VISIBILITY
#   define _GSASL_API __attribute__((__visibility__("default")))
#  elif defined GSASL_BUILDING && defined _MSC_VER && ! defined GSASL_STATIC
#   define _GSASL_API __declspec(dllexport)
#  elif defined _MSC_VER && ! defined GSASL_STATIC
#   define _GSASL_API __declspec(dllimport)
#  else
#   define _GSASL_API
#  endif
# endif
 
# ifdef __cplusplus
extern "C"
{
# endif
 
  typedef struct Gsasl Gsasl;
 
  typedef struct Gsasl_session Gsasl_session;
 
  typedef enum
  {
    GSASL_OK = 0,
    GSASL_NEEDS_MORE = 1,
    GSASL_UNKNOWN_MECHANISM = 2,
    GSASL_MECHANISM_CALLED_TOO_MANY_TIMES = 3,
    GSASL_MALLOC_ERROR = 7,
    GSASL_BASE64_ERROR = 8,
    GSASL_CRYPTO_ERROR = 9,
    GSASL_SASLPREP_ERROR = 29,
    GSASL_MECHANISM_PARSE_ERROR = 30,
    GSASL_AUTHENTICATION_ERROR = 31,
    GSASL_INTEGRITY_ERROR = 33,
    GSASL_NO_CLIENT_CODE = 35,
    GSASL_NO_SERVER_CODE = 36,
    GSASL_NO_CALLBACK = 51,
    GSASL_NO_ANONYMOUS_TOKEN = 52,
    GSASL_NO_AUTHID = 53,
    GSASL_NO_AUTHZID = 54,
    GSASL_NO_PASSWORD = 55,
    GSASL_NO_PASSCODE = 56,
    GSASL_NO_PIN = 57,
    GSASL_NO_SERVICE = 58,
    GSASL_NO_HOSTNAME = 59,
    GSASL_NO_CB_TLS_UNIQUE = 65,
    GSASL_NO_SAML20_IDP_IDENTIFIER = 66,
    GSASL_NO_SAML20_REDIRECT_URL = 67,
    GSASL_NO_OPENID20_REDIRECT_URL = 68,
    GSASL_NO_CB_TLS_EXPORTER = 69,
    /* Mechanism specific errors. */
    GSASL_GSSAPI_RELEASE_BUFFER_ERROR = 37,
    GSASL_GSSAPI_IMPORT_NAME_ERROR = 38,
    GSASL_GSSAPI_INIT_SEC_CONTEXT_ERROR = 39,
    GSASL_GSSAPI_ACCEPT_SEC_CONTEXT_ERROR = 40,
    GSASL_GSSAPI_UNWRAP_ERROR = 41,
    GSASL_GSSAPI_WRAP_ERROR = 42,
    GSASL_GSSAPI_ACQUIRE_CRED_ERROR = 43,
    GSASL_GSSAPI_DISPLAY_NAME_ERROR = 44,
    GSASL_GSSAPI_UNSUPPORTED_PROTECTION_ERROR = 45,
    GSASL_SECURID_SERVER_NEED_ADDITIONAL_PASSCODE = 48,
    GSASL_SECURID_SERVER_NEED_NEW_PIN = 49,
    GSASL_GSSAPI_ENCAPSULATE_TOKEN_ERROR = 60,
    GSASL_GSSAPI_DECAPSULATE_TOKEN_ERROR = 61,
    GSASL_GSSAPI_INQUIRE_MECH_FOR_SASLNAME_ERROR = 62,
    GSASL_GSSAPI_TEST_OID_SET_MEMBER_ERROR = 63,
    GSASL_GSSAPI_RELEASE_OID_SET_ERROR = 64
      /* When adding new values, note that integers are not necessarily
         assigned monotonously increasingly. */
  } Gsasl_rc;
 
  typedef enum
  {
    /* Information properties, e.g., username. */
    GSASL_AUTHID = 1,
    GSASL_AUTHZID = 2,
    GSASL_PASSWORD = 3,
    GSASL_ANONYMOUS_TOKEN = 4,
    GSASL_SERVICE = 5,
    GSASL_HOSTNAME = 6,
    GSASL_GSSAPI_DISPLAY_NAME = 7,
    GSASL_PASSCODE = 8,
    GSASL_SUGGESTED_PIN = 9,
    GSASL_PIN = 10,
    GSASL_REALM = 11,
    GSASL_DIGEST_MD5_HASHED_PASSWORD = 12,
    GSASL_QOPS = 13,
    GSASL_QOP = 14,
    GSASL_SCRAM_ITER = 15,
    GSASL_SCRAM_SALT = 16,
    GSASL_SCRAM_SALTED_PASSWORD = 17,
    GSASL_SCRAM_SERVERKEY = 23,
    GSASL_SCRAM_STOREDKEY = 24,
    GSASL_CB_TLS_UNIQUE = 18,
    GSASL_SAML20_IDP_IDENTIFIER = 19,
    GSASL_SAML20_REDIRECT_URL = 20,
    GSASL_OPENID20_REDIRECT_URL = 21,
    GSASL_OPENID20_OUTCOME_DATA = 22,
    GSASL_CB_TLS_EXPORTER = 25,
    /* Client callbacks. */
    GSASL_SAML20_AUTHENTICATE_IN_BROWSER = 250,
    GSASL_OPENID20_AUTHENTICATE_IN_BROWSER = 251,
    /* Server validation callback properties. */
    GSASL_VALIDATE_SIMPLE = 500,
    GSASL_VALIDATE_EXTERNAL = 501,
    GSASL_VALIDATE_ANONYMOUS = 502,
    GSASL_VALIDATE_GSSAPI = 503,
    GSASL_VALIDATE_SECURID = 504,
    GSASL_VALIDATE_SAML20 = 505,
    GSASL_VALIDATE_OPENID20 = 506
  } Gsasl_property;
 
  typedef int (*Gsasl_callback_function) (Gsasl * ctx, Gsasl_session * sctx,
                                          Gsasl_property prop);
 
  typedef enum
  {
    GSASL_MIN_MECHANISM_SIZE = 1,
    GSASL_MAX_MECHANISM_SIZE = 20
  } Gsasl_mechname_limits;
 
  typedef enum
  {
    GSASL_QOP_AUTH = 1,
    GSASL_QOP_AUTH_INT = 2,
    GSASL_QOP_AUTH_CONF = 4
  } Gsasl_qop;
 
  typedef enum
  {
    GSASL_ALLOW_UNASSIGNED = 1
  } Gsasl_saslprep_flags;
 
  /* Library entry and exit points: version.c, init.c, done.c */
  extern _GSASL_API int gsasl_init (Gsasl ** ctx);
  extern _GSASL_API void gsasl_done (Gsasl * ctx);
  extern _GSASL_API const char *gsasl_check_version (const char *req_version);
 
  /* Callback handling: callback.c */
  extern _GSASL_API void gsasl_callback_set (Gsasl * ctx,
                                             Gsasl_callback_function cb);
  extern _GSASL_API int gsasl_callback (Gsasl * ctx, Gsasl_session * sctx,
                                        Gsasl_property prop);
 
  extern _GSASL_API void gsasl_callback_hook_set (Gsasl * ctx, void *hook);
  extern _GSASL_API void *gsasl_callback_hook_get (Gsasl * ctx);
 
  extern _GSASL_API void gsasl_session_hook_set (Gsasl_session * sctx,
                                                 void *hook);
  extern _GSASL_API void *gsasl_session_hook_get (Gsasl_session * sctx);
 
  /* Property handling: property.c */
  extern _GSASL_API int gsasl_property_set (Gsasl_session * sctx,
                                            Gsasl_property prop,
                                            const char *data);
  extern _GSASL_API int gsasl_property_set_raw (Gsasl_session * sctx,
                                                Gsasl_property prop,
                                                const char *data, size_t len);
  extern _GSASL_API void gsasl_property_free (Gsasl_session * sctx,
                                              Gsasl_property prop);
  extern _GSASL_API const char *gsasl_property_get (Gsasl_session * sctx,
                                                    Gsasl_property prop);
  extern _GSASL_API const char *gsasl_property_fast (Gsasl_session * sctx,
                                                     Gsasl_property prop);
 
  /* Mechanism handling: listmech.c, supportp.c, suggest.c */
  extern _GSASL_API int gsasl_client_mechlist (Gsasl * ctx, char **out);
  extern _GSASL_API int gsasl_client_support_p (Gsasl * ctx,
                                                const char *name);
  extern _GSASL_API const char *gsasl_client_suggest_mechanism (Gsasl * ctx,
                                                                const char
                                                                *mechlist);
 
  extern _GSASL_API int gsasl_server_mechlist (Gsasl * ctx, char **out);
  extern _GSASL_API int gsasl_server_support_p (Gsasl * ctx,
                                                const char *name);
  extern _GSASL_API int gsasl_mechanism_name_p (const char *mech);
 
  /* Authentication functions: xstart.c, xstep.c, xfinish.c */
  extern _GSASL_API int gsasl_client_start (Gsasl * ctx, const char *mech,
                                            Gsasl_session ** sctx);
  extern _GSASL_API int gsasl_server_start (Gsasl * ctx, const char *mech,
                                            Gsasl_session ** sctx);
  extern _GSASL_API int gsasl_step (Gsasl_session * sctx,
                                    const char *input, size_t input_len,
                                    char **output, size_t *output_len);
  extern _GSASL_API int gsasl_step64 (Gsasl_session * sctx,
                                      const char *b64input, char **b64output);
  extern _GSASL_API void gsasl_finish (Gsasl_session * sctx);
 
  /* Session functions: xcode.c, mechname.c */
  extern _GSASL_API int gsasl_encode (Gsasl_session * sctx,
                                      const char *input, size_t input_len,
                                      char **output, size_t *output_len);
  extern _GSASL_API int gsasl_decode (Gsasl_session * sctx,
                                      const char *input, size_t input_len,
                                      char **output, size_t *output_len);
  extern _GSASL_API const char *gsasl_mechanism_name (Gsasl_session * sctx);
 
  /* Error handling: error.c */
  extern _GSASL_API const char *gsasl_strerror (int err);
  extern _GSASL_API const char *gsasl_strerror_name (int err);
 
  /* Internationalized string processing: stringprep.c */
  extern _GSASL_API int gsasl_saslprep (const char *in,
                                        Gsasl_saslprep_flags flags,
                                        char **out, int *stringpreprc);
 
  /* Crypto functions: crypto.c */
 
  typedef enum
  {
    /* Hash algorithm identifiers. */
    GSASL_HASH_SHA1 = 2,
    GSASL_HASH_SHA256 = 3,
  } Gsasl_hash;
 
  typedef enum
  {
    /* Output sizes of hashes. */
    GSASL_HASH_SHA1_SIZE = 20,
    GSASL_HASH_SHA256_SIZE = 32,
    GSASL_HASH_MAX_SIZE = GSASL_HASH_SHA256_SIZE
  } Gsasl_hash_length;
 
  extern _GSASL_API int gsasl_nonce (char *data, size_t datalen);
  extern _GSASL_API int gsasl_random (char *data, size_t datalen);
 
  extern _GSASL_API size_t gsasl_hash_length (Gsasl_hash hash);
 
  extern _GSASL_API int
    gsasl_scram_secrets_from_salted_password (Gsasl_hash hash,
                                              const char *salted_password,
                                              char *client_key,
                                              char *server_key,
                                              char *stored_key);
  extern _GSASL_API int
    gsasl_scram_secrets_from_password (Gsasl_hash hash,
                                       const char *password,
                                       unsigned int iteration_count,
                                       const char *salt,
                                       size_t saltlen,
                                       char *salted_password,
                                       char *client_key,
                                       char *server_key, char *stored_key);
 
  /* Utilities: md5pwd.c, base64.c, free.c */
  extern _GSASL_API int gsasl_simple_getpass (const char *filename,
                                              const char *username,
                                              char **key);
  extern _GSASL_API int gsasl_base64_to (const char *in, size_t inlen,
                                         char **out, size_t *outlen);
  extern _GSASL_API int gsasl_base64_from (const char *in, size_t inlen,
                                           char **out, size_t *outlen);
  extern _GSASL_API int gsasl_hex_to (const char *in, size_t inlen,
                                      char **out, size_t *outlen);
  extern _GSASL_API int gsasl_hex_from (const char *in, char **out,
                                        size_t *outlen);
  extern _GSASL_API void gsasl_free (void *ptr);
 
  /* Get the mechanism API. */
# include <gsasl-mech.h>
 
# ifdef __cplusplus
}
# endif
 
#endif                          /* GSASL_H */