1MUNGE_CTX(3) MUNGE Uid 'N' Gid Emporium MUNGE_CTX(3)
3
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
12 #include <munge.h>
13 munge_ctx_t munge_ctx_create (void);
15 munge_ctx_t munge_ctx_copy (munge_ctx_t ctx);
17 void munge_ctx_destroy (munge_ctx_t ctx);
19 const char * munge_ctx_strerror (munge_ctx_t ctx);
21 munge_err_t munge_ctx_get (munge_ctx_t ctx, munge_opt_t opt, ...);
23 munge_err_t munge_ctx_set (munge_ctx_t ctx, munge_opt_t opt, ...);
25 cc `pkg-config --cflags --libs munge` -o foo foo.c
27
30 The munge_ctx_create() function creates and returns a new MUNGE con‐
31 text, or NULL on error.
32 The munge_ctx_copy() function copies the context ctx and returns a new
34 MUNGE context, or NULL on error.
35 The munge_ctx_destroy() function destroys the context ctx.
37 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 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 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
54 The munge_ctx_create() and munge_ctx_copy() functions return a newly
55 allocated MUNGE context, or NULL on error.
56 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 The munge_ctx_get() and munge_ctx_set() functions return EMUNGE_SUCCESS
62 on success, or a MUNGE error number otherwise.
63
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 MUNGE_OPT_CIPHER_TYPE , int
73 Get or set the cipher type (cf., CIPHER TYPES).
74 MUNGE_OPT_MAC_TYPE , int
76 Get or set the MAC type (cf., MAC TYPES).
77 MUNGE_OPT_ZIP_TYPE , int
79 Get or set the compression type (cf., COMPRESSION TYPES).
80 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 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 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 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 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 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 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 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 member.
121
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 MUNGE_CIPHER_NONE
130 Specify that encryption is to be disabled.
131 MUNGE_CIPHER_DEFAULT
133 Specify the default according to the munged configuration.
134 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 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 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 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
164 The message authentication code (MAC) is a required component of the
165 credential; consequently, it cannot be disabled.
166 MUNGE_MAC_DEFAULT
168 Specify the default according to the munged configuration.
169 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
176 security margin.
177 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. Since a pre-image attack has not yet been demon‐
186 strated, SHA-1 should still be safe to use within MUNGE; how‐
187 ever, use of a SHA-2 hash function (such as SHA-256 or SHA-512)
188 should be preferred.
189 MUNGE_MAC_RIPEMD160
191 Specify the RIPEMD-160 (RACE Integrity Primitives Evaluation
192 Message Digest) algorithm designed in Europe by Hans Dobbertin,
193 Antoon Bosselaers, and Bart Preneel, and published in 1996.
194 This algorithm has a 160-bit message digest. It is somewhat
195 less popular than SHA-1 and correspondingly less well studied.
196 While slower than SHA-1, it is believed to have a slightly bet‐
197 ter security margin.
198 MUNGE_MAC_SHA256
200 Specify the SHA-256 algorithm designed by the National Security
201 Agency and published in 2002; this is one of the SHA-2 variants
202 in the Secure Hash Algorithm family. This algorithm has a
203 256-bit message digest. In 2006, NIST began encouraging the use
204 of the SHA-2 family of hash functions for all new applications
205 and protocols.
206 MUNGE_MAC_SHA512
208 Specify the SHA-512 algorithm designed by the National Security
209 Agency and published in 2002; this is one of the SHA-2 variants
210 in the Secure Hash Algorithm family. This algorithm has a
211 512-bit message digest. In 2006, NIST began encouraging the use
212 of the SHA-2 family of hash functions for all new applications
213 and protocols.
214
217 If a compression type is specified, a payload-bearing credential will
218 be compressed accordingly. However, if the resulting compressed data
219 is larger than the original uncompressed data, the uncompressed data
220 will be restored and compression will be disabled for that credential.
221 MUNGE_ZIP_NONE
223 Specify that compression is to be disabled. This is the recom‐
224 mended setting unless there is a payload of sufficient size to
225 compress.
226 MUNGE_ZIP_DEFAULT
228 Specify the default according to the munged configuration.
229 MUNGE_ZIP_BZLIB
231 Specify the bzip2 library developed by Julian Seward. This is
232 slower and uses more memory, but generally gets better compres‐
233 sion on larger payloads.
234 MUNGE_ZIP_ZLIB
236 Specify the zlib library developed by Jean-loup Gailly and Mark
237 Adler. This is faster and uses less memory, but gets pretty
238 good compression nonetheless.
239
242 The time-to-live value specifies the number of seconds after the
243 encode-time that the credential is considered valid. In addition to
244 specifying an integer value, the following types are available.
245 MUNGE_TTL_MAXIMUM
247 Specify the maximum allowed by the munged configuration.
248 MUNGE_TTL_DEFAULT
250 Specify the default according to the munged configuration.
251
254 The UID and GID restrictions can be used to restrict the decoding of
255 the credential based on the effective user and group ID of the request‐
256 ing process. In addition to specifying an integer value, the following
257 types are available.
258 MUNGE_UID_ANY
260 Specify that no UID restriction is to take effect; this is the
261 default behavior.
262 MUNGE_GID_ANY
264 Specify that no GID restriction is to take effect; this is the
265 default behavior.
266
269 Refer to munge(3) for a complete list of errors.
270
273 The following example program illustrates the use of the MUNGE context
274 to query the location of the munged domain socket.
275 #include <stdio.h> /* for printf() */
277 #include <stdlib.h> /* for exit() */
278 #include <munge.h>
279 int
281 main (int argc, char *argv[])
282 {
283 munge_ctx_t ctx;
284 munge_err_t err;
285 char *str;
286 if (!(ctx = munge_ctx_create ())) {
288 fprintf (stderr, "ERROR: Unable to create MUNGE context\n");
289 exit (1);
290 }
291 err = munge_ctx_get (ctx, MUNGE_OPT_SOCKET, &str);
292 if (err != EMUNGE_SUCCESS) {
294 fprintf (stderr, "ERROR: %s\n", munge_ctx_strerror (ctx));
295 exit (1);
296 }
297 printf ("socket=%s\n", str);
298 /*
299 * Note that 'str' is not to be free()d since
300 * it points to a string within the 'ctx'.
301 */
302 munge_ctx_destroy (ctx);
303 exit (0);
304 }
305
308 Abandoning a new or copied MUNGE context without destroying it will
309 result in a memory leak.
310 The context passed to munge_encode() is treated read-only except for
312 the error message that is set when an error is returned. The context
313 passed to munge_decode() is set according to the context used to encode
314 the credential; however, on error, its settings may be in a state which
315 is invalid for encoding. Consequently, separate contexts should be
316 used for encoding and decoding.
317 A context should not be shared between threads unless it is protected
319 by a mutex; however, a better alternative is to use a separate context
320 (or two) for each thread, either by creating a new one via
321 munge_ctx_create() or copying an existing one via munge_ctx_copy().
322
325 Chris Dunlap <cdunlap@llnl.gov>
326
329 Copyright (C) 2007-2017 Lawrence Livermore National Security, LLC.
330 Copyright (C) 2002-2007 The Regents of the University of California.
331 MUNGE is free software: you can redistribute it and/or modify it under
333 the terms of the GNU General Public License as published by the Free
334 Software Foundation, either version 3 of the License, or (at your
335 option) any later version.
336 Additionally for the MUNGE library (libmunge), you can redistribute it
338 and/or modify it under the terms of the GNU Lesser General Public
339 License as published by the Free Software Foundation, either version 3
340 of the License, or (at your option) any later version.
341
344 munge(1), remunge(1), unmunge(1), munge(3), munge_enum(3), munge(7),
345 munged(8).
346 https://dun.github.io/munge/
348munge-0.5.13 2017-09-26 MUNGE_CTX(3)