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