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

NAME

7       munge_ctx_create,   munge_ctx_copy,  munge_ctx_destroy,  munge_ctx_str‐
8       error, munge_ctx_get, munge_ctx_set - MUNGE context functions
9
10

SYNOPSIS

12       #include <munge.h>
13
14       munge_ctx_t munge_ctx_create (void);
15
16       munge_ctx_t munge_ctx_copy (munge_ctx_t ctx);
17
18       void munge_ctx_destroy (munge_ctx_t ctx);
19
20       const char * munge_ctx_strerror (munge_ctx_t ctx);
21
22       munge_err_t munge_ctx_get (munge_ctx_t ctx, munge_opt_t opt, ...);
23
24       munge_err_t munge_ctx_set (munge_ctx_t ctx, munge_opt_t opt, ...);
25
26       cc ... -lmunge
27
28

DESCRIPTION

30       The munge_ctx_create() function creates and returns a new munge context
31       or NULL or error.
32
33       The  munge_ctx_copy()  function copies the context ctx, returning a new
34       munge context or NULL on error.
35
36       The munge_ctx_destroy() function destroys the context ctx.
37
38       The munge_ctx_strerror() function returns  a  descriptive  text  string
39       describing the munge error number according to the context ctx, or NULL
40       if no error condition exists.  This may provide a more  detailed  error
41       message than that returned by munge_strerror().
42
43       The  munge_ctx_get() function gets the value for the option opt associ‐
44       ated with the munge context ctx, storing the result in  the  subsequent
45       pointer argument.  If the result is a string, that string should not be
46       freed or modified by the caller.
47
48       The munge_ctx_set() function sets the value for the option opt  associ‐
49       ated  with  the  munge  context  ctx, using the value of the subsequent
50       argument.
51
52

RETURN VALUE

54       The munge_ctx_create() and munge_ctx_copy() functions  return  a  newly
55       allocated munge context, or NULL on error.
56
57       The munge_cxt_strerror() function returns a pointer to a NUL-terminated
58       constant text string; this string should not be freed  or  modified  by
59       the caller.
60
61       The munge_ctx_get() and munge_ctx_set() functions return EMUNGE_SUCCESS
62       on success; otherwise, a munge error number is returned.
63
64

CONTEXT OPTIONS

66       The following context options can be  queried  via  munge_ctx_get()  or
67       specified  via munge_ctx_set().  The type following each enumeration is
68       the variable type used for the subsequent argument in  munge_ctx_set(),
69       or  the  variable type of a pointer used for the subsequent argument in
70       munge_ctx_get().
71
72       MUNGE_OPT_CIPHER_TYPE , int
73              Get or set the cipher type (cf., CIPHER TYPES).
74
75       MUNGE_OPT_MAC_TYPE , int
76              Get or set the MAC type (cf., MAC TYPES).
77
78       MUNGE_OPT_ZIP_TYPE , int
79              Get or set the compression type (cf., ZIP TYPES).
80
81       MUNGE_OPT_REALM , char *
82              Get or set the security realm, where the char * type is  a  NUL-
83              terminated   character   string.    The   string   returned   by
84              munge_ctx_get() should not be freed or modified by  the  caller.
85              NOT YET SUPPORTED.
86
87       MUNGE_OPT_TTL , int
88              Get or set the time-to-live (in seconds) (cf., TTL TYPES).  This
89              value controls how long the credential is valid once it has been
90              encoded.
91
92       MUNGE_OPT_ADDR4 , struct in_addr
93              Get  the  IPv4  address  of  the  host  where the credential was
94              encoded.  This option cannot be explicitly set.
95
96       MUNGE_OPT_ENCODE_TIME , time_t
97              Get the time (in seconds since the epoch) at which  the  creden‐
98              tial was encoded.  This option cannot be explicitly set.
99
100       MUNGE_OPT_DECODE_TIME , time_t
101              Get  the  time (in seconds since the epoch) at which the creden‐
102              tial was decoded.  This option cannot be explicitly set.
103
104       MUNGE_OPT_SOCKET , char *
105              Get or set the local domain socket for connecting  with  munged,
106              where the char * type is a NUL-terminated character string.  The
107              string returned by munge_ctx_get() should not be freed or  modi‐
108              fied by the caller.
109
110       MUNGE_OPT_UID_RESTRICTION , uid_t
111              Get  or set the UID allowed to decode the credential (cf., UID &
112              GID TYPES).  This value will be matched  against  the  effective
113              user ID of the process requesting the credential decode.
114
115       MUNGE_OPT_GID_RESTRICTION , gid_t
116              Get  or set the GID allowed to decode the credential (cf., UID &
117              GID TYPES).  This value will be matched  against  the  effective
118              group  ID  of  the  process requesting the credential decode, as
119              well as each supplementary group of which the effective user  ID
120              of that process is a memeber.
121
122

