gsasl  2.2.1
gsasl.h
Go to the documentation of this file.
1 /* gsasl.h --- Header file for GNU SASL Library.
2  * Copyright (C) 2002-2024 Simon Josefsson
3  *
4  * This file is part of GNU SASL Library.
5  *
6  * GNU SASL Library is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public License
8  * as published by the Free Software Foundation; either version 2.1 of
9  * the License, or (at your option) any later version.
10  *
11  * GNU SASL Library 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 License along with GNU SASL Library; if not, write to the
18  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19  * Boston, MA 02110-1301, USA.
20  *
21  */
22 
23 #ifndef GSASL_H
24 # define GSASL_H
25 
34 # include <stdio.h> /* FILE */
35 # include <stddef.h> /* size_t */
36 # include <unistd.h> /* ssize_t */
37 
38 /* Get version symbols. */
39 # include <gsasl-version.h>
40 
41 # ifndef _GSASL_API
42 # if defined GSASL_BUILDING && defined HAVE_VISIBILITY && HAVE_VISIBILITY
43 # define _GSASL_API __attribute__((__visibility__("default")))
44 # elif defined GSASL_BUILDING && defined _MSC_VER && ! defined GSASL_STATIC
45 # define _GSASL_API __declspec(dllexport)
46 # elif defined _MSC_VER && ! defined GSASL_STATIC
47 # define _GSASL_API __declspec(dllimport)
48 # else
49 # define _GSASL_API
50 # endif
51 # endif
52 
53 # ifdef __cplusplus
54 extern "C"
55 {
56 # endif
57 
63  typedef struct Gsasl Gsasl;
64 
70  typedef struct Gsasl_session Gsasl_session;
71 
127  typedef enum
128  {
129  GSASL_OK = 0,
156  /* Mechanism specific errors. */
173  /* When adding new values, note that integers are not necessarily
174  assigned monotonously increasingly. */
176 
221  typedef enum
222  {
223  /* Information properties, e.g., username. */
233  GSASL_PIN = 10,
237  GSASL_QOP = 14,
249  /* Client callbacks. */
252  /* Server validation callback properties. */
261 
286  typedef int (*Gsasl_callback_function) (Gsasl * ctx, Gsasl_session * sctx,
287  Gsasl_property prop);
288 
298  typedef enum
299  {
303 
316  typedef enum
317  {
322 
330  typedef enum
331  {
334 
335  /* Library entry and exit points: version.c, init.c, done.c */
336  extern _GSASL_API int gsasl_init (Gsasl ** ctx);
337  extern _GSASL_API void gsasl_done (Gsasl * ctx);
338  extern _GSASL_API const char *gsasl_check_version (const char *req_version);
339 
340  /* Callback handling: callback.c */
341  extern _GSASL_API void gsasl_callback_set (Gsasl * ctx,
343  extern _GSASL_API int gsasl_callback (Gsasl * ctx, Gsasl_session * sctx,
344  Gsasl_property prop);
345 
346  extern _GSASL_API void gsasl_callback_hook_set (Gsasl * ctx, void *hook);
347  extern _GSASL_API void *gsasl_callback_hook_get (Gsasl * ctx);
348 
349  extern _GSASL_API void gsasl_session_hook_set (Gsasl_session * sctx,
350  void *hook);
351  extern _GSASL_API void *gsasl_session_hook_get (Gsasl_session * sctx);
352 
353  /* Property handling: property.c */
354  extern _GSASL_API int gsasl_property_set (Gsasl_session * sctx,
355  Gsasl_property prop,
356  const char *data);
358  Gsasl_property prop,
359  const char *data, size_t len);
360  extern _GSASL_API void gsasl_property_free (Gsasl_session * sctx,
361  Gsasl_property prop);
362  extern _GSASL_API const char *gsasl_property_get (Gsasl_session * sctx,
363  Gsasl_property prop);
364  extern _GSASL_API const char *gsasl_property_fast (Gsasl_session * sctx,
365  Gsasl_property prop);
366 
367  /* Mechanism handling: listmech.c, supportp.c, suggest.c */
368  extern _GSASL_API int gsasl_client_mechlist (Gsasl * ctx, char **out);
370  const char *name);
371  extern _GSASL_API const char *gsasl_client_suggest_mechanism (Gsasl * ctx,
372  const char
373  *mechlist);
374 
375  extern _GSASL_API int gsasl_server_mechlist (Gsasl * ctx, char **out);
377  const char *name);
378  extern _GSASL_API int gsasl_mechanism_name_p (const char *mech);
379 
380  /* Authentication functions: xstart.c, xstep.c, xfinish.c */
381  extern _GSASL_API int gsasl_client_start (Gsasl * ctx, const char *mech,
382  Gsasl_session ** sctx);
383  extern _GSASL_API int gsasl_server_start (Gsasl * ctx, const char *mech,
384  Gsasl_session ** sctx);
385  extern _GSASL_API int gsasl_step (Gsasl_session * sctx,
386  const char *input, size_t input_len,
387  char **output, size_t *output_len);
388  extern _GSASL_API int gsasl_step64 (Gsasl_session * sctx,
389  const char *b64input, char **b64output);
390  extern _GSASL_API void gsasl_finish (Gsasl_session * sctx);
391 
392  /* Session functions: xcode.c, mechname.c */
393  extern _GSASL_API int gsasl_encode (Gsasl_session * sctx,
394  const char *input, size_t input_len,
395  char **output, size_t *output_len);
396  extern _GSASL_API int gsasl_decode (Gsasl_session * sctx,
397  const char *input, size_t input_len,
398  char **output, size_t *output_len);
399  extern _GSASL_API const char *gsasl_mechanism_name (Gsasl_session * sctx);
400 
401  /* Error handling: error.c */
402  extern _GSASL_API const char *gsasl_strerror (int err);
403  extern _GSASL_API const char *gsasl_strerror_name (int err);
404 
405  /* Internationalized string processing: stringprep.c */
406  extern _GSASL_API int gsasl_saslprep (const char *in,
407  Gsasl_saslprep_flags flags,
408  char **out, int *stringpreprc);
409 
410  /* Crypto functions: crypto.c */
411 
427  typedef enum
428  {
429  /* Hash algorithm identifiers. */
432  } Gsasl_hash;
433 
447  typedef enum
448  {
449  /* Output sizes of hashes. */
454 
455  extern _GSASL_API int gsasl_nonce (char *data, size_t datalen);
456  extern _GSASL_API int gsasl_random (char *data, size_t datalen);
457 
458  extern _GSASL_API size_t gsasl_hash_length (Gsasl_hash hash);
459 
460  extern _GSASL_API int
462  const char *salted_password,
463  char *client_key,
464  char *server_key,
465  char *stored_key);
466  extern _GSASL_API int
468  const char *password,
469  unsigned int iteration_count,
470  const char *salt,
471  size_t saltlen,
472  char *salted_password,
473  char *client_key,
474  char *server_key, char *stored_key);
475 
476  /* Utilities: md5pwd.c, base64.c, free.c */
477  extern _GSASL_API int gsasl_simple_getpass (const char *filename,
478  const char *username,
479  char **key);
480  extern _GSASL_API int gsasl_base64_to (const char *in, size_t inlen,
481  char **out, size_t *outlen);
482  extern _GSASL_API int gsasl_base64_from (const char *in, size_t inlen,
483  char **out, size_t *outlen);
484  extern _GSASL_API int gsasl_hex_to (const char *in, size_t inlen,
485  char **out, size_t *outlen);
486  extern _GSASL_API int gsasl_hex_from (const char *in, char **out,
487  size_t *outlen);
488  extern _GSASL_API void gsasl_free (void *ptr);
489 
490  /* Get the mechanism API. */
491 # include <gsasl-mech.h>
492 
493 # ifdef __cplusplus
494 }
495 # endif
496 
497 #endif /* GSASL_H */
const char * name
Definition: error.c:38
_GSASL_API int gsasl_encode(Gsasl_session *sctx, const char *input, size_t input_len, char **output, size_t *output_len)
Definition: xcode.c:66
_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)
Definition: crypto.c:156
_GSASL_API int gsasl_init(Gsasl **ctx)
Definition: init.c:158
_GSASL_API size_t gsasl_hash_length(Gsasl_hash hash)
Definition: crypto.c:73
Gsasl_saslprep_flags
Definition: gsasl.h:331
@ GSASL_ALLOW_UNASSIGNED
Definition: gsasl.h:332
_GSASL_API const char * gsasl_strerror_name(int err)
Definition: error.c:223
_GSASL_API const char * gsasl_client_suggest_mechanism(Gsasl *ctx, const char *mechlist)
Definition: suggest.c:88
_GSASL_API int gsasl_base64_to(const char *in, size_t inlen, char **out, size_t *outlen)
Definition: base64.c:45
_GSASL_API int gsasl_server_mechlist(Gsasl *ctx, char **out)
Definition: listmech.c:94
_GSASL_API int gsasl_mechanism_name_p(const char *mech)
Definition: suggest.c:53
_GSASL_API void gsasl_callback_hook_set(Gsasl *ctx, void *hook)
Definition: callback.c:100
Gsasl_qop
Definition: gsasl.h:317
@ GSASL_QOP_AUTH_CONF
Definition: gsasl.h:320
@ GSASL_QOP_AUTH
Definition: gsasl.h:318
@ GSASL_QOP_AUTH_INT
Definition: gsasl.h:319
_GSASL_API int gsasl_nonce(char *data, size_t datalen)
Definition: crypto.c:39
_GSASL_API const char * gsasl_strerror(int err)
Definition: error.c:185
Gsasl_hash
Definition: gsasl.h:428
@ GSASL_HASH_SHA1
Definition: gsasl.h:430
@ GSASL_HASH_SHA256
Definition: gsasl.h:431
_GSASL_API int gsasl_hex_from(const char *in, char **out, size_t *outlen)
Definition: base64.c:144
#define _GSASL_API
Definition: gsasl.h:49
int(* Gsasl_callback_function)(Gsasl *ctx, Gsasl_session *sctx, Gsasl_property prop)
Definition: gsasl.h:286
_GSASL_API void gsasl_property_free(Gsasl_session *sctx, Gsasl_property prop)
Definition: property.c:159
Gsasl_rc
Definition: gsasl.h:128
@ GSASL_GSSAPI_UNWRAP_ERROR
Definition: gsasl.h:161
@ GSASL_NO_CLIENT_CODE
Definition: gsasl.h:140
@ GSASL_NO_CALLBACK
Definition: gsasl.h:142
@ GSASL_GSSAPI_IMPORT_NAME_ERROR
Definition: gsasl.h:158
@ GSASL_GSSAPI_RELEASE_OID_SET_ERROR
Definition: gsasl.h:172
@ GSASL_OK
Definition: gsasl.h:129
@ GSASL_SECURID_SERVER_NEED_ADDITIONAL_PASSCODE
Definition: gsasl.h:166
@ GSASL_GSSAPI_RELEASE_BUFFER_ERROR
Definition: gsasl.h:157
@ GSASL_NO_CB_TLS_EXPORTER
Definition: gsasl.h:155
@ GSASL_GSSAPI_ACCEPT_SEC_CONTEXT_ERROR
Definition: gsasl.h:160
@ GSASL_BASE64_ERROR
Definition: gsasl.h:134
@ GSASL_NO_OPENID20_REDIRECT_URL
Definition: gsasl.h:154
@ GSASL_SECURID_SERVER_NEED_NEW_PIN
Definition: gsasl.h:167
@ GSASL_GSSAPI_INQUIRE_MECH_FOR_SASLNAME_ERROR
Definition: gsasl.h:170
@ GSASL_AUTHENTICATION_ERROR
Definition: gsasl.h:138
@ GSASL_NEEDS_MORE
Definition: gsasl.h:130
@ GSASL_GSSAPI_TEST_OID_SET_MEMBER_ERROR
Definition: gsasl.h:171
@ GSASL_MALLOC_ERROR
Definition: gsasl.h:133
@ GSASL_NO_PASSWORD
Definition: gsasl.h:146
@ GSASL_NO_SAML20_IDP_IDENTIFIER
Definition: gsasl.h:152
@ GSASL_GSSAPI_DISPLAY_NAME_ERROR
Definition: gsasl.h:164
@ GSASL_NO_PASSCODE
Definition: gsasl.h:147
@ GSASL_NO_SERVICE
Definition: gsasl.h:149
@ GSASL_GSSAPI_ENCAPSULATE_TOKEN_ERROR
Definition: gsasl.h:168
@ GSASL_NO_AUTHZID
Definition: gsasl.h:145
@ GSASL_GSSAPI_ACQUIRE_CRED_ERROR
Definition: gsasl.h:163
@ GSASL_MECHANISM_CALLED_TOO_MANY_TIMES
Definition: gsasl.h:132
@ GSASL_NO_HOSTNAME
Definition: gsasl.h:150
@ GSASL_NO_AUTHID
Definition: gsasl.h:144
@ GSASL_GSSAPI_WRAP_ERROR
Definition: gsasl.h:162
@ GSASL_MECHANISM_PARSE_ERROR
Definition: gsasl.h:137
@ GSASL_NO_PIN
Definition: gsasl.h:148
@ GSASL_CRYPTO_ERROR
Definition: gsasl.h:135
@ GSASL_SASLPREP_ERROR
Definition: gsasl.h:136
@ GSASL_GSSAPI_DECAPSULATE_TOKEN_ERROR
Definition: gsasl.h:169
@ GSASL_NO_ANONYMOUS_TOKEN
Definition: gsasl.h:143
@ GSASL_NO_SERVER_CODE
Definition: gsasl.h:141
@ GSASL_NO_SAML20_REDIRECT_URL
Definition: gsasl.h:153
@ GSASL_INTEGRITY_ERROR
Definition: gsasl.h:139
@ GSASL_UNKNOWN_MECHANISM
Definition: gsasl.h:131
@ GSASL_GSSAPI_INIT_SEC_CONTEXT_ERROR
Definition: gsasl.h:159
@ GSASL_NO_CB_TLS_UNIQUE
Definition: gsasl.h:151
@ GSASL_GSSAPI_UNSUPPORTED_PROTECTION_ERROR
Definition: gsasl.h:165
_GSASL_API int gsasl_property_set_raw(Gsasl_session *sctx, Gsasl_property prop, const char *data, size_t len)
Definition: property.c:218
_GSASL_API int gsasl_hex_to(const char *in, size_t inlen, char **out, size_t *outlen)
Definition: base64.c:111
_GSASL_API int gsasl_base64_from(const char *in, size_t inlen, char **out, size_t *outlen)
Definition: base64.c:75
_GSASL_API int gsasl_step(Gsasl_session *sctx, const char *input, size_t input_len, char **output, size_t *output_len)
Definition: xstep.c:52
_GSASL_API void gsasl_session_hook_set(Gsasl_session *sctx, void *hook)
Definition: callback.c:140
_GSASL_API int gsasl_property_set(Gsasl_session *sctx, Gsasl_property prop, const char *data)
Definition: property.c:189
_GSASL_API int gsasl_server_start(Gsasl *ctx, const char *mech, Gsasl_session **sctx)
Definition: xstart.c:138
_GSASL_API const char * gsasl_check_version(const char *req_version)
Definition: version.c:46
_GSASL_API void * gsasl_session_hook_get(Gsasl_session *sctx)
Definition: callback.c:160
_GSASL_API int gsasl_step64(Gsasl_session *sctx, const char *b64input, char **b64output)
Definition: xstep.c:87
_GSASL_API int gsasl_random(char *data, size_t datalen)
Definition: crypto.c:55
_GSASL_API const char * gsasl_property_get(Gsasl_session *sctx, Gsasl_property prop)
Definition: property.c:292
_GSASL_API const char * gsasl_mechanism_name(Gsasl_session *sctx)
Definition: mechname.c:39
_GSASL_API void gsasl_free(void *ptr)
Definition: src/free.c:41
_GSASL_API void * gsasl_callback_hook_get(Gsasl *ctx)
Definition: callback.c:120
_GSASL_API void gsasl_done(Gsasl *ctx)
Definition: done.c:34
Gsasl_hash_length
Definition: gsasl.h:448
@ GSASL_HASH_SHA1_SIZE
Definition: gsasl.h:450
@ GSASL_HASH_MAX_SIZE
Definition: gsasl.h:452
@ GSASL_HASH_SHA256_SIZE
Definition: gsasl.h:451
_GSASL_API int gsasl_client_start(Gsasl *ctx, const char *mech, Gsasl_session **sctx)
Definition: xstart.c:120
Gsasl_property
Definition: gsasl.h:222
@ GSASL_DIGEST_MD5_HASHED_PASSWORD
Definition: gsasl.h:235
@ GSASL_SCRAM_STOREDKEY
Definition: gsasl.h:242
@ GSASL_SAML20_AUTHENTICATE_IN_BROWSER
Definition: gsasl.h:250
@ GSASL_HOSTNAME
Definition: gsasl.h:229
@ GSASL_AUTHZID
Definition: gsasl.h:225
@ GSASL_VALIDATE_GSSAPI
Definition: gsasl.h:256
@ GSASL_OPENID20_AUTHENTICATE_IN_BROWSER
Definition: gsasl.h:251
@ GSASL_SCRAM_SALT
Definition: gsasl.h:239
@ GSASL_QOP
Definition: gsasl.h:237
@ GSASL_CB_TLS_UNIQUE
Definition: gsasl.h:243
@ GSASL_SERVICE
Definition: gsasl.h:228
@ GSASL_GSSAPI_DISPLAY_NAME
Definition: gsasl.h:230
@ GSASL_VALIDATE_SIMPLE
Definition: gsasl.h:253
@ GSASL_VALIDATE_EXTERNAL
Definition: gsasl.h:254
@ GSASL_OPENID20_OUTCOME_DATA
Definition: gsasl.h:247
@ GSASL_SAML20_IDP_IDENTIFIER
Definition: gsasl.h:244
@ GSASL_SCRAM_SALTED_PASSWORD
Definition: gsasl.h:240
@ GSASL_VALIDATE_OPENID20
Definition: gsasl.h:259
@ GSASL_VALIDATE_SAML20
Definition: gsasl.h:258
@ GSASL_QOPS
Definition: gsasl.h:236
@ GSASL_PASSWORD
Definition: gsasl.h:226
@ GSASL_REALM
Definition: gsasl.h:234
@ GSASL_SCRAM_ITER
Definition: gsasl.h:238
@ GSASL_PASSCODE
Definition: gsasl.h:231
@ GSASL_AUTHID
Definition: gsasl.h:224
@ GSASL_SAML20_REDIRECT_URL
Definition: gsasl.h:245
@ GSASL_PIN
Definition: gsasl.h:233
@ GSASL_VALIDATE_SECURID
Definition: gsasl.h:257
@ GSASL_VALIDATE_ANONYMOUS
Definition: gsasl.h:255
@ GSASL_ANONYMOUS_TOKEN
Definition: gsasl.h:227
@ GSASL_SCRAM_SERVERKEY
Definition: gsasl.h:241
@ GSASL_CB_TLS_EXPORTER
Definition: gsasl.h:248
@ GSASL_SUGGESTED_PIN
Definition: gsasl.h:232
@ GSASL_OPENID20_REDIRECT_URL
Definition: gsasl.h:246
_GSASL_API int gsasl_simple_getpass(const char *filename, const char *username, char **key)
Definition: md5pwd.c:48
_GSASL_API void gsasl_callback_set(Gsasl *ctx, Gsasl_callback_function cb)
Definition: callback.c:45
_GSASL_API void gsasl_finish(Gsasl_session *sctx)
Definition: xfinish.c:34
_GSASL_API int gsasl_client_support_p(Gsasl *ctx, const char *name)
Definition: supportp.c:50
_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)
Definition: crypto.c:104
_GSASL_API int gsasl_callback(Gsasl *ctx, Gsasl_session *sctx, Gsasl_property prop)
Definition: callback.c:71
_GSASL_API const char * gsasl_property_fast(Gsasl_session *sctx, Gsasl_property prop)
Definition: property.c:262
_GSASL_API int gsasl_server_support_p(Gsasl *ctx, const char *name)
Definition: supportp.c:67
_GSASL_API int gsasl_client_mechlist(Gsasl *ctx, char **out)
Definition: listmech.c:75
Gsasl_mechname_limits
Definition: gsasl.h:299
@ GSASL_MIN_MECHANISM_SIZE
Definition: gsasl.h:300
@ GSASL_MAX_MECHANISM_SIZE
Definition: gsasl.h:301
_GSASL_API int gsasl_saslprep(const char *in, Gsasl_saslprep_flags flags, char **out, int *stringpreprc)
_GSASL_API int gsasl_decode(Gsasl_session *sctx, const char *input, size_t input_len, char **output, size_t *output_len)
Definition: xcode.c:99
Gsasl_mechanism * mech
Definition: internal.h:52
Gsasl * ctx
Definition: internal.h:50
char * password
Definition: internal.h:60
Definition: internal.h:37