Provided by: libmunge-dev_0.5.8-7_i386 bug

NAME

       munge_ctx_create,           munge_ctx_copy,          munge_ctx_destroy,
       munge_ctx_strerror,  munge_ctx_get,  munge_ctx_set  -   MUNGE   context
       functions

SYNOPSIS

       #define GPL_LICENSED 1
       #include <munge.h>

       munge_ctx_t munge_ctx_create (void);

       munge_ctx_t munge_ctx_copy (munge_ctx_t ctx);

       void munge_ctx_destroy (munge_ctx_t ctx);

       const char * munge_ctx_strerror (munge_ctx_t ctx);

       munge_err_t munge_ctx_get (munge_ctx_t ctx, munge_opt_t opt, ...);

       munge_err_t munge_ctx_set (munge_ctx_t ctx, munge_opt_t opt, ...);

       cc ... -lmunge

DESCRIPTION

       The munge_ctx_create() function creates and returns a new munge context
       or NULL or error.

       The munge_ctx_copy() function copies the context ctx, returning  a  new
       munge context or NULL on error.

       The munge_ctx_destroy() function destroys the context ctx.

       The  munge_ctx_strerror()  function  returns  a descriptive text string
       describing the munge error number according to the context ctx, or NULL
       if  no  error condition exists.  This may provide a more detailed error
       message than that returned by munge_strerror().

       The  munge_ctx_get()  function  gets  the  value  for  the  option  opt
       associated  with  the  munge  context  ctx,  storing  the result in the
       subsequent pointer argument.  If the result is a  string,  that  string
       should not be freed or modified by the caller.

       The  munge_ctx_set()  function  sets  the  value  for  the  option  opt
       associated  with  the  munge  context  ctx,  using  the  value  of  the
       subsequent argument.

RETURN VALUE

       The  munge_ctx_create()  and  munge_ctx_copy() functions return a newly
       allocated munge context, or NULL on error.

       The munge_cxt_strerror() function returns a pointer to a NUL-terminated
       constant  text  string;  this string should not be freed or modified by
       the caller.

       The munge_ctx_get() and munge_ctx_set() functions return EMUNGE_SUCCESS
       on success; otherwise, a munge error number is returned.

CONTEXT OPTIONS

       The  following  context  options  can be queried via munge_ctx_get() or
       specified via munge_ctx_set().  The type following each enumeration  is
       the  variable type used for the subsequent argument in munge_ctx_set(),
       or the variable type of a pointer used for the subsequent  argument  in
       munge_ctx_get().

       MUNGE_OPT_CIPHER_TYPE , int
              Get or set the cipher type (cf., CIPHER TYPES).

       MUNGE_OPT_MAC_TYPE , int
              Get or set the MAC type (cf., MAC TYPES).

       MUNGE_OPT_ZIP_TYPE , int
              Get or set the compression type (cf., ZIP TYPES).

       MUNGE_OPT_REALM , char *
              Get  or  set the security realm, where the char * type is a NUL-
              terminated   character   string.    The   string   returned   by
              munge_ctx_get()  should  not be freed or modified by the caller.
              NOT YET SUPPORTED.

       MUNGE_OPT_TTL , int
              Get or set the time-to-live (in seconds) (cf., TTL TYPES).  This
              value controls how long the credential is valid once it has been
              encoded.

       MUNGE_OPT_ADDR4 , struct in_addr
              Get the IPv4 address  of  the  host  where  the  credential  was
              encoded.  This option cannot be explicitly set.

       MUNGE_OPT_ENCODE_TIME , time_t
              Get  the  time  (in  seconds  since  the  epoch)  at  which  the
              credential was encoded.  This option cannot be explicitly set.

       MUNGE_OPT_DECODE_TIME , time_t
              Get  the  time  (in  seconds  since  the  epoch)  at  which  the
              credential was decoded.  This option cannot be explicitly set.

       MUNGE_OPT_SOCKET , char *
              Get  or  set the local domain socket for connecting with munged,
              where the char * type is a NUL-terminated character string.  The
              string  returned  by  munge_ctx_get()  should  not  be  freed or
              modified by the caller.

       MUNGE_OPT_UID_RESTRICTION , uid_t
              Get or set the UID allowed to decode the credential (cf., UID  &
              GID  TYPES).   This  value will be matched against the effective
              user ID of the process requesting the credential decode.

       MUNGE_OPT_GID_RESTRICTION , gid_t
              Get or set the GID allowed to decode the credential (cf., UID  &
              GID  TYPES).   This  value will be matched against the effective
              group ID of the process requesting  the  credential  decode,  as
              well  as each supplementary group of which the effective user ID
              of that process is a memeber.

