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 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 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 ar‐
50 gument.
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 (see CIPHER TYPES).
74 MUNGE_OPT_MAC_TYPE , int
76 Get or set the MAC type (see MAC TYPES).
77 MUNGE_OPT_ZIP_TYPE , int
79 Get or set the compression type (see 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) (see 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 en‐
94 coded. 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 (see 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 (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
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 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 ci‐
139 pher 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 se‐
176 curity 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. 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 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 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 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
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 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 MUNGE_ZIP_DEFAULT
229 Specify the default according to the munged configuration.
230 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 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
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 MUNGE_TTL_MAXIMUM
248 Specify the maximum allowed by the munged configuration.
249 MUNGE_TTL_DEFAULT
251 Specify the default according to the munged configuration.
252
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 MUNGE_UID_ANY
261 Specify that no UID restriction is to take effect; this is the
262 default behavior.
263 MUNGE_GID_ANY
265 Specify that no GID restriction is to take effect; this is the
266 default behavior.
267
270 Refer to munge(3) for a complete list of errors.
271
274 The following example program illustrates the use of the MUNGE context
275 to query the location of the munged domain socket.
276 #include <stdio.h> /* for printf() */
278 #include <stdlib.h> /* for exit() */
279 #include <munge.h>
280 int
282 main (int argc, char *argv[])
283 {
284 munge_ctx_t ctx;
285 munge_err_t err;
286 char *str;
287 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 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
309 Abandoning a new or copied MUNGE context without destroying it will re‐
310 sult in a memory leak.
311 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 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
326 Chris Dunlap <cdunlap@llnl.gov>
327
330 Copyright (C) 2007-2020 Lawrence Livermore National Security, LLC.
331 Copyright (C) 2002-2007 The Regents of the University of California.
332 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 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
345 munge(1), remunge(1), unmunge(1), munge(3), munge_enum(3), munge(7),
346 munged(8), mungekey(8).
347 https://dun.github.io/munge/
349munge-0.5.14 2020-01-14 MUNGE_CTX(3)