Man Linux: Main Page and Category List

NAME

       munge_encode, munge_decode, munge_strerror - MUNGE primary functions

SYNOPSIS

       #include <munge.h>

       munge_err_t munge_encode (char **cred, munge_ctx_t ctx,
                                 const void *buf, int len);

       munge_err_t munge_decode (const char *cred, munge_ctx_t ctx,
                                 void **buf, int *len, uid_t *uid, gid_t *gid);

       const char * munge_strerror (munge_err_t e);

       cc ... -lmunge

DESCRIPTION

       The  munge_encode()  function  creates a credential contained in a NUL-
       terminated base64 string.  A payload  specified  by  a  buffer  buf  of
       length len can be encapsulated in as well.  If the munge context ctx is
       NULL, the default context will be used.  A  pointer  to  the  resulting
       credential  is  returned  via  cred;  on error, it is set to NULL.  The
       caller is responsible for freeing the memory referenced by cred.

       The munge_decode() function  validates  the  NUL-terminated  credential
       cred.   If  the  munge  context ctx is not NULL, it will be set to that
       used to encode the credential.  If buf and len  are  not  NULL,  memory
       will  be  allocated  for  the  encapsulated payload, buf will be set to
       point to this data, and len will be set to its length.   An  additional
       NUL character will be appended to this payload data but not included in
       its length.  If no payload exists, buf will be set to NULL and len will
       be   set   to   0.   For  certain  errors  (i.e.,  EMUNGE_CRED_EXPIRED,
       EMUNGE_CRED_REWOUND, EMUNGE_CRED_REPLAYED), payload memory  will  still
       be  allocated  if necessary.  The caller is responsible for freeing the
       memory referenced by buf.  If uid or gid is not NULL, they will be  set
       to the UID/GID of the process that created the credential.

       The   munge_strerror()  function  returns  a  descriptive  text  string
       describing the munge error number e.

RETURN VALUE

       The munge_encode() and munge_decode() functions  return  EMUNGE_SUCCESS
       on  success;  otherwise,  a munge error number is returned.  If a munge
       context was  used,  it  may  contain  a  more  detailed  error  message
       accessible via munge_ctx_strerror().

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

ERRORS

       EMUNGE_SUCCESS
              Success.

       EMUNGE_SNAFU
              Internal error.

       EMUNGE_BAD_ARG
              Invalid argument.

       EMUNGE_BAD_LENGTH
              Exceeded  the  maximum message length as specified by the munged
              configuration.

       EMUNGE_OVERFLOW
              Exceeded the maximum length of a buffer.

       EMUNGE_NO_MEMORY
              Unable to allocate the requisite memory.

       EMUNGE_SOCKET
              Unable to communicate with the daemon on the domain socket.

       EMUNGE_BAD_CRED
              The credential does not match the specified format.

       EMUNGE_BAD_VERSION
              The credential contains an unsupported version number.

       EMUNGE_BAD_CIPHER
              The credential contains an unsupported cipher type.

       EMUNGE_BAD_MAC
              The credential contains an unsupported MAC type.

       EMUNGE_BAD_ZIP
              The credential contains an unsupported compression type.

       EMUNGE_BAD_REALM
              The credential contains an unrecognized security realm.

       EMUNGE_CRED_INVALID
              The credential is invalid.  This means the credential could  not
              be  successfully  decoded.  More than likely, the secret keys on
              the  encoding  and  decoding  hosts  do  not   match.    Another
              possibility is that the credential has been altered since it was
              encoded.

       EMUNGE_CRED_EXPIRED
              The credential has expired.  This means more  than  TTL  seconds
              have   elapsed  sinced  the  credential  was  encoded.   Another
              possibility is that the clocks  on  the  encoding  and  decoding
              hosts are out of sync.

       EMUNGE_CRED_REWOUND
              The credential appears to have been encoded at some point in the
              future.  This means the clock on the  decoding  host  is  slower
              than  that of the encoding host by more than the allowable clock
              skew.  More than likely, the clocks on the encoding and decoding
              hosts are out of sync.

       EMUNGE_CRED_REPLAYED
              The credential has been previously decoded on this host.

       EMUNGE_CRED_UNAUTHORIZED
              The client is not authorized to decode the credential based upon
              the effective user and/or group ID of the process.

EXAMPLE

       The following example program illustrates the use of a munge credential
       to ascertain the effective user and group ID of the encoding process.

       #include <stdio.h>                      /* for printf() */
       #include <stdlib.h>                     /* for exit() & free() */
       #include <unistd.h>                     /* for uid_t & gid_t */
       #include <munge.h>

       int
       main (int argc, char *argv[])
       {
           char        *cred;
           munge_err_t  err;
           uid_t        uid;
           gid_t        gid;

           err = munge_encode (&cred, NULL, NULL, 0);

           if (err != EMUNGE_SUCCESS) {
               fprintf (stderr, "ERROR: %s\n", munge_strerror (err));
               exit (1);
           }
           err = munge_decode (cred, NULL, NULL, NULL, &uid, &gid);

           if (err != EMUNGE_SUCCESS) {
               fprintf (stderr, "ERROR: %s\n", munge_strerror (err));
               exit (1);
           }
           printf ("uid=%d gid=%d\n", uid, gid);
           free (cred);
           exit (0);
       }

NOTES

       Both  munge_encode()  and  munge_decode()  may allocate memory that the
       caller is responsible for freeing.  Failure to do so will result  in  a
       memory leak.

AUTHOR

       Chris Dunlap <cdunlap@llnl.gov>

COPYRIGHT

       Copyright (C) 2007-2010 Lawrence Livermore National Security, LLC.
       Copyright (C) 2002-2007 The Regents of the University of California.

       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,  either  version  3  of  the License, or (at your
       option)  any  later  version.   Additionally  for  the  MUNGE   library
       (libmunge), you can redistribute it and/or modify it under the terms of
       the GNU Lesser General Public License as published by the Free Software
       Foundation,  either  version  3 of the License, or (at your option) any
       later version.

SEE ALSO

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

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