GNU Simple Authentication and Security Layer 0.2.26

Simon Josefsson Datakonsult
Hagagatan 24
113 47 Stockholm
Sweden

E-mail: simon@josefsson.org

     $ wget -q http://josefsson.org/gsasl/releases/gsasl-0.2.26.tar.gz
     $ tar xfz gsasl-0.2.26.tar.gz
     $ cd gsasl-0.2.26/
     $ ./configure
     ...
     $ make
     ...
     $ make install
     ...

     #include <gsasl.h>

     int
     main (int argc, char *argv[])
     {
       Gsasl *ctx = NULL;
       int rc;
     ...
       rc = gsasl_init (&ctx);
       if (rc != GSASL_OK)
         {
           printf ("SASL initialization failure (%d): %s\n",
                   rc, gsasl_strerror (rc));
           return 1;
         }
     ...

     int
     main (int argc, char *argv[])
     {
       Gsasl *ctx = NULL;
       int rc;
     ...
       setlocale (LC_ALL, "");
     ...
       rc = gsasl_init (&ctx);
       if (rc != GSASL_OK)
         {
           printf (gettext ("SASL initialization failure (%d): %s\n"),
                   rc, gsasl_strerror (rc));
           return 1;
         }
     ...

     #include <gcrypt.h>
     ...
     int
     main (int argc, char *argv[])
     {
       Gsasl *ctx = NULL;
       int rc;
     ...
       /* Check version of libgcrypt. */
       if (!gcry_check_version (GCRYPT_VERSION))
         die ("version mismatch\n");
     
       /* Allocate a pool of 16k secure memory.  This also drops priviliges
          on some systems. */
       gcry_control (GCRYCTL_INIT_SECMEM, 16384, 0);
     
       /* Tell Libgcrypt that initialization has completed. */
       gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);
     ...
       rc = gsasl_init (&ctx);
       if (rc != GSASL_OK)
         {
           printf ("SASL initialization failure (%d): %s\n",
                   rc, gsasl_strerror (rc));
           return 1;
         }
     ...

       if (!gsasl_check_version (GSASL_VERSION))
         {
           printf ("gsasl_check_version failed:\n"
                   "Header file incompatible with shared library.\n");
           exit(1);
         }

     gcc -c foo.c `pkg-config libgsasl --cflags`

     gcc -o foo foo.o `pkg-config libgsasl --libs`

     gcc -o foo foo.c `pkg-config libgsasl --cflags --libs`

     AC_ARG_ENABLE(gsasl,
     	AC_HELP_STRING([--disable-gsasl], [don't use GNU SASL]),
     	gsasl=$enableval)
     if test "$gsal" != "no" ; then
     	PKG_CHECK_MODULES(GSASL, libgsasl >= 0.2.26,
     			[gsasl=yes],
                             [gsasl=no])
     	if test "$gsasl" != "yes" ; then
     		sal=no
     		AC_MSG_WARN([Cannot find GNU SASL, disabling])
     	else
     		gsasl=yes
     		AC_DEFINE(USE_GSASL, 1, [Define to 1 if you want GNU SASL.])
     	fi
     fi
     AC_MSG_CHECKING([if GNU SASL should be used])
     AC_MSG_RESULT($gsasl)

     AC_CHECK_HEADER(gsasl.h,
     	AC_CHECK_LIB(gsasl, gsasl_check_version,
     		[gsasl=yes AC_SUBST(GSASL_LIBS, -lgsasl)],
     		gsasl=no),
     	gsasl=no)
     AC_ARG_ENABLE(gsasl,
     	AC_HELP_STRING([--disable-gsasl], [don't use GNU SASL]),
     	gsasl=$enableval)
     if test "$gsasl" != "no" ; then
     	AC_DEFINE(USE_SASL, 1, [Define to 1 if you want GNU SASL.])
     else
     	AC_MSG_WARN([Cannot find GNU SASL, diabling])
     fi
     AC_MSG_CHECKING([if GNU SASL should be used])
     AC_MSG_RESULT($gsasl)

     int main (int argc, char *argv[])
     {
       Gsasl *ctx = NULL;
       int rc;
     
       if ((rc = gsasl_init (&ctx)) != GSASL_OK)
         {
           printf ("Cannot initialize libgsasl (%d): %s",
                   rc, gsasl_strerror (rc));
           return 1;
         }
     
       client (ctx);
     
       gsasl_done (ctx);
     
       return 0;
     }

     void client (Gsasl *ctx)
     {
       Gsasl_session *session;
       const char *mech = "PLAIN";
       int rc;
     
       /* Create new authentication session. */
       if ((rc = gsasl_client_start (ctx, mech, &session)) != GSASL_OK)
         {
           printf ("Cannot initialize client (%d): %s\n",
                   rc, gsasl_strerror (rc));
           return;
         }
     
       /* Set username and password in session handle.  This info will be
          lost when this session is deallocated below.  */
       gsasl_property_set (session, GSASL_AUTHID, "jas");
       gsasl_property_set (session, GSASL_PASSWORD, "secret");
     
       /* Do it. */
       client_authenticate (ctx, session);
     
       /* Cleanup. */
       gsasl_finish (session);
     }

     void client_authenticate (Gsasl * ctx, Gsasl_session * session)
     {
       char buf[BUFSIZ] = "";
       char *p;
       int rc;
     
       /* This loop mimic a protocol where the server get to send data
          first. */
     
       do
         {
           printf ("Input base64 encoded data from server:\n");
           fgets (buf, sizeof (buf) - 1, stdin);
           if (buf[strlen (buf) - 1] == '\n')
             buf[strlen (buf) - 1] = '\0';
     
           rc = gsasl_step64 (session, buf, &p);
     
           if (rc == GSASL_NEEDS_MORE || rc == GSASL_OK)
             {
               printf ("Output:\n%s\n", p);
               free (p);
             }
         }
       while (rc == GSASL_NEEDS_MORE);
     
       printf ("\n");
     
       if (rc != GSASL_OK)
         {
           printf ("Authentication error (%d): %s\n",
                   rc, gsasl_strerror (rc));
           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");
     }

     const char *client_mechanism (Gsasl *ctx)
     {
       static char mech[GSASL_MAX_MECHANISM_SIZE + 1] = "";
       char mechlist[BUFSIZ] = "";
       const char *suggestion;
     
       printf ("Enter list of mechanism that server support, separate by SPC:\n");
       fgets (mechlist, sizeof (mechlist) - 1, stdin);
     
       suggestion = gsasl_client_suggest_mechanism (ctx, mechlist);
       if (suggestion)
         printf ("Library suggest use of `%s'.\n", suggestion);
     
       printf ("Enter mechanism to use:\n");
       fgets (mech, sizeof (mech) - 1, stdin);
       mech[strlen (mech) - 1] = '\0';
     
       return mech;
     }

     Enter list of mechanism that server support, separate by SPC:
     CRAM-MD5 DIGEST-MD5 GSSAPI FOO BAR
     Library suggest use of `GSSAPI'.
     Enter mechanism to use:
     CRAM-MD5
     Input base64 encoded data from server:
     Zm5vcmQ=
     Output:
     amFzIDkyY2U1NWE5MTM2ZTY4NzEyMTUyZTFjYmFmNjVkZjgx
     
     If server accepted us, we're done.

       gsasl_property_set (ctx, GSASL_AUTHID, "jas");
       gsasl_property_set (ctx, GSASL_PASSWORD, "secret");

       /* Set the callback handler for the library. */
       gsasl_callback_set (ctx, callback);

     int callback (Gsasl * ctx, Gsasl_session * sctx, Gsasl_property prop)
     {
       char buf[BUFSIZ] = "";
       int rc = GSASL_NO_CALLBACK;
     
       /* Get user info from user. */
     
       printf ("Callback invoked, for property %d.\n", prop);
     
       switch (prop)
         {
         case GSASL_PASSCODE:
           printf ("Enter passcode:\n");
           fgets (buf, sizeof (buf) - 1, stdin);
           buf[strlen (buf) - 1] = '\0';
     
           gsasl_property_set (sctx, GSASL_PASSCODE, buf);
           rc = GSASL_OK;
           break;
     
         case GSASL_AUTHID:
           printf ("Enter username:\n");
           fgets (buf, sizeof (buf) - 1, stdin);
           buf[strlen (buf) - 1] = '\0';
     
           gsasl_property_set (sctx, GSASL_AUTHID, buf);
           rc = GSASL_OK;
           break;
     
         default:
           printf ("Unknown property!  Don't worry.\n");
           break;
         }
     
       return rc;
     }

GNU Simple Authentication and Security Layer 0.2.26

Table of Contents

GNU Simple Authentication and Security Layer

1 Introduction

1.1 Getting Started

1.2 Features

1.3 SASL Overview

1.4 Requirements

1.5 Supported Platforms

1.6 Getting help

1.7 Commercial Support

1.8 Downloading and Installing

1.8.1 Installing under Windows

1.9 Bug Reports

1.10 Contributing

2 Preparation

2.1 Header

2.2 Initialization

2.3 Version Check

gsasl_check_version

2.4 Building the source

2.5 Autoconf tests

2.5.1 Autoconf test via ‘pkg-config’

2.5.2 Standalone Autoconf test using Libtool

3 Using the Library

3.1 Choosing a mechanism

3.2 Using a callback

4 Properties

5 Mechanisms

5.1 The EXTERNAL mechanism

5.2 The ANONYMOUS mechanism

5.3 The PLAIN mechanism

5.4 The LOGIN mechanism

5.5 The CRAM-MD5 mechanism

5.6 The DIGEST-MD5 mechanism

5.7 The NTLM mechanism

5.8 The SECURID mechanism

5.9 The GSSAPI mechanism

5.10 The KERBEROS_V5 mechanism

6 Global Functions

gsasl_init

gsasl_done

gsasl_client_mechlist

gsasl_server_mechlist

gsasl_client_support_p

gsasl_server_support_p

gsasl_client_suggest_mechanism

gsasl_register

7 Callback Functions

gsasl_callback_set

gsasl_callback

gsasl_callback_hook_set

gsasl_callback_hook_get

gsasl_session_hook_set

gsasl_session_hook_get

8 Property Functions

gsasl_property_set

gsasl_property_set_raw

gsasl_property_fast

gsasl_property_get

9 Session Functions

gsasl_client_start

gsasl_server_start

gsasl_step

gsasl_step64

gsasl_finish

gsasl_encode

gsasl_decode

10 Utilities

gsasl_saslprep

gsasl_base64_to

gsasl_base64_from

gsasl_simple_getpass

gsasl_nonce

gsasl_random

gsasl_md5

gsasl_hmac_md5

11 Memory Handling

gsasl_free

12 Error Handling

2.5.1 Autoconf test via ‘`pkg-config`’