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 `pkg-config --cflags --libs munge` -o foo foo.c
27
28

DESCRIPTION

30       The munge_ctx_create() function creates and returns a  new  MUNGE  con‐
31       text, or NULL on error.
32
33       The  munge_ctx_copy() function copies the context ctx and returns 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 de‐
39       scribing  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 ar‐
50       gument.
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_ctx_strerror() function returns a pointer to a NUL-terminated
58       constant text string, or NULL  if  no  error  condition  exists.   This
59       string should not be freed or modified by the caller.
60
61       The munge_ctx_get() and munge_ctx_set() functions return EMUNGE_SUCCESS
62       on success, or a MUNGE error number otherwise.
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 (see CIPHER TYPES).
74
75       MUNGE_OPT_MAC_TYPE , int
76              Get or set the MAC type (see MAC TYPES).
77
78       MUNGE_OPT_ZIP_TYPE , int
79              Get or set the compression type (see COMPRESSION 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 CURRENTLY SUPPORTED.
86
87       MUNGE_OPT_TTL , int
88              Get  or set the time-to-live (in seconds) (see 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 en‐
94              coded.  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 (see 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 (see 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 member.
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 be‐
127       ing imposed by munged.
128
129       MUNGE_CIPHER_NONE
130              Specify that 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  ci‐
139              pher  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) is a required component of the
165       credential; consequently, it cannot be disabled.
166
167       MUNGE_MAC_DEFAULT
168              Specify the default according to the munged configuration.
169
170       MUNGE_MAC_MD5
171              Specify the MD5 algorithm designed by Ron Rivest  and  published
172              in 1991.  This algorithm has a 128-bit message digest.  In 2004,
173              a successful collision attack against MD5 was demonstrated.   In
174              2009,  a theoretical pre-image attack against MD5 was published.
175              Consequently, use of MD5 is not recommended due to its lower se‐
176              curity margin.
177
178       MUNGE_MAC_SHA1
179              Specify  the  SHA-1  algorithm designed by the National Security
180              Agency and published in 1995; this is the successor to the orig‐
181              inal Secure Hash Algorithm (now called SHA-0) published in 1993.
182              This algorithm has a 160-bit message digest.  In 2005,  success‐
183              ful collision attacks were demonstrated against SHA-1.  In 2017,
184              a successful identical-prefix collision attack  (SHAttered)  was
185              announced.  In 2020, a successful chosen-prefix collision attack
186              (SHA-1 is a Shambles) was announced.  Since a  pre-image  attack
187              has not yet been demonstrated, SHA-1 should still be safe to use
188              within MUNGE; however, use of a SHA-2  hash  function  (such  as
189              SHA-256 or SHA-512) should be preferred.
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

COMPRESSION 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 for that credential.
222
223       MUNGE_ZIP_NONE
224              Specify that compression is to be disabled.  This is the  recom‐
225              mended  setting  unless there is a payload of sufficient size to
226              compress.
227
228       MUNGE_ZIP_DEFAULT
229              Specify the default according to the munged configuration.
230
231       MUNGE_ZIP_BZLIB
232              Specify the bzip2 library developed by Julian Seward.   This  is
233              slower  and uses more memory, but generally gets better compres‐
234              sion on larger payloads.
235
236       MUNGE_ZIP_ZLIB
237              Specify the zlib library developed by Jean-loup Gailly and  Mark
238              Adler.   This  is  faster  and uses less memory, but gets pretty
239              good compression nonetheless.
240
241

TTL TYPES

243       The time-to-live value specifies the number of seconds  after  the  en‐
244       code-time  that  the  credential  is  considered valid.  In addition to
245       specifying an integer value, the following types are available.
246
247       MUNGE_TTL_MAXIMUM
248              Specify the maximum allowed by the munged configuration.
249
250       MUNGE_TTL_DEFAULT
251              Specify the default according to the munged configuration.
252
253

UID & GID TYPES

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

ERRORS

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

EXAMPLE

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

NOTES

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

AUTHOR

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

SEE ALSO

345       munge(1),  remunge(1),  unmunge(1),  munge(3), munge_enum(3), munge(7),
346       munged(8), mungekey(8).
347
348       https://dun.github.io/munge/
349
350
351
352munge-0.5.15                      2022-06-22                      MUNGE_CTX(3)
Impressum