gfal2/common/gfal_cred_mapping.h

0001 /*
0002  * Copyright (c) CERN 2017
0003  *
0004  * Licensed under the Apache License, Version 2.0 (the "License");
0005  * you may not use this file except in compliance with the License.
0006  * You may obtain a copy of the License at
0007  *
0008  *    http://www.apache.org/licenses/LICENSE-2.0
0009  *
0010  * Unless required by applicable law or agreed to in writing, software
0011  * distributed under the License is distributed on an "AS IS" BASIS,
0012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0013  * See the License for the specific language governing permissions and
0014  * limitations under the License.
0015  */
0016
0017 #ifndef GFAL2_GFAL_CRED_MAPPING_H
0018 #define GFAL2_GFAL_CRED_MAPPING_H
0019
0020 #include "gfal_common.h"
0021
0022 #ifdef __cplusplus
0023 extern "C"
0024 {
0025 #endif
0026
0027 /* Predefined credential types
0028  * Some plugins may define their own
0029  */
0030
0031 /// No credential set
0032 #define GFAL_CRED_NONE NULL
0033 /// X509 user certificate, or proxy certificate
0034 #define GFAL_CRED_X509_CERT "X509_CERT"
0035 /// X509 user private key
0036 #define GFAL_CRED_X509_KEY "X509_KEY"
0037 /// User, usually combined with GFAL_CRED_PASSWD
0038 #define GFAL_CRED_USER "USER"
0039 /// Password, usually combined with GFAL_CRED_USER
0040 #define GFAL_CRED_PASSWD "PASSWORD"
0041 /// Bearer token-type credential
0042 #define GFAL_CRED_BEARER "BEARER"
0043
0044 /**
0045  * Stores a credential value together with its type
0046  * The specific value depends on the type.
0047  * @note Use gfal2_cred_new to create a new instance
0048  */
0049 typedef struct {
0050     char *type;
0051     char *value;
0052 } gfal2_cred_t;
0053
0054 /**
0055  * Callback type for gfal2_cred_foreach
0056  */
0057 typedef void (*gfal_cred_func_t)(const char *url_prefix, const gfal2_cred_t *cred, void *user_data);
0058
0059 /**
0060  * Create a new gfal2_cred_t
0061  * @return An initialized gfal2_cred_t
0062  */
0063 gfal2_cred_t *gfal2_cred_new(const char* type, const char *value);
0064
0065 /**
0066  * Release a gfal2_cred_t instance
0067   */
0068 void gfal2_cred_free(gfal2_cred_t *cred);
0069
0070 /**
0071  * Duplicate a gfal2_cred_t instance
0072  */
0073 gfal2_cred_t *gfal2_cred_dup(const gfal2_cred_t *cred);
0074
0075 /**
0076  * Set a credential for a given url prefix
0077  * @param handle        The gfal2 context
0078  * @param url_prefix    The URL prefix
0079  * @param cred          The credential to use for this prefix
0080  * @param error         In case of error
0081  * @return              0 on success, -1 on error
0082  * @note                The empty prefix is initialized by default with the environment X509_USER_* variables
0083  *                      or the [X509] configuration
0084  * @note                It will store its own copy of url_prefix and cred
0085  */
0086 int gfal2_cred_set(gfal2_context_t handle, const char *url_prefix, const gfal2_cred_t *cred, GError **error);
0087
0088 /**
0089  * Get a credential for a given url
0090  * @param handle        The gfal2 context
0091  * @param type          Credential type
0092  * @param url           Full URL. Best matching prefix will be picked.
0093  * @param baseurl       If not NULL, the chosen base url will be put here.
0094  * @param error         In case of error
0095  * @return              A credential suitable for the given url. NULL if nothing has been found. Remember to g_free it.
0096  */
0097 char *gfal2_cred_get(gfal2_context_t handle, const char *type, const char *url, char const** baseurl, GError **error);
0098
0099 /**
0100  * Remove the credential for a given type and url
0101  * @param handle        The gfal2 context
0102  * @param type          Credential type
0103  * @param url           Full URL. Only exact matching URL will be deleted
0104  * @param error         In case of error
0105  * @return              0 on success, -1 on error
0106  */
0107 int gfal2_cred_del(gfal2_context_t handle, const char *type, const char *url, GError **error);
0108
0109 /**
0110  * Remove all loaded credentials
0111  * @param handle        The gfal2 context
0112  * @param error         In case of error
0113  * @return              0 on success, -1 on error
0114  */
0115 int gfal2_cred_clean(gfal2_context_t handle, GError **error);
0116
0117 /**
0118  * Copy the credential list from one context to another
0119  * @param dest          Destination gfal2 context
0120  * @param src           Source gfal2 context
0121  * @param error         In case of error
0122  * @return              0 on success, -1 on error
0123  */
0124 int gfal2_cred_copy(gfal2_context_t dest, const gfal2_context_t src, GError **error);
0125
0126 /**
0127  * Iterate over all registered credentials
0128  * @param handle        The gfal2 context
0129  * @param callback      Callback for each item
0130  * @param user_data     To be passed to the callback
0131  */
0132 void gfal2_cred_foreach(gfal2_context_t handle, gfal_cred_func_t callback, void *user_data);
0133
0134 #ifdef __cplusplus
0135 }
0136 #endif
0137
0138 #endif //GFAL2_GFAL_CRED_MAPPING_H