00001 /** @file include/dmlite/c/dmlite.h 00002 * @brief C wrapper for DMLite 00003 * @author Alejandro Álvarez Ayllon <aalvarez@cern.ch> 00004 */ 00005 #ifndef DMLITE_DMLITE_H 00006 #define DMLITE_DMLITE_H 00007 00008 #include "dmlite/common/config.h" 00009 #include "dmlite/common/errno.h" 00010 #include "any.h" 00011 00012 #include <stdlib.h> 00013 #include <sys/stat.h> 00014 #include <utime.h> 00015 00016 #ifdef __cplusplus 00017 extern "C" { 00018 #endif 00019 00020 /** @brief Handle for the plugin manager. */ 00021 typedef struct dmlite_manager dmlite_manager; 00022 /** @brief Handle for a initialized context. */ 00023 typedef struct dmlite_context dmlite_context; 00024 00025 /** @brief Security credentials 00026 * @details It is up to the caller to allocate and free this pointers. 00027 * DMLite will keep a copy internaly. 00028 * Non used values MUST be NULL. 00029 */ 00030 typedef struct dmlite_credentials { 00031 const char* mech; 00032 const char* client_name; 00033 const char* remote_address; 00034 const char* session_id; 00035 00036 unsigned nfqans; 00037 const char** fqans; 00038 00039 // These fields may come from openid-connect 00040 const char *oidc_audience; 00041 const char *oidc_issuer; 00042 const char *oidc_scope; 00043 00044 dmlite_any_dict* extra; 00045 } dmlite_credentials; 00046 00047 /** @brief Used to handle user and group information 00048 */ 00049 typedef struct dmlite_security_ent { 00050 const char* name; 00051 dmlite_any_dict* extra; 00052 } dmlite_security_ent; 00053 00054 /** @brief Security context 00055 */ 00056 typedef struct dmlite_security_context { 00057 dmlite_credentials* credentials; 00058 00059 unsigned ngroups; 00060 dmlite_security_ent user; 00061 dmlite_security_ent* groups; 00062 } dmlite_security_context; 00063 00064 /** 00065 * @brief Gets the API version. 00066 */ 00067 unsigned dmlite_api_version(void); 00068 00069 /** 00070 * @brief Initializes a dmlite_manager. 00071 * @return NULL on failure. 00072 */ 00073 dmlite_manager* dmlite_manager_new(void); 00074 00075 /** 00076 * @brief Destroys the manager. 00077 * @param manager The manager to be destroyed. 00078 */ 00079 int dmlite_manager_free(dmlite_manager* manager); 00080 00081 /** 00082 * @brief Loads a library. 00083 * @param manager The plugin manager. 00084 * @param lib The .so file. Usually, (path)/plugin_name.so. 00085 * @param id The plugin ID. Usually, plugin_name. 00086 * @return 0 on success, error code otherwise. 00087 */ 00088 int dmlite_manager_load_plugin(dmlite_manager *manager, const char* lib, const char* id); 00089 00090 /** 00091 * @brief Sets a configuration parameter. 00092 * @param manager The plugin manager. 00093 * @param key The parameter to set. 00094 * @param value The value. 00095 * @return 0 on success, error code otherwise. 00096 */ 00097 int dmlite_manager_set(dmlite_manager* manager, const char* key, const char* value); 00098 00099 /** 00100 * @brief Loads a configuration file. 00101 * @param manager The plugin manager. 00102 * @param file The configuration file 00103 * @return 0 on success, error code otherwise. 00104 */ 00105 int dmlite_manager_load_configuration(dmlite_manager* manager, const char* file); 00106 00107 /** 00108 * @brief Returns the associated value with the given key. 00109 * @param manager The plugin manager. 00110 * @param key The configuration parameter. 00111 * @param buffer Where to leave the string. 00112 * @param bufsize The buffer size. 00113 */ 00114 int dmlite_manager_get(dmlite_manager* handle, const char* key, char* buffer, size_t bufsize); 00115 00116 /** 00117 * @brief Returns the last error code. 00118 * @param manager The plugin manager used in the failing function. 00119 * @return The last error code, WITHOUT the error type byte. 00120 */ 00121 int dmlite_manager_errno(dmlite_manager* manager); 00122 00123 /** 00124 * @brief Returns the type of the last error. 00125 * @param manager The plugin manager used in the failing function. 00126 * @return The last error type byte. 00127 */ 00128 int dmlite_manager_errtype(dmlite_manager* manager); 00129 00130 /** 00131 * @brief Returns the string that describes the last error. 00132 * @param manager The plugin manager used in the failing function. 00133 * @return A pointer to the error string. Do NOT free it. 00134 */ 00135 const char* dmlite_manager_error(dmlite_manager* manager); 00136 00137 /** 00138 * @brief Returns a usable context from the loaded libraries. 00139 * @param manager The plugin manager. 00140 * @return NULL on failure. The error code can be checked with dmlite_manager_error. 00141 * @note A context is NOT thread safe. 00142 */ 00143 dmlite_context* dmlite_context_new(dmlite_manager* manager); 00144 00145 /** 00146 * @brief Destroys the context. 00147 * @param context The context to free. 00148 * @return 0 on success, error code otherwise. 00149 */ 00150 int dmlite_context_free(dmlite_context* context); 00151 00152 /** 00153 * @brief Returns the error code from the last failure. 00154 * @param context The context that was used in the failed function. 00155 * @return The error code. 00156 */ 00157 int dmlite_errno(dmlite_context* context); 00158 00159 /** 00160 * @brief Returns the type of the last error. 00161 * @param context The context that was used in the failed function. 00162 * @return The error type. 00163 */ 00164 int dmlite_errtype(dmlite_context* context); 00165 00166 /** 00167 * @brief Error string from the last failed function. 00168 * @param context The context that was used in the failed function. 00169 * @return A string with the error description. Do NOT free it. 00170 */ 00171 const char* dmlite_error(dmlite_context* context); 00172 00173 /** 00174 * @brief Sets the user security credentials. 00175 * @param context The DM context. 00176 * @param cred The security credentials. 00177 * @return 0 on success, error code otherwise. 00178 */ 00179 int dmlite_setcredentials(dmlite_context* context, const dmlite_credentials* cred); 00180 00181 /** 00182 * @brief Returns the security context. There is no need to free. 00183 * @param context The DM context. 00184 * @return The security context. 00185 */ 00186 const dmlite_security_context* dmlite_get_security_context(dmlite_context* context); 00187 00188 /** 00189 * @brief Sets a configuration parameter tied to a context. 00190 * @details This can be used to pass advanced parameters to a plugin. 00191 * @param context The DM context. 00192 * @param k The configuration key. 00193 * @param v Value. 00194 * @return 0 on success, error code otherwise. 00195 */ 00196 int dmlite_set(dmlite_context* context, const char* k, const dmlite_any* v); 00197 00198 /** 00199 * @brief Sets a configuration parameter tied to a context (array version). 00200 * @param context The DM context. 00201 * @param k The configuration key. 00202 * @param n The configuration key. 00203 * @param v Array of values. 00204 * @return 0 on success, error code otherwise. 00205 */ 00206 int dmlite_set_array(dmlite_context* context, const char* k, 00207 unsigned n, dmlite_any* const* v); 00208 00209 /** 00210 * @brief Removes a configuration parameter. 00211 * @param context The DM context. 00212 * @param k The configuration key. 00213 * @return 0 on success, error code otherwise. 00214 */ 00215 int dmlite_unset(dmlite_context* context, const char* k); 00216 00217 /** 00218 * @brief Removes all configuration parameters previously set. 00219 * @param context The DM context. 00220 * @return 0 on success, error code otherwise. 00221 */ 00222 int dmlite_unset_all(dmlite_context* context); 00223 00224 #ifdef __cplusplus 00225 } 00226 #endif 00227 00228 #endif /* DMLITE_DMLITE_H */