source/include/munge.h

0001 /*****************************************************************************
0002  *  Written by Chris Dunlap <cdunlap@llnl.gov>.
0003  *  Copyright (C) 2007-2022 Lawrence Livermore National Security, LLC.
0004  *  Copyright (C) 2002-2007 The Regents of the University of California.
0005  *  UCRL-CODE-155910.
0006  *
0007  *  This file is part of the MUNGE Uid 'N' Gid Emporium (MUNGE).
0008  *  For details, see <https://dun.github.io/munge/>.
0009  *
0010  *  MUNGE is free software: you can redistribute it and/or modify it under
0011  *  the terms of the GNU General Public License as published by the Free
0012  *  Software Foundation, either version 3 of the License, or (at your option)
0013  *  any later version.  Additionally for the MUNGE library (libmunge), you
0014  *  can redistribute it and/or modify it under the terms of the GNU Lesser
0015  *  General Public License as published by the Free Software Foundation,
0016  *  either version 3 of the License, or (at your option) any later version.
0017  *
0018  *  MUNGE is distributed in the hope that it will be useful, but WITHOUT
0019  *  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0020  *  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
0021  *  and GNU Lesser General Public License for more details.
0022  *
0023  *  You should have received a copy of the GNU General Public License
0024  *  and GNU Lesser General Public License along with MUNGE.  If not, see
0025  *  <http://www.gnu.org/licenses/>.
0026  *****************************************************************************/
0027
0028
0029 #ifndef MUNGE_H
0030 #define MUNGE_H
0031
0032 #include <sys/types.h>
0033
0034
0035 /*****************************************************************************
0036  *  Got C++?
0037  *****************************************************************************/
0038
0039 #undef BEGIN_C_DECLS
0040 #undef END_C_DECLS
0041 #ifdef __cplusplus
0042 #  define BEGIN_C_DECLS         extern "C" {
0043 #  define END_C_DECLS           }
0044 #else  /* !__cplusplus */
0045 #  define BEGIN_C_DECLS         /* empty */
0046 #  define END_C_DECLS           /* empty */
0047 #endif /* !__cplusplus */
0048
0049
0050 /*****************************************************************************
0051  *  Data Types
0052  *****************************************************************************/
0053
0054 /*  MUNGE context opaque data type
0055  */
0056 typedef struct munge_ctx * munge_ctx_t;
0057
0058 /*  MUNGE context options
0059  */
0060 typedef enum munge_opt {
0061     MUNGE_OPT_CIPHER_TYPE       =  0,   /* symmetric cipher type (int)       */
0062     MUNGE_OPT_MAC_TYPE          =  1,   /* message auth code type (int)      */
0063     MUNGE_OPT_ZIP_TYPE          =  2,   /* compression type (int)            */
0064     MUNGE_OPT_REALM             =  3,   /* security realm (str)              */
0065     MUNGE_OPT_TTL               =  4,   /* time-to-live (int)                */
0066     MUNGE_OPT_ADDR4             =  5,   /* src IPv4 addr (struct in_addr)    */
0067     MUNGE_OPT_ENCODE_TIME       =  6,   /* time when cred encoded (time_t)   */
0068     MUNGE_OPT_DECODE_TIME       =  7,   /* time when cred decoded (time_t)   */
0069     MUNGE_OPT_SOCKET            =  8,   /* socket for comm w/ daemon (str)   */
0070     MUNGE_OPT_UID_RESTRICTION   =  9,   /* UID able to decode cred (uid_t)   */
0071     MUNGE_OPT_GID_RESTRICTION   = 10    /* GID able to decode cred (gid_t)   */
0072 } munge_opt_t;
0073
0074 /*  MUNGE symmetric cipher types
0075  */
0076 typedef enum munge_cipher {
0077     MUNGE_CIPHER_NONE           =  0,   /* encryption disabled               */
0078     MUNGE_CIPHER_DEFAULT        =  1,   /* default ciphr specified by daemon */
0079     MUNGE_CIPHER_BLOWFISH       =  2,   /* Blowfish CBC w/ 64b-blk/128b-key  */
0080     MUNGE_CIPHER_CAST5          =  3,   /* CAST5 CBC w/ 64b-blk/128b-key     */
0081     MUNGE_CIPHER_AES128         =  4,   /* AES CBC w/ 128b-blk/128b-key      */
0082     MUNGE_CIPHER_AES256         =  5,   /* AES CBC w/ 128b-blk/256b-key      */
0083     MUNGE_CIPHER_LAST_ITEM
0084 } munge_cipher_t;
0085
0086 /*  MUNGE message authentication code types
0087  */
0088 typedef enum munge_mac {
0089     MUNGE_MAC_NONE              =  0,   /* mac disabled -- invalid, btw      */
0090     MUNGE_MAC_DEFAULT           =  1,   /* default mac specified by daemon   */
0091     MUNGE_MAC_MD5               =  2,   /* MD5 w/ 128b-digest                */
0092     MUNGE_MAC_SHA1              =  3,   /* SHA-1 w/ 160b-digest              */
0093     MUNGE_MAC_RIPEMD160         =  4,   /* RIPEMD-160 w/ 160b-digest         */
0094     MUNGE_MAC_SHA256            =  5,   /* SHA-256 w/ 256b-digest            */
0095     MUNGE_MAC_SHA512            =  6,   /* SHA-512 w/ 512b-digest            */
0096     MUNGE_MAC_LAST_ITEM
0097 } munge_mac_t;
0098
0099 /*  MUNGE compression types
0100  */
0101 typedef enum munge_zip {
0102     MUNGE_ZIP_NONE              =  0,   /* compression disabled              */
0103     MUNGE_ZIP_DEFAULT           =  1,   /* default zip specified by daemon   */
0104     MUNGE_ZIP_BZLIB             =  2,   /* bzip2 by Julian Seward            */
0105     MUNGE_ZIP_ZLIB              =  3,   /* zlib "deflate" by Gailly & Adler  */
0106     MUNGE_ZIP_LAST_ITEM
0107 } munge_zip_t;
0108
0109 /*  MUNGE credential time-to-live (in seconds)
0110  */
0111 typedef enum munge_ttl {
0112     MUNGE_TTL_MAXIMUM           = -1,   /* maximum ttl allowed by daemon     */
0113     MUNGE_TTL_DEFAULT           =  0    /* default ttl specified by daemon   */
0114 } munge_ttl_t;
0115
0116 /*  MUNGE UID restrictions for credential decoding
0117  */
0118 typedef enum munge_uid {
0119     MUNGE_UID_ANY               = -1    /* do not restrict decode via uid    */
0120 } munge_uid_t;
0121
0122 /*  MUNGE GID restrictions for credential decoding
0123  */
0124 typedef enum munge_gid {
0125     MUNGE_GID_ANY               = -1    /* do not restrict decode via gid    */
0126 } munge_gid_t;
0127
0128 /*  MUNGE enum types for str/int conversions
0129  */
0130 typedef enum munge_enum {
0131     MUNGE_ENUM_CIPHER           =  0,   /* cipher enum type                  */
0132     MUNGE_ENUM_MAC              =  1,   /* mac enum type                     */
0133     MUNGE_ENUM_ZIP              =  2    /* zip enum type                     */
0134 } munge_enum_t;
0135
0136 /*  MUNGE error codes
0137  *
0138  *  Error codes are in the range [1..255] in order to provide
0139  *    a meaningful return status when returned via exit().
0140  */
0141 typedef enum munge_err {
0142     EMUNGE_SUCCESS              =  0,   /* Success: Whoohoo!                 */
0143     EMUNGE_SNAFU                =  1,   /* Internal error: Doh!              */
0144     EMUNGE_BAD_ARG              =  2,   /* Invalid argument                  */
0145     EMUNGE_BAD_LENGTH           =  3,   /* Exceeded maximum message length   */
0146     EMUNGE_OVERFLOW             =  4,   /* Buffer overflow                   */
0147     EMUNGE_NO_MEMORY            =  5,   /* Out of memory                     */
0148     EMUNGE_SOCKET               =  6,   /* Socket communication error        */
0149     EMUNGE_TIMEOUT              =  7,   /* Socket timeout (NOT USED)         */
0150     EMUNGE_BAD_CRED             =  8,   /* Invalid credential format         */
0151     EMUNGE_BAD_VERSION          =  9,   /* Invalid credential version        */
0152     EMUNGE_BAD_CIPHER           = 10,   /* Invalid cipher type               */
0153     EMUNGE_BAD_MAC              = 11,   /* Invalid MAC type                  */
0154     EMUNGE_BAD_ZIP              = 12,   /* Invalid compression type          */
0155     EMUNGE_BAD_REALM            = 13,   /* Unrecognized security realm       */
0156     EMUNGE_CRED_INVALID         = 14,   /* Invalid credential                */
0157     EMUNGE_CRED_EXPIRED         = 15,   /* Expired credential                */
0158     EMUNGE_CRED_REWOUND         = 16,   /* Rewound credential, future ctime  */
0159     EMUNGE_CRED_REPLAYED        = 17,   /* Replayed credential               */
0160     EMUNGE_CRED_UNAUTHORIZED    = 18    /* Unauthorized credential decode    */
0161 } munge_err_t;
0162
0163 /*  MUNGE defines for backwards-compatibility
0164  */
0165 #define MUNGE_CIPHER_AES_128 MUNGE_CIPHER_AES128
0166
0167
0168 /*****************************************************************************
0169  *  Primary Functions
0170  *****************************************************************************/
0171
0172 BEGIN_C_DECLS
0173
0174 munge_err_t munge_encode (char **cred, munge_ctx_t ctx,
0175                           const void *buf, int len);
0176 /*
0177  *  Creates a credential contained in a NUL-terminated base64 string.
0178  *    A payload specified by a buffer [buf] of length [len] can be
0179  *    encapsulated in as well.
0180  *  If the munge context [ctx] is NULL, the default context will be used.
0181  *  A pointer to the resulting credential is returned via [cred]; the caller
0182  *    is responsible for freeing this memory.
0183  *  Returns EMUNGE_SUCCESS if the credential is successfully created;
0184  *    o/w, sets [cred] to NULL and returns the munge error number.
0185  *    If a [ctx] was specified, it may contain a more detailed error
0186  *    message accessible via munge_ctx_strerror().
0187  */
0188
0189 munge_err_t munge_decode (const char *cred, munge_ctx_t ctx,
0190                           void **buf, int *len, uid_t *uid, gid_t *gid);
0191 /*
0192  *  Validates the NUL-terminated credential [cred].
0193  *  If the munge context [ctx] is not NULL, it will be set to that used
0194  *    to encode the credential.
0195  *  If [buf] and [len] are not NULL, memory will be allocated for the
0196  *    encapsulated payload, [buf] will be set to point to this data, and [len]
0197  *    will be set to its length.  An additional NUL character will be appended
0198  *    to this payload data but not included in its length.  If no payload
0199  *    exists, [buf] will be set to NULL and [len] will be set to 0.
0200  *    For certain errors (ie, EMUNGE_CRED_EXPIRED, EMUNGE_CRED_REWOUND,
0201  *    EMUNGE_CRED_REPLAYED), payload memory will still be allocated if
0202  *    necessary.  The caller is responsible for freeing this memory.
0203  *  If [uid] or [gid] is not NULL, they will be set to the UID/GID of the
0204  *    process that created the credential.
0205  *  Returns EMUNGE_SUCCESS if the credential is valid; o/w, returns the
0206  *    munge error number.  If a [ctx] was specified, it may contain a
0207  *    more detailed error message accessible via munge_ctx_strerror().
0208  */
0209
0210 const char * munge_strerror (munge_err_t e);
0211 /*
0212  *  Returns a descriptive string describing the munge errno [e].
0213  *    This string should not be freed or modified by the caller.
0214  */
0215
0216 END_C_DECLS
0217
0218
0219 /*****************************************************************************
0220  *  Context Functions
0221  *****************************************************************************
0222  *  The context passed to munge_encode() is treated read-only except for the
0223  *    error message that is set when an error is returned.
0224  *  The context passed to munge_decode() is set according to the context used
0225  *    to encode the credential; however, on error, its settings may be in a
0226  *    state which is invalid for encoding.
0227  *  Consequently, separate contexts should be used for encoding and decoding.
0228  *  A context should not be shared between threads unless it is protected by
0229  *    a mutex; however, a better alternative is to use a separate context
0230  *    (or two) for each thread, either by creating a new one or copying an
0231  *    existing one.
0232  *****************************************************************************/
0233
0234 BEGIN_C_DECLS
0235
0236 munge_ctx_t munge_ctx_create (void);
0237 /*
0238  *  Creates and returns a new munge context or NULL on error.
0239  *  Abandoning a context without calling munge_ctx_destroy() will result
0240  *    in a memory leak.
0241  */
0242
0243 munge_ctx_t munge_ctx_copy (munge_ctx_t ctx);
0244 /*
0245  *  Copies the context [ctx], returning a new munge context or NULL on error.
0246  *  Abandoning a context without calling munge_ctx_destroy() will result
0247  *    in a memory leak.
0248  */
0249
0250 void munge_ctx_destroy (munge_ctx_t ctx);
0251 /*
0252  *  Destroys the context [ctx].
0253  */
0254
0255 const char * munge_ctx_strerror (munge_ctx_t ctx);
0256 /*
0257  *  Returns a descriptive text string describing the munge error number
0258  *    according to the context [ctx], or NULL if no error condition exists.
0259  *  This message may be more detailed than that returned by munge_strerror().
0260  *  This string should not be freed or modified by the caller.
0261  */
0262
0263 munge_err_t munge_ctx_get (munge_ctx_t ctx, int opt, ...);
0264 /*
0265  *  Gets the value for the option [opt] (of munge_opt_t) associated with the
0266  *    munge context [ctx], storing the result in the subsequent pointer
0267  *    argument.  Refer to the munge_opt_t enum comments for argument types.
0268  *    If the result is a string, that string should not be freed or modified
0269  *    by the caller.
0270  *  Returns EMUNGE_SUCCESS on success; o/w, returns the munge error number.
0271  */
0272
0273 munge_err_t munge_ctx_set (munge_ctx_t ctx, int opt, ...);
0274 /*
0275  *  Sets the value for the option [opt] (of munge_opt_t) associated with the
0276  *    munge context [ctx], using the value of the subsequent argument.
0277  *    Refer to the munge_opt_t enum comments for argument types.
0278  *  Returns EMUNGE_SUCCESS on success; o/w, returns the munge error number.
0279  */
0280
0281 END_C_DECLS
0282
0283
0284 /*****************************************************************************
0285  *  Enumeration Functions
0286  *****************************************************************************/
0287
0288 BEGIN_C_DECLS
0289
0290 int munge_enum_is_valid (munge_enum_t type, int val);
0291 /*
0292  *  Returns non-zero if the given value [val] is a valid enumeration of
0293  *    the specified type [type] in the software configuration as currently
0294  *    compiled; o/w, returns 0.
0295  *  Some enumerations corresond to options that can only be enabled at
0296  *    compile-time.
0297  */
0298
0299 const char * munge_enum_int_to_str (munge_enum_t type, int val);
0300 /*
0301  *  Converts the munge enumeration [val] of the specified type [type]
0302  *    into a text string.
0303  *  Returns a NUL-terminated constant text string, or NULL on error;
0304  *    this string should not be freed or modified by the caller.
0305  */
0306
0307 int munge_enum_str_to_int (munge_enum_t type, const char *str);
0308 /*
0309  *  Converts the NUL-terminated case-insensitive string [str] into the
0310  *    corresponding munge enumeration of the specified type [type].
0311  *  Returns a munge enumeration on success (>=0), or -1 on error.
0312  */
0313
0314 END_C_DECLS
0315
0316
0317 #endif /* !MUNGE_H */