CIPHER TYPES

124       Credentials  can be encrypted using the secret key shared by all munged
125       daemons within a security realm.  Anyone having access to this key  can
126       use  it  to  decrypt  a  credential, thereby bypassing any restrictions
127       being imposed by munged.
128
129       MUNGE_CIPHER_NONE
130              Specify encryption is to be disabled.
131
132       MUNGE_CIPHER_DEFAULT
133              Specify the default according to the munged configuration.
134
135       MUNGE_CIPHER_BLOWFISH
136              Specify the Blowfish cipher designed by  Bruce  Schneier.   This
137              cipher has a 64-bit block-size and a variable key length.  MUNGE
138              uses it with a 128-bit key in CBC mode.   It  is  a  fast  block
139              cipher but suffers from a slow key setup time.  Consequently, it
140              underperforms when generating small credentials.
141
142       MUNGE_CIPHER_CAST5
143              Specify the CAST5 cipher designed by Carlisle Adams and Stafford
144              Tavares.  This cipher has a 64-bit block-size and a variable key
145              length.  MUNGE uses it with a 128-bit key in CBC mode.
146
147       MUNGE_CIPHER_AES128
148              Specify the AES  (Advanced  Encryption  Standard)  cipher,  also
149              known  as  Rijndael.  It was designed by Joan Daemen and Vincent
150              Rijmen.  This cipher has a 128-bit block-size and a  key  length
151              of 128, 192, or 256 bits.  MUNGE uses it here with a 128-bit key
152              in CBC mode.
153
154       MUNGE_CIPHER_AES256
155              Specify the AES  (Advanced  Encryption  Standard)  cipher,  also
156              known  as  Rijndael.  It was designed by Joan Daemen and Vincent
157              Rijmen.  This cipher has a 128-bit block-size and a  key  length
158              of 128, 192, or 256 bits.  MUNGE uses it here with a 256-bit key
159              in CBC mode.  Currently, MUNGE_CIPHER_AES256 requires the use of
160              MUNGE_MAC_SHA256.
161
162

MAC TYPES

164       The  message  authentication  code  (MAC),  also  known  as  a  message
165       integrity code (MIC), is a required component of the credental;  conse‐
166       quently, it cannot be disabled.
167
168       MUNGE_MAC_DEFAULT
169              Specify the default according to the munged configuration.
170
171       MUNGE_MAC_MD5
172              Specify  the  MD5 algorithm designed by Ron Rivest and published
173              in 1991.  This algorithm has a 128-bit message digest.  In 2004,
174              a successful collision attack was demonstrated against MD5.  But
175              since a pre-image attack has  not  yet  been  demonstrated,  MD5
176              should  still  be  safe  to  use  within MUNGE.  However, use of
177              SHA-1, RIPEMD-160, or SHA-256 is recommended in order to provide
178              a better security margin.
179
180       MUNGE_MAC_SHA1
181              Specify  the  SHA-1  algorithm designed by the National Security
182              Agency and published in 1995; this is the successor to the orig‐
183              inal Secure Hash Algorithm (now called SHA-0) published in 1993.
184              This algorithm has a 160-bit message digest.  In 2005,  success‐
185              ful  collision  attacks  were  demonstrated  against SHA-1.  But
186              since a pre-image attack has not yet  been  demonstrated,  SHA-1
187              should  still  be  safe to use within MUNGE.  NIST has announced
188              plans to phase out the use of SHA-1 by  2010  in  favor  of  the
189              SHA-2 variants.
190
191       MUNGE_MAC_RIPEMD160
192              Specify  the  RIPEMD-160  (RACE  Integrity Primitives Evaluation
193              Message Digest) algorithm designed in Europe by Hans  Dobbertin,
194              Antoon  Bosselaers,  and  Bart  Preneel,  and published in 1996.
195              This algorithm has a 160-bit message  digest.   It  is  somewhat
196              less  popular  than SHA-1 and correspondingly less well studied.
197              While slower than SHA-1, it is believed to have a slightly  bet‐
198              ter security margin.
199
200       MUNGE_MAC_SHA256
201              Specify  the SHA-256 algorithm designed by the National Security
202              Agency and published in 2002; this is one of the SHA-2  variants
203              in  the  Secure  Hash  Algorithm  family.   This algorithm has a
204              256-bit message digest.  In 2006, NIST began encouraging the use
205              of  the  SHA-2 family of hash functions for all new applications
206              and protocols.
207
208       MUNGE_MAC_SHA512
209              Specify the SHA-512 algorithm designed by the National  Security
210              Agency  and published in 2002; this is one of the SHA-2 variants
211              in the Secure Hash  Algorithm  family.   This  algorithm  has  a
212              512-bit message digest.  In 2006, NIST began encouraging the use
213              of the SHA-2 family of hash functions for all  new  applications
214              and protocols.
215
216

