1 /***************************************************************************** 2 * Written by Chris Dunlap <cdunlap@llnl.gov>. 3 * Copyright (C) 2007-2020 Lawrence Livermore National Security, LLC. 4 * Copyright (C) 2002-2007 The Regents of the University of California. 5 * UCRL-CODE-155910. 6 * 7 * This file is part of the MUNGE Uid 'N' Gid Emporium (MUNGE). 8 * For details, see <https://dun.github.io/munge/>. 9 * 10 * MUNGE is free software: you can redistribute it and/or modify it under 11 * the terms of the GNU General Public License as published by the Free 12 * Software Foundation, either version 3 of the License, or (at your option) 13 * any later version. Additionally for the MUNGE library (libmunge), you 14 * can redistribute it and/or modify it under the terms of the GNU Lesser 15 * General Public License as published by the Free Software Foundation, 16 * either version 3 of the License, or (at your option) any later version. 17 * 18 * MUNGE is distributed in the hope that it will be useful, but WITHOUT 19 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 20 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 21 * and GNU Lesser General Public License for more details. 22 * 23 * You should have received a copy of the GNU General Public License 24 * and GNU Lesser General Public License along with MUNGE. If not, see 25 * <http://www.gnu.org/licenses/>. 26 *****************************************************************************/ 27 28 29 #ifndef MUNGE_H 30 #define MUNGE_H 31 32 #include <sys/types.h> 33 34 35 /***************************************************************************** 36 * Got C++? 37 *****************************************************************************/ 38 39 #undef BEGIN_C_DECLS 40 #undef END_C_DECLS 41 #ifdef __cplusplus 42 # define BEGIN_C_DECLS extern "C" { 43 # define END_C_DECLS } 44 #else /* !__cplusplus */ 45 # define BEGIN_C_DECLS /* empty */ 46 # define END_C_DECLS /* empty */ 47 #endif /* !__cplusplus */ 48 49 50 /***************************************************************************** 51 * Data Types 52 *****************************************************************************/ 53 54 /* MUNGE context opaque data type 55 */ 56 typedef struct munge_ctx * munge_ctx_t; 57 58 /* MUNGE context options 59 */ 60 typedef enum munge_opt { 61 MUNGE_OPT_CIPHER_TYPE = 0, /* symmetric cipher type (int) */ 62 MUNGE_OPT_MAC_TYPE = 1, /* message auth code type (int) */ 63 MUNGE_OPT_ZIP_TYPE = 2, /* compression type (int) */ 64 MUNGE_OPT_REALM = 3, /* security realm (str) */ 65 MUNGE_OPT_TTL = 4, /* time-to-live (int) */ 66 MUNGE_OPT_ADDR4 = 5, /* src IPv4 addr (struct in_addr) */ 67 MUNGE_OPT_ENCODE_TIME = 6, /* time when cred encoded (time_t) */ 68 MUNGE_OPT_DECODE_TIME = 7, /* time when cred decoded (time_t) */ 69 MUNGE_OPT_SOCKET = 8, /* socket for comm w/ daemon (str) */ 70 MUNGE_OPT_UID_RESTRICTION = 9, /* UID able to decode cred (uid_t) */ 71 MUNGE_OPT_GID_RESTRICTION = 10 /* GID able to decode cred (gid_t) */ 72 } munge_opt_t; 73 74 /* MUNGE symmetric cipher types 75 */ 76 typedef enum munge_cipher { 77 MUNGE_CIPHER_NONE = 0, /* encryption disabled */ 78 MUNGE_CIPHER_DEFAULT = 1, /* default ciphr specified by daemon */ 79 MUNGE_CIPHER_BLOWFISH = 2, /* Blowfish CBC w/ 64b-blk/128b-key */ 80 MUNGE_CIPHER_CAST5 = 3, /* CAST5 CBC w/ 64b-blk/128b-key */ 81 MUNGE_CIPHER_AES128 = 4, /* AES CBC w/ 128b-blk/128b-key */ 82 MUNGE_CIPHER_AES256 = 5, /* AES CBC w/ 128b-blk/256b-key */ 83 MUNGE_CIPHER_LAST_ITEM 84 } munge_cipher_t; 85 86 /* MUNGE message authentication code types 87 */ 88 typedef enum munge_mac { 89 MUNGE_MAC_NONE = 0, /* mac disabled -- invalid, btw */ 90 MUNGE_MAC_DEFAULT = 1, /* default mac specified by daemon */ 91 MUNGE_MAC_MD5 = 2, /* MD5 w/ 128b-digest */ 92 MUNGE_MAC_SHA1 = 3, /* SHA-1 w/ 160b-digest */ 93 MUNGE_MAC_RIPEMD160 = 4, /* RIPEMD-160 w/ 160b-digest */ 94 MUNGE_MAC_SHA256 = 5, /* SHA-256 w/ 256b-digest */ 95 MUNGE_MAC_SHA512 = 6, /* SHA-512 w/ 512b-digest */ 96 MUNGE_MAC_LAST_ITEM 97 } munge_mac_t; 98 99 /* MUNGE compression types 100 */ 101 typedef enum munge_zip { 102 MUNGE_ZIP_NONE = 0, /* compression disabled */ 103 MUNGE_ZIP_DEFAULT = 1, /* default zip specified by daemon */ 104 MUNGE_ZIP_BZLIB = 2, /* bzip2 by Julian Seward */ 105 MUNGE_ZIP_ZLIB = 3, /* zlib "deflate" by Gailly & Adler */ 106 MUNGE_ZIP_LAST_ITEM 107 } munge_zip_t; 108 109 /* MUNGE credential time-to-live (in seconds) 110 */ 111 typedef enum munge_ttl { 112 MUNGE_TTL_MAXIMUM = -1, /* maximum ttl allowed by daemon */ 113 MUNGE_TTL_DEFAULT = 0 /* default ttl specified by daemon */ 114 } munge_ttl_t; 115 116 /* MUNGE UID restrictions for credential decoding 117 */ 118 typedef enum munge_uid { 119 MUNGE_UID_ANY = -1 /* do not restrict decode via uid */ 120 } munge_uid_t; 121 122 /* MUNGE GID restrictions for credential decoding 123 */ 124 typedef enum munge_gid { 125 MUNGE_GID_ANY = -1 /* do not restrict decode via gid */ 126 } munge_gid_t; 127 128 /* MUNGE enum types for str/int conversions 129 */ 130 typedef enum munge_enum { 131 MUNGE_ENUM_CIPHER = 0, /* cipher enum type */ 132 MUNGE_ENUM_MAC = 1, /* mac enum type */ 133 MUNGE_ENUM_ZIP = 2 /* zip enum type */ 134 } munge_enum_t; 135 136 /* MUNGE error codes 137 * 138 * Error codes are in the range [1..255] in order to provide 139 * a meaningful return status when returned via exit(). 140 */ 141 typedef enum munge_err { 142 EMUNGE_SUCCESS = 0, /* Success: Whoohoo! */ 143 EMUNGE_SNAFU = 1, /* Internal error: Doh! */ 144 EMUNGE_BAD_ARG = 2, /* Invalid argument */ 145 EMUNGE_BAD_LENGTH = 3, /* Exceeded maximum message length */ 146 EMUNGE_OVERFLOW = 4, /* Buffer overflow */ 147 EMUNGE_NO_MEMORY = 5, /* Out of memory */ 148 EMUNGE_SOCKET = 6, /* Socket communication error */ 149 EMUNGE_TIMEOUT = 7, /* Socket timeout (NOT USED) */ 150 EMUNGE_BAD_CRED = 8, /* Invalid credential format */ 151 EMUNGE_BAD_VERSION = 9, /* Invalid credential version */ 152 EMUNGE_BAD_CIPHER = 10, /* Invalid cipher type */ 153 EMUNGE_BAD_MAC = 11, /* Invalid MAC type */ 154 EMUNGE_BAD_ZIP = 12, /* Invalid compression type */ 155 EMUNGE_BAD_REALM = 13, /* Unrecognized security realm */ 156 EMUNGE_CRED_INVALID = 14, /* Invalid credential */ 157 EMUNGE_CRED_EXPIRED = 15, /* Expired credential */ 158 EMUNGE_CRED_REWOUND = 16, /* Rewound credential, future ctime */ 159 EMUNGE_CRED_REPLAYED = 17, /* Replayed credential */ 160 EMUNGE_CRED_UNAUTHORIZED = 18 /* Unauthorized credential decode */ 161 } munge_err_t; 162 163 /* MUNGE defines for backwards-compatibility 164 */ 165 #define MUNGE_CIPHER_AES_128 MUNGE_CIPHER_AES128 166 167 168 /***************************************************************************** 169 * Primary Functions 170 *****************************************************************************/ 171 172 BEGIN_C_DECLS 173 174 munge_err_t munge_encode (char **cred, munge_ctx_t ctx, 175 const void *buf, int len); 176 /* 177 * Creates a credential contained in a NUL-terminated base64 string. 178 * A payload specified by a buffer [buf] of length [len] can be 179 * encapsulated in as well. 180 * If the munge context [ctx] is NULL, the default context will be used. 181 * A pointer to the resulting credential is returned via [cred]; the caller 182 * is responsible for freeing this memory. 183 * Returns EMUNGE_SUCCESS if the credential is successfully created; 184 * o/w, sets [cred] to NULL and returns the munge error number. 185 * If a [ctx] was specified, it may contain a more detailed error 186 * message accessible via munge_ctx_strerror(). 187 */ 188 189 munge_err_t munge_decode (const char *cred, munge_ctx_t ctx, 190 void **buf, int *len, uid_t *uid, gid_t *gid); 191 /* 192 * Validates the NUL-terminated credential [cred]. 193 * If the munge context [ctx] is not NULL, it will be set to that used 194 * to encode the credential. 195 * If [buf] and [len] are not NULL, memory will be allocated for the 196 * encapsulated payload, [buf] will be set to point to this data, and [len] 197 * will be set to its length. An additional NUL character will be appended 198 * to this payload data but not included in its length. If no payload 199 * exists, [buf] will be set to NULL and [len] will be set to 0. 200 * For certain errors (ie, EMUNGE_CRED_EXPIRED, EMUNGE_CRED_REWOUND, 201 * EMUNGE_CRED_REPLAYED), payload memory will still be allocated if 202 * necessary. The caller is responsible for freeing this memory. 203 * If [uid] or [gid] is not NULL, they will be set to the UID/GID of the 204 * process that created the credential. 205 * Returns EMUNGE_SUCCESS if the credential is valid; o/w, returns the 206 * munge error number. If a [ctx] was specified, it may contain a 207 * more detailed error message accessible via munge_ctx_strerror(). 208 */ 209 210 const char * munge_strerror (munge_err_t e); 211 /* 212 * Returns a descriptive string describing the munge errno [e]. 213 * This string should not be freed or modified by the caller. 214 */ 215 216 END_C_DECLS 217 218 219 /***************************************************************************** 220 * Context Functions 221 ***************************************************************************** 222 * The context passed to munge_encode() is treated read-only except for the 223 * error message that is set when an error is returned. 224 * The context passed to munge_decode() is set according to the context used 225 * to encode the credential; however, on error, its settings may be in a 226 * state which is invalid for encoding. 227 * Consequently, separate contexts should be used for encoding and decoding. 228 * A context should not be shared between threads unless it is protected by 229 * a mutex; however, a better alternative is to use a separate context 230 * (or two) for each thread, either by creating a new one or copying an 231 * existing one. 232 *****************************************************************************/ 233 234 BEGIN_C_DECLS 235 236 munge_ctx_t munge_ctx_create (void); 237 /* 238 * Creates and returns a new munge context or NULL on error. 239 * Abandoning a context without calling munge_ctx_destroy() will result 240 * in a memory leak. 241 */ 242 243 munge_ctx_t munge_ctx_copy (munge_ctx_t ctx); 244 /* 245 * Copies the context [ctx], returning a new munge context or NULL on error. 246 * Abandoning a context without calling munge_ctx_destroy() will result 247 * in a memory leak. 248 */ 249 250 void munge_ctx_destroy (munge_ctx_t ctx); 251 /* 252 * Destroys the context [ctx]. 253 */ 254 255 const char * munge_ctx_strerror (munge_ctx_t ctx); 256 /* 257 * Returns a descriptive text string describing the munge error number 258 * according to the context [ctx], or NULL if no error condition exists. 259 * This message may be more detailed than that returned by munge_strerror(). 260 * This string should not be freed or modified by the caller. 261 */ 262 263 munge_err_t munge_ctx_get (munge_ctx_t ctx, int opt, ...); 264 /* 265 * Gets the value for the option [opt] (of munge_opt_t) associated with the 266 * munge context [ctx], storing the result in the subsequent pointer 267 * argument. Refer to the munge_opt_t enum comments for argument types. 268 * If the result is a string, that string should not be freed or modified 269 * by the caller. 270 * Returns EMUNGE_SUCCESS on success; o/w, returns the munge error number. 271 */ 272 273 munge_err_t munge_ctx_set (munge_ctx_t ctx, int opt, ...); 274 /* 275 * Sets the value for the option [opt] (of munge_opt_t) associated with the 276 * munge context [ctx], using the value of the subsequent argument. 277 * Refer to the munge_opt_t enum comments for argument types. 278 * Returns EMUNGE_SUCCESS on success; o/w, returns the munge error number. 279 */ 280 281 END_C_DECLS 282 283 284 /***************************************************************************** 285 * Enumeration Functions 286 *****************************************************************************/ 287 288 BEGIN_C_DECLS 289 290 int munge_enum_is_valid (munge_enum_t type, int val); 291 /* 292 * Returns non-zero if the given value [val] is a valid enumeration of 293 * the specified type [type] in the software configuration as currently 294 * compiled; o/w, returns 0. 295 * Some enumerations corresond to options that can only be enabled at 296 * compile-time. 297 */ 298 299 const char * munge_enum_int_to_str (munge_enum_t type, int val); 300 /* 301 * Converts the munge enumeration [val] of the specified type [type] 302 * into a text string. 303 * Returns a NUL-terminated constant text string, or NULL on error; 304 * this string should not be freed or modified by the caller. 305 */ 306 307 int munge_enum_str_to_int (munge_enum_t type, const char *str); 308 /* 309 * Converts the NUL-terminated case-insensitive string [str] into the 310 * corresponding munge enumeration of the specified type [type]. 311 * Returns a munge enumeration on success (>=0), or -1 on error. 312 */ 313 314 END_C_DECLS 315 316 317 #endif /* !MUNGE_H */ 318