CIPHER TYPES

       Credentials can be encrypted using the secret key shared by all  munged
       daemons  within a security realm.  Anyone having access to this key can
       use it to decrypt a  credential,  thereby  bypassing  any  restrictions
       being imposed by munged.

       MUNGE_CIPHER_NONE
              Specify encryption is to be disabled.

       MUNGE_CIPHER_DEFAULT
              Specify the default according to the munged configuration.

       MUNGE_CIPHER_BLOWFISH
              Specify  the  Blowfish  cipher designed by Bruce Schneier.  This
              cipher has a 64-bit block-size and a variable key length.  MUNGE
              uses  it  with  a  128-bit  key in CBC mode.  It is a fast block
              cipher but suffers from a slow key setup time.  Consequently, it
              underperforms when generating small credentials.

       MUNGE_CIPHER_CAST5
              Specify the CAST5 cipher designed by Carlisle Adams and Stafford
              Tavares.  This cipher has a 64-bit block-size and a variable key
              length.  MUNGE uses it with a 128-bit key in CBC mode.

       MUNGE_CIPHER_AES128
              Specify  the  AES  (Advanced  Encryption  Standard) cipher, also
              known as Rijndael.  It was designed by Joan Daemen  and  Vincent
              Rijmen.   This  cipher has a 128-bit block-size and a key length
              of 128, 192, or 256 bits.  MUNGE uses it here with a 128-bit key
              in CBC mode.

       MUNGE_CIPHER_AES256
              Specify  the  AES  (Advanced  Encryption  Standard) cipher, also
              known as Rijndael.  It was designed by Joan Daemen  and  Vincent
              Rijmen.   This  cipher has a 128-bit block-size and a key length
              of 128, 192, or 256 bits.  MUNGE uses it here with a 256-bit key
              in CBC mode.  Currently, MUNGE_CIPHER_AES256 requires the use of
              MUNGE_MAC_SHA256.

MAC TYPES

       The  message  authentication  code  (MAC),  also  known  as  a  message
       integrity  code  (MIC),  is  a  required  component  of  the credental;
       consequently, it cannot be disabled.

       MUNGE_MAC_DEFAULT
              Specify the default according to the munged configuration.

       MUNGE_MAC_MD5
              Specify the MD5 algorithm designed by Ron Rivest  and  published
              in 1991.  This algorithm has a 128-bit message digest.  In 2004,
              a successful collision attack was demonstrated against MD5.  But
              since  a  pre-image  attack  has  not yet been demonstrated, MD5
              should still be safe to  use  within  MUNGE.   However,  use  of
              SHA-1, RIPEMD-160, or SHA-256 is recommended in order to provide
              a better security margin.

       MUNGE_MAC_SHA1
              Specify the SHA-1 algorithm designed by  the  National  Security
              Agency  and  published  in  1995;  this  is the successor to the
              original Secure Hash Algorithm (now called SHA-0)  published  in
              1993.   This  algorithm  has a 160-bit message digest.  In 2005,
              successful collision attacks were  demonstrated  against  SHA-1.
              But  since  a  pre-image  attack  has not yet been demonstrated,
              SHA-1 should still be  safe  to  use  within  MUNGE.   NIST  has
              announced  plans  to phase out the use of SHA-1 by 2010 in favor
              of the SHA-2 variants.

       MUNGE_MAC_RIPEMD160
              Specify the RIPEMD-160  (RACE  Integrity  Primitives  Evaluation
              Message  Digest) algorithm designed in Europe by Hans Dobbertin,
              Antoon Bosselaers, and Bart  Preneel,  and  published  in  1996.
              This  algorithm  has  a  160-bit message digest.  It is somewhat
              less popular than SHA-1 and correspondingly less  well  studied.
              While  slower  than  SHA-1,  it  is  believed to have a slightly
              better security margin.

       MUNGE_MAC_SHA256
              Specify the SHA-256 algorithm designed by the National  Security
              Agency  and published in 2002; this is one of the SHA-2 variants
              in the Secure Hash  Algorithm  family.   This  algorithm  has  a
              256-bit message digest.  It has not received as much scrutiny by
              the public cryptographic community as  SHA-1  has,  and  so  its
              cryptographic security is not yet as well-established.  However,
              no attacks have yet been reported against it.

