2.2 Initialization

The library must be initialized before it can be used. The library is initialized by calling gsasl_init (see Global Functions). The resources allocated by the initialization process can be released if the application no longer has a need to call `Libgsasl' functions, this is done by calling gsasl_done. For example:

     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;
         }
     ...

In order to make error messages from gsasl_strerror be translated (see Top) the application must set the current locale using setlocale before calling gsasl_init. For example:

     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;
         }
     ...

In order to take advantage of the secure memory features in Libgcrypt¹, you need to initialize secure memory in your application, and for some platforms even make your application setuid root. See the Libgcrypt documentation for more information. Example code to initialize secure memory in your code:

     #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 you do not do this, keying material will not be allocated in secure memory (which for most application is not the biggest secure problem anyway). Note that the GNU SASL Library has not been audited to make sure it only ever stores passwords or keys in secure memory.