Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MUNGE(3)		  MUNGE	Uid 'N'	Gid Emporium		      MUNGE(3)

NAME
       munge_encode, munge_decode, munge_strerror - MUNGE core 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 `pkg-config --cflags --libs munge` -o	foo foo.c

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, EMU-
       NGE_CRED_REWOUND, EMUNGE_CRED_REPLAYED),	payload	memory will  still  be
       allocated if necessary.	The caller is responsible for freeing the mem-
       ory 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 de-
       scribing	the MUNGE error	number e.

RETURN VALUE
       The munge_encode() and munge_decode() functions	return	EMUNGE_SUCCESS
       on  success,  or	a MUNGE	error otherwise.  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 possibil-
	      ity  is  that  the  credential has been altered since it was en-
	      coded.

       EMUNGE_CRED_EXPIRED
	      The credential has expired.  This	means more  than  TTL  seconds
	      have  elapsed  since the credential was encoded.	Another	possi-
	      bility 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-2016 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 op-
       tion) 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 Li-
       cense 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).

       https://dun.github.io/munge/

munge-0.5.12			  2016-02-25			      MUNGE(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLE | NOTES | AUTHOR | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=munge&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help