3.2. Initialization

`Libgsasl' must be initialized before it can be used. The library is initialized by calling gsasl_init (Chapter 6). 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.

In order to take advantage of the internationalisation features in `Libgsasl', such as translated error messages, the application must set the current locale using setlocale before initializing `Libgsasl'.

In order to take advantage of the secure memory features in `Libgcrypt', which subsequently makes sensitive key material used in `Libgsasl' be allocated in secure memory, 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[])
{
...

  /* 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);
  ...

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. Note that `Libgsasl' has not been audited to make sure it only ever stores passwords or keys in secure memory.