Grid Community Toolkit  6.2.1629922860 (tag: v6.2.20210826)
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
myproxy_protocol.h
1 /*
2  *
3  * MyProxy protocol API
4  *
5  */
6 #ifndef __MYPROXY_PROTOCOL_H
7 #define __MYPROXY_PROTOCOL_H
8 
9 /* Protocol commands */
10 typedef enum
11 {
12  MYPROXY_GET_PROXY,
13  MYPROXY_PUT_PROXY,
14  MYPROXY_INFO_PROXY,
15  MYPROXY_DESTROY_PROXY,
16  MYPROXY_CHANGE_CRED_PASSPHRASE,
17  MYPROXY_STORE_CERT,
18  MYPROXY_RETRIEVE_CERT,
19  MYPROXY_GET_TRUSTROOTS
20 } myproxy_proto_request_type_t;
21 
22 /* server response codes */
23 typedef enum
24 {
25  MYPROXY_OK_RESPONSE,
26  MYPROXY_ERROR_RESPONSE,
27  MYPROXY_AUTHORIZATION_RESPONSE
28 } myproxy_proto_response_type_t;
29 
30 /* client/server socket attributes */
31 typedef struct myproxy_socket_attrs_s
32 {
33  char *pshost;
34  int psport;
35  int socket_fd;
36  struct _gsi_socket *gsi_socket;
37 } myproxy_socket_attrs_t;
38 
39 /* A client request object */
40 #define REGULAR_EXP 1
41 #define MATCH_CN_ONLY 0
42 
43 typedef struct
44 {
45  char *version;
46  char *username;
47  char passphrase[MAX_PASS_LEN+1];
48  char new_passphrase[MAX_PASS_LEN+1];
49  myproxy_proto_request_type_t command_type;
50  int proxy_lifetime;
51  char *retrievers;
52  char *renewers;
53  char *credname;
54  char *creddesc;
55  char *authzcreds;
56  char *keyretrieve;
57  char *trusted_retrievers;
58  int want_trusted_certs; /* 1=yes, 0=no */
59  char *voname;
60  char *vomses;
61  char *certreq;
62 } myproxy_request_t;
63 
64 /* A server response object */
65 typedef struct
66 {
67  char *version;
68  myproxy_proto_response_type_t response_type;
69  authorization_data_t **authorization_data;
70  char *error_string;
71  myproxy_creds_t *info_creds;
72  myproxy_certs_t *trusted_certs;
73 } myproxy_response_t;
74 
75 
76 /*
77  * myproxy_init_client()
78  *
79  * Create a generic client by creating a GSI socket and connecting to a a host
80  *
81  * returns the file descriptor of the connected socket or
82  * -1 if an error occurred
83  */
84 int myproxy_init_client(myproxy_socket_attrs_t *attrs);
85 
86 /*
87  * myproxy_authenticate_init()
88  *
89  * Perform client-side authentication
90  *
91  * returns -1 if unable to authenticate, 0 if authentication successful
92  */
93 int myproxy_authenticate_init(myproxy_socket_attrs_t *attr,
94  const char *proxyfile);
95 
96 /*
97  * myproxy_authenticate_accept()
98  *
99  * Perform server-side authentication and retrieve the client's DN
100  *
101  * returns -1 if unable to authenticate, 0 if authentication successful
102  */
103 int myproxy_authenticate_accept(myproxy_socket_attrs_t *attr,
104  char *client_name, const int namelen);
105 
106 /*
107  * myproxy_authenticate_accept_fqans()
108  *
109  * The same as myproxy_authenticate_accept() but also returns a list of FQANs
110  * if suggested by the peer.
111  *
112  */
113 int myproxy_authenticate_accept_fqans(myproxy_socket_attrs_t *attr,
114  char *client_name, const int namelen,
115  char ***fqans);
116 
117 /*
118  * myproxy_serialize_request()
119  *
120  * Serialize a request object into a buffer to be sent over the network.
121  * Use myproxy_serialize_request_ex() instead.
122  *
123  * Returns the serialized data length or -1 on error.
124  */
125 int myproxy_serialize_request(const myproxy_request_t *request,
126  char *data, const int datalen);
127 
128 /*
129  * myproxy_serialize_request_ex()
130  *
131  * Serialize a request object into a newly allocated buffer of correct size.
132  * The caller should free() the buffer after use.
133  *
134  * Returns the serialized data length or -1 on error.
135  */
136 int myproxy_serialize_request_ex(const myproxy_request_t *request,
137  char **data);
138 
139 
140 /*
141  * myproxy_deserialize_request()
142  *
143  * Deserialize a buffer into a request object.
144  *
145  * returns 0 if succesful, otherwise -1
146  */
147 int myproxy_deserialize_request(const char *data, const int datalen,
148  myproxy_request_t *request);
149 
150 /*
151  * myproxy_serialize_response()
152  *
153  * Serialize a response object into a buffer to be sent over the network.
154  * Use myproxy_serialize_response_ex() instead.
155  *
156  * returns the number of characters put into the buffer
157  * (not including the trailing NULL)
158  */
159 int
160 myproxy_serialize_response(const myproxy_response_t *response,
161  char *data, const int datalen);
162 
163 /*
164  * myproxy_serialize_response_ex()
165  *
166  * Serialize a response object into a newly allocated buffer of correct size.
167  * The caller should free() the buffer after use.
168  *
169  * returns the number of characters put into the buffer
170  * (not including the trailing NULL)
171  */
172 int
173 myproxy_serialize_response_ex(const myproxy_response_t *response,
174  char **data);
175 
176 /*
177  * myproxy_deserialize_response()
178  *
179  * Serialize a a buffer into a response object.
180  *
181  * returns the number of characters put into the buffer
182  * (not including the trailing NULL)
183  */
184 int myproxy_deserialize_response(myproxy_response_t *response,
185  const char *data, const int datalen);
186 
187 /*
188  * myproxy_send()
189  *
190  * Sends a buffer
191  *
192  * returns 0 on success, -1 on error
193  */
194 int myproxy_send(myproxy_socket_attrs_t *attrs,
195  const char *data, const int datalen);
196 
197 /*
198  * myproxy_recv()
199  *
200  * Receives a message into the buffer.
201  * Use myproxy_recv_ex() instead.
202  *
203  * returns bytes read on success, -1 on error, -2 on truncated response
204  *
205  */
206 int myproxy_recv(myproxy_socket_attrs_t *attrs,
207  char *data, const int datalen);
208 
209 /*
210  * myproxy_recv_ex()
211  *
212  * Receives a message into a newly allocated buffer of correct size.
213  * The caller must deallocate the buffer.
214  *
215  * returns bytes read on success, -1 on error
216  *
217  */
218 int myproxy_recv_ex(myproxy_socket_attrs_t *attrs, char **data);
219 
220 /*
221  * myproxy_init_delegation()
222  *
223  * Delegates a proxy based on the credentials found in file
224  * location delegfile good for lifetime_seconds
225  *
226  * returns 0 on success, -1 on error
227  */
228 int myproxy_init_delegation(myproxy_socket_attrs_t *attrs,
229  const char *delegfile,
230  const int lifetime_seconds,
231  char *passphrase);
232 
233 /*
234  * myproxy_accept_delegation()
235  *
236  * Accepts delegated credentials into a file, and sets
237  * path in provided buffer.
238  *
239  * returns 0 on success, -1 on error
240  */
241 int myproxy_accept_delegation(myproxy_socket_attrs_t *attrs, char *delegfile,
242  const int delegfile_len, char *passphrase);
243 
244 /*
245  * myproxy_accept_delegation_ex()
246  *
247  * Accepts delegated credentials into a newly allocated buffer.
248  * The caller must deallocate the buffer.
249  * Private key is encrypted with passphrase, if provided (may be NULL).
250  *
251  * returns 0 on success, -1 on error
252  */
253 int myproxy_accept_delegation_ex(myproxy_socket_attrs_t *attrs,
254  char **credentials,
255  int *credential_len, char *passphrase);
256 
257 /*
258  * myproxy_request_cert()
259  *
260  * An alternative to myproxy_accept_delegation_ex() that takes the
261  * location of a file containing a PEM-formatted certificate request
262  * (certreq) as input.
263  * Accepts delegated credentials into a newly allocated buffer.
264  * The caller must deallocate the buffer.
265  *
266  * return 0 on success, -1 on error
267  */
268 int
269 myproxy_request_cert(myproxy_socket_attrs_t *attrs, char *certreq,
270  char **credentials, int *credential_len);
271 
272 /*
273  * myproxy_accept_credentials()
274  *
275  * Accepts credentials into file location data
276  *
277  * returns 0 on success, -1 on error
278  */
279 int
280 myproxy_accept_credentials(myproxy_socket_attrs_t *attrs,
281  char *delegfile,
282  int delegfile_len);
283 
284 /*
285  * myproxy_init_credentials()
286  *
287  * returns 0 on success, -1 on error
288  */
289 int
290 myproxy_init_credentials(myproxy_socket_attrs_t *attrs,
291  const char *delegfile);
292 
293 int
294 myproxy_get_credentials(myproxy_socket_attrs_t *attrs,
295  const char *delegfile);
296 
297 /*
298  * myproxy_free()
299  *
300  * Frees up memory used for creating request, response and socket objects
301  */
302 void myproxy_free(myproxy_socket_attrs_t *attrs, myproxy_request_t *request,
303  myproxy_response_t *response);
304 
305 /*
306  * myproxy_recv_response()
307  *
308  * Helper function that combines myproxy_recv() and
309  * myproxy_deserialize_response() with some error checking.
310  *
311  */
312 int myproxy_recv_response(myproxy_socket_attrs_t *attrs,
313  myproxy_response_t *response);
314 
315 /*
316  * myproxy_handle_response()
317  *
318  * Helper function that combines
319  * myproxy_deserialize_response() with some error checking.
320  *
321  */
322 int myproxy_handle_response(const char *response_buffer,
323  int responselen,
324  myproxy_response_t *response);
325 
326 /*
327  * myproxy_recv_response_ex()
328  *
329  * Helper function that combines myproxy_recv(),
330  * myproxy_deserialize_response(), and myproxy_handle_authorization()
331  * with some error checking.
332  *
333  */
334 int myproxy_recv_response_ex(myproxy_socket_attrs_t *attrs,
335  myproxy_response_t *response,
336  myproxy_request_t *client_request);
337 
338 /*
339  * myproxy_handle_authorization()
340  *
341  * If MYPROXY_AUTHORIZATION_RESPONSE is received, pass it to this
342  * function to be processed.
343  *
344  */
345 int myproxy_handle_authorization(myproxy_socket_attrs_t *attrs,
346  myproxy_response_t *server_response,
347  myproxy_request_t *client_request);
348 
349 /*
350  * myproxy_bootstrap_trust()
351  *
352  * Get server's CA certificate(s) via the SSL handshake and install
353  * them in the trusted certificates directory.
354  *
355  */
356 int myproxy_bootstrap_trust(myproxy_socket_attrs_t *attrs);
357 
358 /*
359  * myproxy_bootstrap_client()
360  *
361  * Connect to server and authenticate.
362  * Bootstrap trust roots as needed/requested.
363  * Allows anonymous authentication.
364  * Called by myproxy-logon and myproxy-get-trustroots.
365  *
366  */
367 int myproxy_bootstrap_client(myproxy_socket_attrs_t *attrs,
368  int bootstrap_if_no_cert_dir,
369  int bootstrap_even_if_cert_dir_exists);
370 
371 /*
372  * myproxy_request_add_voname()
373  *
374  * Adds VONAME parameter to client request.
375  * returns 0 if succesful, otherwise -1
376  *
377  */
378 int myproxy_request_add_voname(myproxy_request_t *client_request,
379  const char *voname);
380 
381 /*
382  * myproxy_request_add_vomses()
383  *
384  * Adds VOMSES parameter to client request.
385  * returns 0 if succesful, otherwise -1
386  *
387  */
388 int myproxy_request_add_vomses(myproxy_request_t *client_request,
389  const char *vomses);
390 
391 #endif /* __MYPROXY_PROTOCOL_H */