GNU SASL Library
Introduction
GNU SASL is an implementation of the Simple Authentication and Security Layer framework and a few common SASL mechanisms. SASL is used by network servers (e.g., IMAP, SMTP) to request authentication from clients, and in clients to authenticate against servers.
GNU SASL consists of a library (‘libgsasl’), a command line utility (‘gsasl’) to access the library from the shell, and a manual. The library includes support for the framework (with authentication functions and application data privacy and integrity functions) and at least partial support for the CRAM-MD5, EXTERNAL, GSSAPI, ANONYMOUS, PLAIN, SECURID, DIGEST-MD5, LOGIN, and NTLM mechanisms.
The library is easily ported because it does not do network communication by itself, but rather leaves it up to the calling application. The library is flexible with regards to the authorization infrastructure used, as it utilize a callback into the application to decide whether a user is authorized or not.
GNU SASL is developed for the GNU/Linux system, but runs on over 20 platforms including most major Unix platforms and Windows, and many kind of devices including iPAQ handhelds and S/390 mainframes.
GNU SASL is written in pure ANSI C89 to be portable to embedded and otherwise limited platforms. The entire library, with full support for ANONYMOUS, EXTERNAL, PLAIN, LOGIN and CRAM-MD5, and the front-end that support client and server mode, and the IMAP and SMTP protocols, fits in under 60kb on an Intel x86 platform, without any modifications to the code. (This figure was accurate as of version 0.0.13.)
The library is licensed under the GNU Lesser General Public License, and the command-line interface, self-tests and examples are licensed under the GNU General Public License.
The project web page:
http://www.gnu.org/software/gsasl/
The software archive:
ftp://alpha.gnu.org/pub/gnu/gsasl/
Further information and paid contract development:
Simon Josefsson simon@josefsson.org
Logical overview
Control flow in application using the library
Examples
/* client.c --- Example SASL client.
* Copyright (C) 2004-2024 Simon Josefsson
*
* This file is part of GNU SASL.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program 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 General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
*/
#include <config.h>
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <gsasl.h>
static void
client_authenticate (Gsasl_session *session)
{
char buf[BUFSIZ] = "";
char *p;
int rc;
/* This loop mimics a protocol where the client send data first. */
do
{
/* Generate client output. */
rc = gsasl_step64 (session, buf, &p);
{
/* If sucessful, print it. */
printf ("Output:\n%s\n", p);
gsasl_free (p);
}
{
/* If the client need more data from server, get it here. */
printf ("Input base64 encoded data from server:\n");
p = fgets (buf, sizeof (buf) - 1, stdin);
if (p == NULL)
{
perror ("fgets");
return;
}
if (buf[strlen (buf) - 1] == '\n')
buf[strlen (buf) - 1] = '\0';
}
}
printf ("\n");
{
return;
}
/* The client is done. Here you would typically check if the server
let the client in. If not, you could try again. */
printf ("If server accepted us, we're done.\n");
}
static void
client (Gsasl *ctx)
{
Gsasl_session *session;
const char *mech = "PLAIN";
int rc;
/* Create new authentication session. */
{
return;
}
/* Set username and password in session handle. This info will be
lost when this session is deallocated below. */
{
return;
}
{
return;
}
/* Do it. */
client_authenticate (session);
/* Cleanup. */
gsasl_finish (session);
}
int
main (void)
{
Gsasl *ctx = NULL;
int rc;
/* Initialize library. */
{
return 1;
}
/* Do it. */
client (ctx);
/* Cleanup. */
gsasl_done (ctx);
return 0;
}
_GSASL_API int gsasl_property_set(Gsasl_session *sctx, Gsasl_property prop, const char *data)
Definition: property.c:189
_GSASL_API int gsasl_step64(Gsasl_session *sctx, const char *b64input, char **b64output)
Definition: xstep.c:87
_GSASL_API int gsasl_client_start(Gsasl *ctx, const char *mech, Gsasl_session **sctx)
Definition: xstart.c:120
Definition: internal.h:49
Definition: internal.h:37
/* client-serverfirst.c --- Example SASL client, where server send data first.
* Copyright (C) 2004-2024 Simon Josefsson
*
* This file is part of GNU SASL.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program 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 General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
*/
#include <config.h>
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <gsasl.h>
static void
client_authenticate (Gsasl_session *session)
{
char buf[BUFSIZ] = "";
char *p;
int rc;
/* This loop mimics a protocol where the server send data first. */
do
{
printf ("Input base64 encoded data from server:\n");
p = fgets (buf, sizeof (buf) - 1, stdin);
if (p == NULL)
{
perror ("fgets");
return;
}
if (buf[strlen (buf) - 1] == '\n')
buf[strlen (buf) - 1] = '\0';
rc = gsasl_step64 (session, buf, &p);
{
printf ("Output:\n%s\n", p);
gsasl_free (p);
}
}
printf ("\n");
{
return;
}
/* The client is done. Here you would typically check if the server
let the client in. If not, you could try again. */
printf ("If server accepted us, we're done.\n");
}
static void
client (Gsasl *ctx)
{
Gsasl_session *session;
const char *mech = "CRAM-MD5";
int rc;
/* Create new authentication session. */
{
return;
}
/* Set username and password in session handle. This info will be
lost when this session is deallocated below. */
{
return;
}
{
return;
}
/* Do it. */
client_authenticate (session);
/* Cleanup. */
gsasl_finish (session);
}
int
main (void)
{
Gsasl *ctx = NULL;
int rc;
/* Initialize library. */
{
return 1;
}
/* Do it. */
client (ctx);
/* Cleanup. */
gsasl_done (ctx);
return 0;
}
/* client-mech.c --- Example SASL client, with a choice of mechanism to use.
* Copyright (C) 2004-2024 Simon Josefsson
*
* This file is part of GNU SASL.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program 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 General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
*/
#include <config.h>
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <gsasl.h>
static void
client_authenticate (Gsasl_session *session)
{
char buf[BUFSIZ] = "";
char *p;
int rc;
/* This loop mimics a protocol where the server send data first. */
do
{
printf ("Input base64 encoded data from server:\n");
p = fgets (buf, sizeof (buf) - 1, stdin);
if (p == NULL)
{
perror ("fgets");
return;
}
if (buf[strlen (buf) - 1] == '\n')
buf[strlen (buf) - 1] = '\0';
rc = gsasl_step64 (session, buf, &p);
{
printf ("Output:\n%s\n", p);
gsasl_free (p);
}
}
printf ("\n");
{
return;
}
/* The client is done. Here you would typically check if the server
let the client in. If not, you could try again. */
printf ("If server accepted us, we're done.\n");
}
static const char *
client_mechanism (Gsasl *ctx)
{
char mechlist[BUFSIZ] = "";
const char *suggestion;
char *p;
printf ("Enter list of server supported mechanisms, separate by SPC:\n");
p = fgets (mechlist, sizeof (mechlist) - 1, stdin);
if (p == NULL)
{
perror ("fgets");
return NULL;
}
suggestion = gsasl_client_suggest_mechanism (ctx, mechlist);
if (suggestion)
printf ("Library suggests use of `%s'.\n", suggestion);
printf ("Enter mechanism to use:\n");
p = fgets (mech, sizeof (mech) - 1, stdin);
if (p == NULL)
{
perror ("fgets");
return NULL;
}
mech[strlen (mech) - 1] = '\0';
return mech;
}
static void
client (Gsasl *ctx)
{
Gsasl_session *session;
const char *mech;
int rc;
/* Find out which mechanism to use. */
mech = client_mechanism (ctx);
/* Create new authentication session. */
{
return;
}
/* Set username and password in session handle. This info will be
lost when this session is deallocated below. */
{
return;
}
{
return;
}
/* Do it. */
client_authenticate (session);
/* Cleanup. */
gsasl_finish (session);
}
int
main (void)
{
Gsasl *ctx = NULL;
int rc;
/* Initialize library. */
{
return 1;
}
/* Do it. */
client (ctx);
/* Cleanup. */
gsasl_done (ctx);
return 0;
}
_GSASL_API const char * gsasl_client_suggest_mechanism(Gsasl *ctx, const char *mechlist)
Definition: suggest.c:88
/* client-callback.c --- Example SASL client, with callback for user info.
* Copyright (C) 2004-2024 Simon Josefsson
*
* This file is part of GNU SASL.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program 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 General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
*/
#include <config.h>
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <gsasl.h>
static void
client_authenticate (Gsasl_session *session)
{
char buf[BUFSIZ] = "";
char *p;
int rc;
/* This loop mimics a protocol where the server send data first. */
do
{
printf ("Input base64 encoded data from server:\n");
p = fgets (buf, sizeof (buf) - 1, stdin);
if (p == NULL)
{
perror ("fgets");
return;
}
if (buf[strlen (buf) - 1] == '\n')
buf[strlen (buf) - 1] = '\0';
rc = gsasl_step64 (session, buf, &p);
{
printf ("Output:\n%s\n", p);
gsasl_free (p);
}
}
printf ("\n");
{
return;
}
/* The client is done. Here you would typically check if the server
let the client in. If not, you could try again. */
printf ("If server accepted us, we're done.\n");
}
static void
client (Gsasl *ctx)
{
Gsasl_session *session;
const char *mech = "SECURID";
int rc;
/* Create new authentication session. */
{
return;
}
/* Do it. */
client_authenticate (session);
/* Cleanup. */
gsasl_finish (session);
}
static int
{
char buf[BUFSIZ] = "";
char *p;
(void) ctx;
/* Get user info from user. */
printf ("Callback invoked, for property %u.\n", prop);
switch (prop)
{
case GSASL_PASSCODE:
printf ("Enter passcode:\n");
p = fgets (buf, sizeof (buf) - 1, stdin);
if (p == NULL)
{
perror ("fgets");
break;
}
buf[strlen (buf) - 1] = '\0';
break;
case GSASL_AUTHID:
printf ("Enter username:\n");
p = fgets (buf, sizeof (buf) - 1, stdin);
if (p == NULL)
{
perror ("fgets");
break;
}
buf[strlen (buf) - 1] = '\0';
break;
default:
printf ("Unknown property! Don't worry.\n");
break;
}
return rc;
}
int
main (void)
{
Gsasl *ctx = NULL;
int rc;
/* Initialize library. */
{
return 1;
}
/* Set the callback handler for the library. */
gsasl_callback_set (ctx, callback);
/* Do it. */
client (ctx);
/* Cleanup. */
gsasl_done (ctx);
return 0;
}
void gsasl_callback_set(Gsasl *ctx, Gsasl_callback_function cb)
Definition: callback.c:45
