1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* Copyright by The HDF Group. *
* All rights reserved. *
* *
* This file is part of HDF5. The full HDF5 copyright notice, including *
* terms governing use, modification, and redistribution, is contained in *
* the COPYING file, which can be found at the root of the source code *
* distribution tree, or in https://www.hdfgroup.org/licenses. *
* If you do not have access to either file, you may request a copy from *
* help@hdfgroup.org. *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*
* Read-Only S3 Virtual File Driver (VFD)
*
* Purpose: The public header file for the ros3 driver.
*/
#ifndef H5FDros3_H
#define H5FDros3_H
#ifdef H5_HAVE_ROS3_VFD
#define H5FD_ROS3 (H5FDperform_init(H5FD_ros3_init))
#define H5FD_ROS3_VALUE H5_VFD_ROS3
#else
#define H5FD_ROS3 (H5I_INVALID_HID)
#define H5FD_ROS3_VALUE H5_VFD_INVALID
#endif /* H5_HAVE_ROS3_VFD */
#ifdef H5_HAVE_ROS3_VFD
/****************************************************************************
*
* Structure: H5FD_ros3_fapl_t
*
* Purpose:
*
* H5FD_ros3_fapl_t is a public structure that is used to pass S3
* authentication data to the appropriate S3 VFD via the FAPL. A pointer
* to an instance of this structure is a parameter to H5Pset_fapl_ros3()
* and H5Pget_fapl_ros3().
*
*
*
* `version` (int32_t)
*
* Version number of the H5FD_ros3_fapl_t structure. Any instance passed
* to the above calls must have a recognized version number, or an error
* will be flagged.
*
* This field should be set to H5FD_CURR_ROS3_FAPL_T_VERSION.
*
* `authenticate` (hbool_t)
*
* Flag TRUE or FALSE whether or not requests are to be authenticated
* with the AWS4 algorithm.
* If TRUE, `aws_region`, `secret_id`, and `secret_key` must be populated.
* If FALSE, those three components are unused.
*
* `aws_region` (char[])
*
* String: name of the AWS "region" of the host, e.g. "us-east-1".
*
* `secret_id` (char[])
*
* String: "Access ID" for the resource.
*
* `secret_key` (char[])
*
* String: "Secret Access Key" associated with the ID and resource.
*
****************************************************************************/
/**
* \def H5FD_CURR_ROS3_FAPL_T_VERSION
* The version number of the H5FD_ros3_fapl_t configuration
* structure for the $H5FD_ROS3 driver.
*/
#define H5FD_CURR_ROS3_FAPL_T_VERSION 1
/**
* \def H5FD_ROS3_MAX_REGION_LEN
* Maximum string length for specifying the region of the S3 bucket.
*/
#define H5FD_ROS3_MAX_REGION_LEN 32
/**
* \def H5FD_ROS3_MAX_SECRET_ID_LEN
* Maximum string length for specifying the security ID.
*/
#define H5FD_ROS3_MAX_SECRET_ID_LEN 128
/**
* \def H5FD_ROS3_MAX_SECRET_KEY_LEN
* Maximum string length for specifying the security key.
*/
#define H5FD_ROS3_MAX_SECRET_KEY_LEN 128
/**
* \def H5FD_ROS3_MAX_SECRET_TOK_LEN
* Maximum string length for specifying the session/security token.
*/
#define H5FD_ROS3_MAX_SECRET_TOK_LEN 1024
/**
*\struct H5FD_ros3_fapl_t
* \brief Configuration structure for H5Pset_fapl_ros3() / H5Pget_fapl_ros3().
*
* \details H5FD_ros_fapl_t is a public structure that is used to pass
* configuration data to the #H5FD_ROS3 driver via a File Access
* Property List. A pointer to an instance of this structure is
* a parameter to H5Pset_fapl_ros3() and H5Pget_fapl_ros3().
*
* \var int32_t H5FD_ros3_fapl_t::version
* Version number of the H5FD_ros3_fapl_t structure. Any instance passed
* to H5Pset_fapl_ros3() / H5Pget_fapl_ros3() must have a recognized version
* number or an error will be raised. Currently, this field should be set
* to #H5FD_CURR_ROS3_FAPL_T_VERSION.
*
* \var hbool_t H5FD_ros3_fapl_t::authenticate
* A boolean which specifies if security credentials should be used for
* accessing a S3 bucket.
*
* \var char H5FD_ros3_fapl_t::aws_region[H5FD_ROS3_MAX_REGION_LEN + 1]
* A string which specifies the AWS region of the S3 bucket.
*
* \var char H5FD_ros3_fapl_t::secret_id[H5FD_ROS3_MAX_SECRET_ID_LEN + 1]
* A string which specifies the security ID.
*
* \var char H5FD_ros3_fapl_t::secret_key[H5FD_ROS3_MAX_SECRET_KEY_LEN + 1]
* A string which specifies the security key.
*
*/
typedef struct H5FD_ros3_fapl_t {
int32_t version;
hbool_t authenticate;
char aws_region[H5FD_ROS3_MAX_REGION_LEN + 1];
char secret_id[H5FD_ROS3_MAX_SECRET_ID_LEN + 1];
char secret_key[H5FD_ROS3_MAX_SECRET_KEY_LEN + 1];
} H5FD_ros3_fapl_t;
#ifdef __cplusplus
extern "C" {
#endif
/**
* \brief Internal routine to initialize #H5FD_ROS3 driver. Not meant to be
* called directly by an HDF5 application.
*/
H5_DLL hid_t H5FD_ros3_init(void);
/**
* \ingroup FAPL
*
* \brief Queries a File Access Property List for #H5FD_ROS3 file driver properties.
*
* \fapl_id
* \param[out] fa_out Pointer to #H5FD_ROS3 driver configuration structure.
* \returns \herr_t
*/
H5_DLL herr_t H5Pget_fapl_ros3(hid_t fapl_id, H5FD_ros3_fapl_t *fa_out);
/**
* \ingroup FAPL
*
* \brief Modifies the specified File Access Property List to use the #H5FD_ROS3 driver.
*
* \fapl_id
* \param[in] fa Pointer to #H5FD_ROS3 driver configuration structure.
* \returns \herr_t
*/
H5_DLL herr_t H5Pset_fapl_ros3(hid_t fapl_id, const H5FD_ros3_fapl_t *fa);
/**
* \ingroup FAPL
*
* \brief Queries a File Access Property List for #H5FD_ROS3 file driver session/security
* token.
*
* \fapl_id
* \param[in] size Size of the provided char array for storing the session/security token.
* \param[out] token Session/security token.
* \returns \herr_t
*
* \since 1.14.2
*/
H5_DLL herr_t H5Pget_fapl_ros3_token(hid_t fapl_id, size_t size, char *token);
/**
* \ingroup FAPL
*
* \brief Modifies the specified File Access Property List to use the #H5FD_ROS3 driver
* by adding the specified session/security token.
*
* \fapl_id
* \param[in] token Session/security token.
* \returns \herr_t
*
* \details H5Pset_fapl_ros3_token() modifies an existing File Access Property List which
* is used by #H5FD_ROS3 driver by adding or updating the session/security token
* of the property list. Be aware, to set the token first you need to create
* a proper File Access Property List using H5Pset_fapl_ros() and use this list
* as input argument of the function H5Pset_fapl_ros3_token().
*
* Note, the session token is only needed when you want to access a S3 bucket
* using temporary security credentials.
*
* \since 1.14.2
*/
H5_DLL herr_t H5Pset_fapl_ros3_token(hid_t fapl_id, const char *token);
#ifdef __cplusplus
}
#endif
#endif /* H5_HAVE_ROS3_VFD */
#endif /* ifndef H5FDros3_H */
|