ZIP TYPES

       If a compression type is specified, a payload-bearing  credential  will
       be  compressed  accordingly.  However, if the resulting compressed data
       is larger than the original uncompressed data,  the  uncompressed  data
       will be restored and compression will be disabled.

       MUNGE_ZIP_NONE
              Specify  compression is to be disabled.  This is the recommended
              setting  unless  there  is  a  payload  of  sufficient  size  to
              compress.

       MUNGE_ZIP_DEFAULT
              Specify the default according to the munged configuration.

       MUNGE_ZIP_BZLIB
              Specify  the  bzip2  algorithm developed by Julian Seward.  This
              algorithm is slower and uses more memory, but generally gets the
              best compression on larger payloads.

       MUNGE_ZIP_ZLIB
              Specify  the  zlib  "deflate"  algorithm  developed by Jean-loup
              Gailly and Mark Adler.  This algorithm is faster and  uses  less
              memory, but gets pretty good compression nonetheless.

TTL TYPES

       The  time-to-live  value specifies the number of seconds the credential
       is considered valid from the time it was encoded according to the clock
       on  the  host  on  which  it was encoded.  In addition to specifying an
       integer value, the following types are available.

       MUNGE_TTL_MAXIMUM
              Specify the maximum allowed by the munged configuration.

       MUNGE_TTL_DEFAULT
              Specify the default according to the munged configuration.

UID & GID TYPES

       The UID and GID restrictions can be used  to  restrict  the  credential
       decode  based  on  the  effective  user  and group ID of the requesting
       process.  In addition to specifying an  integer  value,  the  following
       types are available.

       MUNGE_UID_ANY
              Specify  that  no UID restriction is to take effect; this is the
              default behavior.

       MUNGE_GID_ANY
              Specify that no GID restriction is to take effect; this  is  the
              default behavior.

ERRORS

       Refer to munge(3) for a complete list of errors.

EXAMPLE

       The  following example program illustrates the use of the munge context
       to query the location of the munged domain socket.

       #define GPL_LICENSED 1

       #include <stdio.h>                      /* for printf() */
       #include <stdlib.h>                     /* for exit() */
       #include <munge.h>

       int
       main (int argc, char *argv[])
       {
           munge_ctx_t  ctx;
           munge_err_t  err;
           char        *str;

           if (!(ctx = munge_ctx_create ())) {
               fprintf (stderr, "ERROR: Unable to create munge context\n");
               exit (1);
           }
           err = munge_ctx_get (ctx, MUNGE_OPT_SOCKET, &str);

           if (err != EMUNGE_SUCCESS) {
               fprintf (stderr, "ERROR: %s\n", munge_ctx_strerror (ctx));
               exit (1);
           }
           printf ("socket=%s\n", str);
           /*
            *  Note that ’str’ is not to be free()d since
            *    it points to a string within the ’ctx’.
            */
           munge_ctx_destroy (ctx);
           exit (0);
       }

NOTES

       Abandoning a new or copied munge context  without  destroying  it  will
       result in a memory leak.

       The  context  passed  to munge_encode() is treated read-only except for
       the error message that is set when an error is returned.   The  context
       passed to munge_decode() is set according to the context used to encode
       the credential; however, on error, its settings may be in a state which
       is  invalid  for  encoding.   Consequently, separate contexts should be
       used for encoding and decoding.

       A context should not be shared between threads unless it  is  protected
       by  a mutex; however, a better alternative is to use a separate context
       (or  two)  for  each  thread,  either  by  creating  a  new   one   via
       munge_ctx_create() or copying an existing one via munge_ctx_copy().

AUTHOR

       Chris Dunlap <cdunlap@llnl.gov>

COPYRIGHT

       Copyright  (C)  2002-2007  The Regents of the University of California.
       Produced at Lawrence Livermore National Laboratory.   UCRL-CODE-155910.

       MUNGE  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.

SEE ALSO

       munge(1),  remunge(1),  unmunge(1),  munge(3), munge_enum(3), munge(7),
       munged(8).

       http://home.gna.org/munge/