ZIP TYPES

218       If  a  compression type is specified, a payload-bearing credential will
219       be compressed accordingly.  However, if the resulting  compressed  data
220       is  larger  than  the original uncompressed data, the uncompressed data
221       will be restored and compression will be disabled.
222
223       MUNGE_ZIP_NONE
224              Specify compression is to be disabled.  This is the  recommended
225              setting  unless  there  is  a payload of sufficient size to com‐
226              press.
227
228       MUNGE_ZIP_DEFAULT
229              Specify the default according to the munged configuration.
230
231       MUNGE_ZIP_BZLIB
232              Specify the bzip2 algorithm developed by  Julian  Seward.   This
233              algorithm is slower and uses more memory, but generally gets the
234              best compression on larger payloads.
235
236       MUNGE_ZIP_ZLIB
237              Specify the zlib  "deflate"  algorithm  developed  by  Jean-loup
238              Gailly  and  Mark Adler.  This algorithm is faster and uses less
239              memory, but gets pretty good compression nonetheless.
240
241

TTL TYPES

243       The time-to-live value specifies the number of seconds  the  credential
244       is considered valid from the time it was encoded according to the clock
245       on the host on which it was encoded.   In  addition  to  specifying  an
246       integer value, the following types are available.
247
248       MUNGE_TTL_MAXIMUM
249              Specify the maximum allowed by the munged configuration.
250
251       MUNGE_TTL_DEFAULT
252              Specify the default according to the munged configuration.
253
254

UID & GID TYPES

256       The  UID  and  GID  restrictions can be used to restrict the credential
257       decode based on the effective user  and  group  ID  of  the  requesting
258       process.   In  addition  to  specifying an integer value, the following
259       types are available.
260
261       MUNGE_UID_ANY
262              Specify that no UID restriction is to take effect; this  is  the
263              default behavior.
264
265       MUNGE_GID_ANY
266              Specify  that  no GID restriction is to take effect; this is the
267              default behavior.
268
269

ERRORS

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

EXAMPLE

275       The following example program illustrates the use of the munge  context
276       to query the location of the munged domain socket.
277
278       #include <stdio.h>                      /* for printf() */
279       #include <stdlib.h>                     /* for exit() */
280       #include <munge.h>
281
282       int
283       main (int argc, char *argv[])
284       {
285           munge_ctx_t  ctx;
286           munge_err_t  err;
287           char        *str;
288
289           if (!(ctx = munge_ctx_create ())) {
290               fprintf (stderr, "ERROR: Unable to create munge context\n");
291               exit (1);
292           }
293           err = munge_ctx_get (ctx, MUNGE_OPT_SOCKET, &str);
294
295           if (err != EMUNGE_SUCCESS) {
296               fprintf (stderr, "ERROR: %s\n", munge_ctx_strerror (ctx));
297               exit (1);
298           }
299           printf ("socket=%s\n", str);
300           /*
301            *  Note that 'str' is not to be free()d since
302            *    it points to a string within the 'ctx'.
303            */
304           munge_ctx_destroy (ctx);
305           exit (0);
306       }
307
308

NOTES

310       Abandoning  a  new  or  copied munge context without destroying it will
311       result in a memory leak.
312
313       The context passed to munge_encode() is treated  read-only  except  for
314       the  error  message that is set when an error is returned.  The context
315       passed to munge_decode() is set according to the context used to encode
316       the credential; however, on error, its settings may be in a state which
317       is invalid for encoding.  Consequently,  separate  contexts  should  be
318       used for encoding and decoding.
319
320       A  context  should not be shared between threads unless it is protected
321       by a mutex; however, a better alternative is to use a separate  context
322       (or   two)   for  each  thread,  either  by  creating  a  new  one  via
323       munge_ctx_create() or copying an existing one via munge_ctx_copy().
324
325

AUTHOR

327       Chris Dunlap <cdunlap@llnl.gov>
328
329
331       Copyright (C) 2007-2010 Lawrence Livermore National Security, LLC.
332       Copyright (C) 2002-2007 The Regents of the University of California.
333
334       MUNGE is free software: you can redistribute it and/or modify it  under
335       the  terms  of  the GNU General Public License as published by the Free
336       Software Foundation, either version 3  of  the  License,  or  (at  your
337       option)  any  later  version.  Additionally for the MUNGE library (lib‐
338       munge), you can redistribute it and/or modify it under the terms of the
339       GNU  Lesser  General  Public  License as published by the Free Software
340       Foundation, either version 3 of the License, or (at  your  option)  any
341       later version.
342
343

SEE ALSO

345       munge(1),  remunge(1),  unmunge(1),  munge(3), munge_enum(3), munge(7),
346       munged(8).
347
348       http://home.gna.org/munge/
349
350
351
352munge-0.5.9                       2010-03-23                      MUNGE_CTX(3)
Impressum