Next: , Previous: Header, Up: Preparation


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 Libgcrypt1, 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. Here is 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 applications, is not the biggest secure problem anyway). Note that the GNU SASL Library has not been audited to make sure it stores passwords or keys in secure memory.


Footnotes

[1] Note that GNU SASL normally use its own internal implementation of the cryptographic functions. Take care to verify that GNU SASL really use Libgcrypt, if this is what you want.