1
2MUNGE(3)                  MUNGE Uid 'N' Gid Emporium                  MUNGE(3)
3
4
5

NAME

7       munge_encode, munge_decode, munge_strerror - MUNGE primary functions
8
9

SYNOPSIS

11       #include <munge.h>
12
13       munge_err_t munge_encode (char **cred, munge_ctx_t ctx,
14                                 const void *buf, int len);
15
16       munge_err_t munge_decode (const char *cred, munge_ctx_t ctx,
17                                 void **buf, int *len, uid_t *uid, gid_t *gid);
18
19       const char * munge_strerror (munge_err_t e);
20
21       cc ... -lmunge
22
23

DESCRIPTION

25       The  munge_encode()  function  creates a credential contained in a NUL-
26       terminated base64 string.  A payload  specified  by  a  buffer  buf  of
27       length len can be encapsulated in as well.  If the munge context ctx is
28       NULL, the default context will be used.  A  pointer  to  the  resulting
29       credential  is  returned  via  cred;  on error, it is set to NULL.  The
30       caller is responsible for freeing the memory referenced by cred.
31
32       The munge_decode() function  validates  the  NUL-terminated  credential
33       cred.   If  the  munge  context ctx is not NULL, it will be set to that
34       used to encode the credential.  If buf and len  are  not  NULL,  memory
35       will  be  allocated  for  the  encapsulated payload, buf will be set to
36       point to this data, and len will be set to its length.   An  additional
37       NUL character will be appended to this payload data but not included in
38       its length.  If no payload exists, buf will be set to NULL and len will
39       be  set  to  0.   For  certain  errors (i.e., EMUNGE_CRED_EXPIRED, EMU‐
40       NGE_CRED_REWOUND, EMUNGE_CRED_REPLAYED), payload memory will  still  be
41       allocated if necessary.  The caller is responsible for freeing the mem‐
42       ory referenced by buf.  If uid or gid is not NULL, they will be set  to
43       the UID/GID of the process that created the credential.
44
45       The   munge_strerror()  function  returns  a  descriptive  text  string
46       describing the munge error number e.
47
48

RETURN VALUE

50       The munge_encode() and munge_decode() functions  return  EMUNGE_SUCCESS
51       on  success;  otherwise,  a munge error number is returned.  If a munge
52       context was used, it may contain a more detailed error message accessi‐
53       ble via munge_ctx_strerror().
54
55       The  munge_strerror()  function  returns  a pointer to a NUL-terminated
56       constant text string; this string should not be freed  or  modified  by
57       the caller.
58
59

ERRORS

61       EMUNGE_SUCCESS
62              Success.
63
64       EMUNGE_SNAFU
65              Internal error.
66
67       EMUNGE_BAD_ARG
68              Invalid argument.
69
70       EMUNGE_BAD_LENGTH
71              Exceeded  the  maximum message length as specified by the munged
72              configuration.
73
74       EMUNGE_OVERFLOW
75              Exceeded the maximum length of a buffer.
76
77       EMUNGE_NO_MEMORY
78              Unable to allocate the requisite memory.
79
80       EMUNGE_SOCKET
81              Unable to communicate with the daemon on the domain socket.
82
83       EMUNGE_BAD_CRED
84              The credential does not match the specified format.
85
86       EMUNGE_BAD_VERSION
87              The credential contains an unsupported version number.
88
89       EMUNGE_BAD_CIPHER
90              The credential contains an unsupported cipher type.
91
92       EMUNGE_BAD_MAC
93              The credential contains an unsupported MAC type.
94
95       EMUNGE_BAD_ZIP
96              The credential contains an unsupported compression type.
97
98       EMUNGE_BAD_REALM
99              The credential contains an unrecognized security realm.
100
101       EMUNGE_CRED_INVALID
102              The credential is invalid.  This means the credential could  not
103              be  successfully  decoded.  More than likely, the secret keys on
104              the encoding and decoding hosts do not match.  Another possibil‐
105              ity  is  that  the  credential  has  been  altered  since it was
106              encoded.
107
108       EMUNGE_CRED_EXPIRED
109              The credential has expired.  This means more  than  TTL  seconds
110              have  elapsed sinced the credential was encoded.  Another possi‐
111              bility is that the clocks on the encoding and decoding hosts are
112              out of sync.
113
114       EMUNGE_CRED_REWOUND
115              The credential appears to have been encoded at some point in the
116              future.  This means the clock on the  decoding  host  is  slower
117              than  that of the encoding host by more than the allowable clock
118              skew.  More than likely, the clocks on the encoding and decoding
119              hosts are out of sync.
120
121       EMUNGE_CRED_REPLAYED
122              The credential has been previously decoded on this host.
123
124       EMUNGE_CRED_UNAUTHORIZED
125              The client is not authorized to decode the credential based upon
126              the effective user and/or group ID of the process.
127
128

EXAMPLE

130       The following example program illustrates the use of a munge credential
131       to ascertain the effective user and group ID of the encoding process.
132
133       #include <stdio.h>                      /* for printf() */
134       #include <stdlib.h>                     /* for exit() & free() */
135       #include <unistd.h>                     /* for uid_t & gid_t */
136       #include <munge.h>
137
138       int
139       main (int argc, char *argv[])
140       {
141           char        *cred;
142           munge_err_t  err;
143           uid_t        uid;
144           gid_t        gid;
145
146           err = munge_encode (&cred, NULL, NULL, 0);
147
148           if (err != EMUNGE_SUCCESS) {
149               fprintf (stderr, "ERROR: %s\n", munge_strerror (err));
150               exit (1);
151           }
152           err = munge_decode (cred, NULL, NULL, NULL, &uid, &gid);
153
154           if (err != EMUNGE_SUCCESS) {
155               fprintf (stderr, "ERROR: %s\n", munge_strerror (err));
156               exit (1);
157           }
158           printf ("uid=%d gid=%d\n", uid, gid);
159           free (cred);
160           exit (0);
161       }
162
163

NOTES

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

AUTHOR

171       Chris Dunlap <cdunlap@llnl.gov>
172
173
175       Copyright (C) 2007-2010 Lawrence Livermore National Security, LLC.
176       Copyright (C) 2002-2007 The Regents of the University of California.
177
178       MUNGE  is free software: you can redistribute it and/or modify it under
179       the terms of the GNU General Public License as published  by  the  Free
180       Software  Foundation,  either  version  3  of  the License, or (at your
181       option) any later version.  Additionally for the  MUNGE  library  (lib‐
182       munge), you can redistribute it and/or modify it under the terms of the
183       GNU Lesser General Public License as published  by  the  Free  Software
184       Foundation,  either  version  3 of the License, or (at your option) any
185       later version.
186
187

SEE ALSO

189       munge(1),   remunge(1),   unmunge(1),   munge_ctx(3),    munge_enum(3),
190       munge(7), munged(8).
191
192       http://home.gna.org/munge/
193
194
195
196munge-0.5.9                       2010-03-23                          MUNGE(3)
Impressum