source/include/H5FDros3.h

0001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
0002  * Copyright by The HDF Group.                                               *
0003  * All rights reserved.                                                      *
0004  *                                                                           *
0005  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
0006  * terms governing use, modification, and redistribution, is contained in    *
0007  * the COPYING file, which can be found at the root of the source code       *
0008  * distribution tree, or in https://www.hdfgroup.org/licenses.               *
0009  * If you do not have access to either file, you may request a copy from     *
0010  * help@hdfgroup.org.                                                        *
0011  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
0012
0013 /*
0014  * Purpose: The public header file for the read-only S3 (ros3) virtual file driver (VFD)
0015  */
0016 #ifndef H5FDros3_H
0017 #define H5FDros3_H
0018
0019 #ifdef H5_HAVE_ROS3_VFD
0020
0021 /** Initializer for the ros3 VFD \since 1.8.22 */
0022 #define H5FD_ROS3 (H5FDperform_init(H5FD_ros3_init))
0023
0024 /** Identifier for the ros3 VFD \since 1.14.0 */
0025 #define H5FD_ROS3_VALUE H5_VFD_ROS3
0026
0027 #else
0028 /** Initializer for the ros3 VFD (disabled) \since 1.8.22 */
0029 #define H5FD_ROS3       (H5I_INVALID_HID)
0030
0031 /** Identifier for the ros3 VFD (disabled) \since 1.14.0 */
0032 #define H5FD_ROS3_VALUE H5_VFD_INVALID
0033 #endif
0034
0035 #ifdef H5_HAVE_ROS3_VFD
0036
0037 /****************************************************************************
0038  *
0039  * Structure: H5FD_ros3_fapl_t
0040  *
0041  * Purpose:
0042  *
0043  *     H5FD_ros3_fapl_t is a public structure that is used to pass S3
0044  *     authentication data to the appropriate S3 VFD via the FAPL.  A pointer
0045  *     to an instance of this structure is a parameter to H5Pset_fapl_ros3()
0046  *     and H5Pget_fapl_ros3().
0047  *
0048  *
0049  *
0050  * `version` (int32_t)
0051  *
0052  *     Version number of the H5FD_ros3_fapl_t structure.  Any instance passed
0053  *     to the above calls must have a recognized version number, or an error
0054  *     will be flagged.
0055  *
0056  *     This field should be set to H5FD_CURR_ROS3_FAPL_T_VERSION.
0057  *
0058  * `authenticate` (hbool_t)
0059  *
0060  *     Flag true or false whether or not requests are to be authenticated
0061  *     with the AWS4 algorithm.
0062  *     If true, `aws_region`, `secret_id`, and `secret_key` must be populated.
0063  *     If false, those three components are unused.
0064  *
0065  * `aws_region` (char[])
0066  *
0067  *     String: name of the AWS "region" of the host, e.g. "us-east-1".
0068  *
0069  * `secret_id` (char[])
0070  *
0071  *     String: "Access ID" for the resource.
0072  *
0073  * `secret_key` (char[])
0074  *
0075  *     String: "Secret Access Key" associated with the ID and resource.
0076  *
0077  ****************************************************************************/
0078
0079 /**
0080  * \def H5FD_CURR_ROS3_FAPL_T_VERSION
0081  * The version number of the H5FD_ros3_fapl_t configuration
0082  * structure for the $H5FD_ROS3 driver.
0083  */
0084 #define H5FD_CURR_ROS3_FAPL_T_VERSION 1
0085
0086 /**
0087  * \def H5FD_ROS3_MAX_REGION_LEN
0088  * Maximum string length for specifying the region of the S3 bucket.
0089  *
0090  * \since 1.10.6
0091  */
0092 #define H5FD_ROS3_MAX_REGION_LEN 32
0093 /**
0094  * \def H5FD_ROS3_MAX_SECRET_ID_LEN
0095  * Maximum string length for specifying the security ID.
0096  *
0097  * \since 1.10.6
0098  */
0099 #define H5FD_ROS3_MAX_SECRET_ID_LEN 128
0100 /**
0101  * \def H5FD_ROS3_MAX_SECRET_KEY_LEN
0102  * Maximum string length for specifying the security key.
0103  *
0104  * \since 1.10.6
0105  */
0106 #define H5FD_ROS3_MAX_SECRET_KEY_LEN 128
0107 /**
0108  * \def H5FD_ROS3_MAX_SECRET_TOK_LEN
0109  * Maximum string length for specifying the session/security token.
0110  */
0111 #define H5FD_ROS3_MAX_SECRET_TOK_LEN 4096
0112
0113 /**
0114  * \struct H5FD_ros3_fapl_t
0115  * \brief Configuration structure for H5Pset_fapl_ros3() / H5Pget_fapl_ros3().
0116  *
0117  * \details H5FD_ros_fapl_t is a public structure that is used to pass
0118  *          configuration data to the #H5FD_ROS3 driver via a File Access
0119  *          Property List. A pointer to an instance of this structure is
0120  *          a parameter to H5Pset_fapl_ros3() and H5Pget_fapl_ros3().
0121  *
0122  * \var int32_t H5FD_ros3_fapl_t::version
0123  *      Version number of the H5FD_ros3_fapl_t structure. Any instance passed
0124  *      to H5Pset_fapl_ros3() / H5Pget_fapl_ros3() must have a recognized version
0125  *      number or an error will be raised. Currently, this field should be set
0126  *      to #H5FD_CURR_ROS3_FAPL_T_VERSION.
0127  *
0128  * \var hbool_t H5FD_ros3_fapl_t::authenticate
0129  *      A Boolean which specifies if security credentials should be used for
0130  *      accessing a S3 bucket.
0131  *      If true, `aws_region`, `secret_id`, and `secret_key` must be populated.
0132  *      If false, those three components are unused.
0133  *
0134  * \var char H5FD_ros3_fapl_t::aws_region[H5FD_ROS3_MAX_REGION_LEN + 1]
0135  *      A string which specifies the AWS region of the S3 bucket, e.g. "us-east-1".
0136  *
0137  * \var char H5FD_ros3_fapl_t::secret_id[H5FD_ROS3_MAX_SECRET_ID_LEN + 1]
0138  *      A string which specifies the security ID.
0139  *
0140  * \var char H5FD_ros3_fapl_t::secret_key[H5FD_ROS3_MAX_SECRET_KEY_LEN + 1]
0141  *      A string which specifies the security key.
0142  */
0143 typedef struct H5FD_ros3_fapl_t {
0144     int32_t version;
0145     hbool_t authenticate;
0146     char    aws_region[H5FD_ROS3_MAX_REGION_LEN + 1];
0147     char    secret_id[H5FD_ROS3_MAX_SECRET_ID_LEN + 1];
0148     char    secret_key[H5FD_ROS3_MAX_SECRET_KEY_LEN + 1];
0149 } H5FD_ros3_fapl_t;
0150
0151 #ifdef __cplusplus
0152 extern "C" {
0153 #endif
0154
0155 /** @private
0156  *
0157  * \brief Private initializer for the ros3 VFD
0158  */
0159 H5_DLL hid_t H5FD_ros3_init(void);
0160
0161 /**
0162  * \ingroup FAPL
0163  *
0164  * \brief Queries a File Access Property List for #H5FD_ROS3 file driver properties.
0165  *
0166  * \fapl_id
0167  * \param[out] fa_out Pointer to #H5FD_ROS3 driver configuration structure.
0168  * \returns \herr_t
0169  */
0170 H5_DLL herr_t H5Pget_fapl_ros3(hid_t fapl_id, H5FD_ros3_fapl_t *fa_out);
0171
0172 /**
0173  * \ingroup FAPL
0174  *
0175  * \brief Modifies the specified File Access Property List to use the #H5FD_ROS3 driver.
0176  *
0177  * \fapl_id
0178  * \param[in] fa Pointer to #H5FD_ROS3 driver configuration structure.
0179  * \returns \herr_t
0180  */
0181 H5_DLL herr_t H5Pset_fapl_ros3(hid_t fapl_id, const H5FD_ros3_fapl_t *fa);
0182
0183 /**
0184  * \ingroup FAPL
0185  *
0186  * \brief Queries a File Access Property List for #H5FD_ROS3 file driver session/security
0187  *        token.
0188  *
0189  * \fapl_id
0190  * \param[in] size Size of the provided char array for storing the session/security token.
0191  * \param[out] token Session/security token.
0192  * \returns \herr_t
0193  *
0194  * \since 1.14.2
0195  */
0196 H5_DLL herr_t H5Pget_fapl_ros3_token(hid_t fapl_id, size_t size, char *token);
0197
0198 /**
0199  * \ingroup FAPL
0200  *
0201  * \brief Modifies the specified File Access Property List to use the #H5FD_ROS3 driver
0202  *        by adding the specified session/security token.
0203  *
0204  * \fapl_id
0205  * \param[in] token Session/security token.
0206  * \returns \herr_t
0207  *
0208  * \details H5Pset_fapl_ros3_token() modifies an existing File Access Property List which
0209  *          is used by #H5FD_ROS3 driver by adding or updating the session/security token
0210  *          of the property list. Be aware, to set the token first you need to create
0211  *          a proper File Access Property List using H5Pset_fapl_ros() and use this list
0212  *          as input argument of the function H5Pset_fapl_ros3_token().
0213  *
0214  *          Note, the session token is only needed when you want to access a S3 bucket
0215  *          using temporary security credentials.
0216  *
0217  * \since 1.14.2
0218  */
0219 H5_DLL herr_t H5Pset_fapl_ros3_token(hid_t fapl_id, const char *token);
0220
0221 #ifdef __cplusplus
0222 }
0223 #endif
0224
0225 #endif /* H5_HAVE_ROS3_VFD */
0226
0227 #endif /* ifndef H5FDros3_H */