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 ... -lmunge
27
30 The munge_ctx_create() function creates and returns a new munge context
31 or NULL or error.
32 The munge_ctx_copy() function copies the context ctx, returning 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_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 The munge_ctx_get() and munge_ctx_set() functions return EMUNGE_SUCCESS
62 on success; otherwise, a munge error number is returned.
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., ZIP 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 YET 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 memeber.
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 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), also known as a message
165 integrity code (MIC), is a required component of the credental; conse‐
166 quently, it cannot be disabled.
167 MUNGE_MAC_DEFAULT
169 Specify the default according to the munged configuration.
170 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 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 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.
222 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 MUNGE_ZIP_DEFAULT
229 Specify the default according to the munged configuration.
230 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 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
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 MUNGE_TTL_MAXIMUM
249 Specify the maximum allowed by the munged configuration.
250 MUNGE_TTL_DEFAULT
252 Specify the default according to the munged configuration.
253
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 MUNGE_UID_ANY
262 Specify that no UID restriction is to take effect; this is the
263 default behavior.
264 MUNGE_GID_ANY
266 Specify that no GID restriction is to take effect; this is the
267 default behavior.
268
271 Refer to munge(3) for a complete list of errors.
272
275 The following example program illustrates the use of the munge context
276 to query the location of the munged domain socket.
277 #include <stdio.h> /* for printf() */
279 #include <stdlib.h> /* for exit() */
280 #include <munge.h>
281 int
283 main (int argc, char *argv[])
284 {
285 munge_ctx_t ctx;
286 munge_err_t err;
287 char *str;
288 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 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
310 Abandoning a new or copied munge context without destroying it will
311 result in a memory leak.
312 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 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
327 Chris Dunlap <cdunlap@llnl.gov>
328
331 Copyright (C) 2007-2010 Lawrence Livermore National Security, LLC.
332 Copyright (C) 2002-2007 The Regents of the University of California.
333 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
345 munge(1), remunge(1), unmunge(1), munge(3), munge_enum(3), munge(7),
346 munged(8).
347 http://home.gna.org/munge/
349munge-0.5.9 2010-03-23 MUNGE_CTX(3)