1
1
.\"****************************************************************************
2
.\" $Id: munge_ctx.3.in 771 2010-03-02 23:14:07Z dun $
2
.\" $Id: munge_ctx.3.in 918 2011-02-16 18:19:25Z chris.m.dunlap $
3
3
.\"****************************************************************************
4
4
.\" Written by Chris Dunlap <cdunlap@llnl.gov>.
5
.\" Copyright (C) 2007-2010 Lawrence Livermore National Security, LLC.
5
.\" Copyright (C) 2007-2011 Lawrence Livermore National Security, LLC.
6
6
.\" Copyright (C) 2002-2007 The Regents of the University of California.
7
7
.\" UCRL-CODE-155910.
9
9
.\" This file is part of the MUNGE Uid 'N' Gid Emporium (MUNGE).
10
.\" For details, see <http://home.gna.org/munge/>.
10
.\" For details, see <http://munge.googlecode.com/>.
12
12
.\" MUNGE is free software: you can redistribute it and/or modify it under
13
13
.\" the terms of the GNU General Public License as published by the Free
55
The \fBmunge_ctx_create\fR() function creates and returns a new munge context
55
The \fBmunge_ctx_create\fR() function creates and returns a new MUNGE context,
58
The \fBmunge_ctx_copy\fR() function copies the context \fIctx\fR, returning
59
a new munge context or NULL on error.
58
The \fBmunge_ctx_copy\fR() function copies the context \fIctx\fR and returns
59
a new MUNGE context, or NULL on error.
61
61
The \fBmunge_ctx_destroy\fR() function destroys the context \fIctx\fR.
63
63
The \fBmunge_ctx_strerror\fR() function returns a descriptive text string
64
describing the munge error number according to the context \fIctx\fR, or
64
describing the MUNGE error number according to the context \fIctx\fR, or
65
65
NULL if no error condition exists. This may provide a more detailed error
66
66
message than that returned by \fBmunge_strerror\fR().
68
68
The \fBmunge_ctx_get\fR() function gets the value for the option \fIopt\fR
69
associated with the munge context \fIctx\fR, storing the result in the
69
associated with the MUNGE context \fIctx\fR, storing the result in the
70
70
subsequent pointer argument. If the result is a string, that string should
71
71
not be freed or modified by the caller.
73
73
The \fBmunge_ctx_set\fR() function sets the value for the option \fIopt\fR
74
associated with the munge context \fIctx\fR, using the value of the subsequent
74
associated with the MUNGE context \fIctx\fR, using the value of the
78
The \fBmunge_ctx_create\fR() and \fBmunge_ctx_copy\fR() functions return a
79
newly allocated munge context, or NULL on error.
78
The \fBmunge_ctx_create\fR() and \fBmunge_ctx_copy\fR() functions return
79
a newly allocated MUNGE context, or NULL on error.
81
The \fBmunge_cxt_strerror\fR() function returns a pointer to a NUL-terminated
82
constant text string; this string should not be freed or modified by the
81
The \fBmunge_ctx_strerror\fR() function returns a pointer to a NUL-terminated
82
constant text string, or NULL if no error condition exists. This string
83
should not be freed or modified by the caller.
85
85
The \fBmunge_ctx_get\fR() and \fBmunge_ctx_set\fR() functions return
86
\fBEMUNGE_SUCCESS\fR on success; otherwise, a munge error number is returned.
86
\fBEMUNGE_SUCCESS\fR on success, or a MUNGE error number otherwise.
88
88
.SH "CONTEXT OPTIONS"
89
89
The following context options can be queried via \fBmunge_ctx_get\fR() or
99
99
Get or set the MAC type (cf., \fBMAC TYPES\fR).
101
101
\fBMUNGE_OPT_ZIP_TYPE\fR , \fIint\fR
102
Get or set the compression type (cf., \fBZIP TYPES\fR).
102
Get or set the compression type (cf., \fBCOMPRESSION TYPES\fR).
104
104
\fBMUNGE_OPT_REALM\fR , \fIchar *\fR
105
Get or set the security realm, where the \fIchar *\fR type is a
106
NUL-terminated character string. The string returned by \fBmunge_ctx_get\fR()
107
should not be freed or modified by the caller. \fBNOT YET SUPPORTED\fR.
105
Get or set the security realm, where the \fIchar *\fR type is a NUL-terminated
106
character string. The string returned by \fBmunge_ctx_get\fR() should not
107
be freed or modified by the caller. \fBNOT CURRENTLY SUPPORTED\fR.
109
109
\fBMUNGE_OPT_TTL\fR , \fIint\fR
110
Get or set the time-to-live (in seconds) (cf., \fBTTL TYPES\fR).
111
This value controls how long the credential is valid once it has been encoded.
110
Get or set the time-to-live (in seconds) (cf., \fBTTL TYPES\fR). This value
111
controls how long the credential is valid once it has been encoded.
113
113
\fBMUNGE_OPT_ADDR4\fR , \fIstruct in_addr\fR
114
114
Get the IPv4 address of the host where the credential was encoded.
123
123
This option cannot be explicitly set.
125
125
\fBMUNGE_OPT_SOCKET\fR , \fIchar *\fR
126
Get or set the local domain socket for connecting with \fBmunged\fR, where
127
the \fIchar *\fR type is a NUL-terminated character string. The string
128
returned by \fBmunge_ctx_get\fR() should not be freed or modified by the
126
Get or set the local domain socket for connecting with \fBmunged\fR, where the
127
\fIchar *\fR type is a NUL-terminated character string. The string returned
128
by \fBmunge_ctx_get\fR() should not be freed or modified by the caller.
131
130
\fBMUNGE_OPT_UID_RESTRICTION\fR , \fIuid_t\fR
132
131
Get or set the UID allowed to decode the credential (cf., \fBUID & GID
133
TYPES\fR). This value will be matched against the effective user ID of the
134
process requesting the credential decode.
132
TYPES\fR). This value will be matched against the effective user ID of
133
the process requesting the credential decode.
136
135
\fBMUNGE_OPT_GID_RESTRICTION\fR , \fIgid_t\fR
137
136
Get or set the GID allowed to decode the credential (cf., \fBUID & GID
138
137
TYPES\fR). This value will be matched against the effective group ID of
139
138
the process requesting the credential decode, as well as each supplementary
140
group of which the effective user ID of that process is a memeber.
139
group of which the effective user ID of that process is a member.
142
141
.SH "CIPHER TYPES"
143
142
Credentials can be encrypted using the secret key shared by all \fBmunged\fR
144
daemons within a security realm. Anyone having access to this key can use
145
it to decrypt a credential, thereby bypassing any restrictions being imposed
143
daemons within a security realm. Anyone having access to this key can
144
use it to decrypt a credential, thereby bypassing any restrictions being
145
imposed by \fBmunged\fR.
148
147
.B MUNGE_CIPHER_NONE
149
Specify encryption is to be disabled.
148
Specify that encryption is to be disabled.
151
150
.B MUNGE_CIPHER_DEFAULT
152
151
Specify the default according to the \fBmunged\fR configuration.
165
164
.B MUNGE_CIPHER_AES128
166
165
Specify the AES (Advanced Encryption Standard) cipher, also known as Rijndael.
167
It was designed by Joan Daemen and Vincent Rijmen. This cipher has a 128-bit
168
block-size and a key length of 128, 192, or 256 bits. MUNGE uses it here with
169
a 128-bit key in CBC mode.
166
It was designed by Joan Daemen and Vincent Rijmen. This cipher has a
167
128-bit block-size and a key length of 128, 192, or 256 bits. MUNGE uses
168
it here with a 128-bit key in CBC mode.
171
170
.B MUNGE_CIPHER_AES256
172
171
Specify the AES (Advanced Encryption Standard) cipher, also known as Rijndael.
173
172
It was designed by Joan Daemen and Vincent Rijmen. This cipher has a 128-bit
174
block-size and a key length of 128, 192, or 256 bits. MUNGE uses it here with
175
a 256-bit key in CBC mode. Currently, MUNGE_CIPHER_AES256 requires the use of
173
block-size and a key length of 128, 192, or 256 bits. MUNGE uses it here
174
with a 256-bit key in CBC mode. Currently, \fBMUNGE_CIPHER_AES256\fR
175
requires the use of \fBMUNGE_MAC_SHA256\fR.
179
The message authentication code (MAC), also known as a message integrity code
180
(MIC), is a required component of the credental; consequently, it cannot
178
The message authentication code (MAC) is a required component of the
179
credential; consequently, it cannot be disabled.
183
181
.B MUNGE_MAC_DEFAULT
184
182
Specify the default according to the \fBmunged\fR configuration.
187
Specify the MD5 algorithm designed by Ron Rivest and published in 1991. This
188
algorithm has a 128-bit message digest. In 2004, a successful collision attack
189
was demonstrated against MD5. But since a pre-image attack has not yet been
190
demonstrated, MD5 should still be safe to use within MUNGE. However, use of
191
SHA-1, RIPEMD-160, or SHA-256 is recommended in order to provide a better
185
Specify the MD5 algorithm designed by Ron Rivest and published in 1991.
186
This algorithm has a 128-bit message digest. In 2004, a successful
187
collision attack against MD5 was demonstrated. In 2009, a theoretical
188
pre-image attack against MD5 was published. Consequently, use of MD5 is
189
not recommended due to its lower security margin.
194
191
.B MUNGE_MAC_SHA1
195
Specify the SHA-1 algorithm designed by the National Security Agency and
196
published in 1995; this is the successor to the original Secure Hash Algorithm
197
(now called SHA-0) published in 1993. This algorithm has a 160-bit message
198
digest. In 2005, successful collision attacks were demonstrated against SHA-1.
199
But since a pre-image attack has not yet been demonstrated, SHA-1 should still
200
be safe to use within MUNGE. NIST has announced plans to phase out the use of
201
SHA-1 by 2010 in favor of the SHA-2 variants.
192
Specify the SHA-1 algorithm designed by the National Security Agency
193
and published in 1995; this is the successor to the original Secure Hash
194
Algorithm (now called SHA-0) published in 1993. This algorithm has a 160-bit
195
message digest. In 2005, successful collision attacks were demonstrated
196
against SHA-1. But since a pre-image attack has not yet been demonstrated,
197
SHA-1 should still be safe to use within MUNGE.
203
199
.B MUNGE_MAC_RIPEMD160
204
200
Specify the RIPEMD-160 (RACE Integrity Primitives Evaluation Message Digest)
222
218
NIST began encouraging the use of the SHA-2 family of hash functions for
223
219
all new applications and protocols.
226
If a compression type is specified, a payload-bearing credential will be
227
compressed accordingly. However, if the resulting compressed data is larger
228
than the original uncompressed data, the uncompressed data will be restored
229
and compression will be disabled.
221
.SH "COMPRESSION TYPES"
222
If a compression type is specified, a payload-bearing credential will
223
be compressed accordingly. However, if the resulting compressed data is
224
larger than the original uncompressed data, the uncompressed data will be
225
restored and compression will be disabled for that credential.
231
227
.B MUNGE_ZIP_NONE
232
Specify compression is to be disabled. This is the recommended setting
228
Specify that compression is to be disabled. This is the recommended setting
233
229
unless there is a payload of sufficient size to compress.
235
231
.B MUNGE_ZIP_DEFAULT
236
232
Specify the default according to the \fBmunged\fR configuration.
238
234
.B MUNGE_ZIP_BZLIB
239
Specify the bzip2 algorithm developed by Julian Seward. This algorithm
240
is slower and uses more memory, but generally gets the best compression on
235
Specify the bzip2 library developed by Julian Seward. This is slower and
236
uses more memory, but generally gets better compression on larger payloads.
243
238
.B MUNGE_ZIP_ZLIB
244
Specify the zlib "deflate" algorithm developed by Jean-loup Gailly and
245
Mark Adler. This algorithm is faster and uses less memory, but gets pretty
246
good compression nonetheless.
239
Specify the zlib library developed by Jean-loup Gailly and Mark Adler.
240
This is faster and uses less memory, but gets pretty good compression
249
The time-to-live value specifies the number of seconds the credential is
250
considered valid from the time it was encoded according to the clock on the
251
host on which it was encoded. In addition to specifying an integer value,
252
the following types are available.
244
The time-to-live value specifies the number of seconds after the encode-time
245
that the credential is considered valid. In addition to specifying an
246
integer value, the following types are available.
254
248
.B MUNGE_TTL_MAXIMUM
255
249
Specify the maximum allowed by the \fBmunged\fR configuration.
313
Abandoning a new or copied munge context without destroying it will result
307
Abandoning a new or copied MUNGE context without destroying it will result
314
308
in a memory leak.
316
310
The context passed to \fBmunge_encode\fR() is treated read-only except
317
311
for the error message that is set when an error is returned. The context
318
passed to \fBmunge_decode\fR() is set according to the context used to encode
319
the credential; however, on error, its settings may be in a state which is
320
invalid for encoding. Consequently, separate contexts should be used for
321
encoding and decoding.
312
passed to \fBmunge_decode\fR() is set according to the context used to
313
encode the credential; however, on error, its settings may be in a state
314
which is invalid for encoding. Consequently, separate contexts should be
315
used for encoding and decoding.
323
317
A context should not be shared between threads unless it is protected by a
324
318
mutex; however, a better alternative is to use a separate context (or two)
332
Copyright (C) 2007-2010 Lawrence Livermore National Security, LLC.
326
Copyright (C) 2007-2011 Lawrence Livermore National Security, LLC.
334
328
Copyright (C) 2002-2007 The Regents of the University of California.
336
MUNGE is free software: you can redistribute it and/or modify it under
337
the terms of the GNU General Public License as published by the Free
338
Software Foundation, either version 3 of the License, or (at your option)
339
any later version. Additionally for the MUNGE library (libmunge), you
340
can redistribute it and/or modify it under the terms of the GNU Lesser
341
General Public License as published by the Free Software Foundation,
342
either version 3 of the License, or (at your option) any later version.
330
MUNGE is free software: you can redistribute it and/or modify it under the
331
terms of the GNU General Public License as published by the Free Software
332
Foundation, either version 3 of the License, or (at your option) any later
335
Additionally for the MUNGE library (libmunge), you can redistribute it
336
and/or modify it under the terms of the GNU Lesser General Public License as
337
published by the Free Software Foundation, either version 3 of the License,
338
or (at your option) any later version.
added
removed
src/libmunge/munge_ctx.3.in
