Grid Community Toolkit  6.2.1629922860 (tag: v6.2.20210826)
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
gsi_socket.h
1 /*
2  * gsi_socket.h
3  *
4  * Interface for a GSI-protected socket.
5  */
6 
7 #ifndef __GSI_SOCKET_H
8 #define __GSI_SOCKET_H
9 
10 #include <sys/types.h>
11 
12 struct _gsi_socket;
13 typedef struct _gsi_socket GSI_SOCKET;
14 
15 /*
16  * Return code for many of the GSI_SOCKET routines:
17  */
18 #define GSI_SOCKET_SUCCESS 0
19 #define GSI_SOCKET_ERROR -1
20 #define GSI_SOCKET_TRUNCATED -2
21 #define GSI_SOCKET_UNAUTHORIZED -3
22 #define GSI_SOCKET_UNTRUSTED -4
23 
24 /*
25  * GSI_SOCKET_new()
26  *
27  * Create a new GSI_SOCKET object for a socket descriptor.
28  *
29  * Returns NULL on memory allocation failure.
30  */
31 GSI_SOCKET *GSI_SOCKET_new(int sock);
32 
33 /*
34  * GSI_SOCKET_destroy()
35  *
36  * Destroy the GSI_SOCKET object and deallocated all associated
37  * memory.
38  */
39 void GSI_SOCKET_destroy(GSI_SOCKET *gsi_socket);
40 
41 /*
42  * GSI_SOCKET_get_error_string()
43  *
44  * Fills in buffer with a NUL-terminated string (possibly multi-lined)
45  * describing the last error the occurred with this GSI_SOCKET.
46  * bufferlen should be the size of buffer. It returns the number of
47  * characters actually put into buffer (not including the trailing
48  * NUL).
49  *
50  * If there is no error known of, buffer will be set to a zero-length
51  * string, and zero will be returned.
52  *
53  * If the buffer wasn't big enough and the string was truncated,
54  * -1 will be returned.
55  */
56 int GSI_SOCKET_get_error_string(GSI_SOCKET *gsi_socket,
57  char *buffer,
58  int buffer_len);
59 
60 /*
61  * GSI_SOCKET_clear_error()
62  *
63  * Clears any error state in the given GSI_SOCKET object.
64  */
65 void GSI_SOCKET_clear_error(GSI_SOCKET *gsi_socket);
66 
67 /*
68  * GSI_SOCKET_authentication_init()
69  *
70  * Perform the client-side authentication process.
71  * The accepted_peer_names argument must be a NULL terminated array of
72  * acceptable peer names.
73  *
74  * Returns GSI_SOCKET_SUCCESS on success,
75  * GSI_SOCKET_UNAUTHORIZED if server identity doesn't match one of the
76  * acceptable peer names, and GSI_SOCKET_ERROR otherwise.
77  */
78 int GSI_SOCKET_authentication_init(GSI_SOCKET *gsi_socket,
79  gss_name_t accepted_peer_names[]);
80 
81 /*
82  * GSI_SOCKET_use_creds()
83  *
84  * Use the credentials pointed to by creds for authentication.
85  * The exact contents of creds is mechanism-specific, but is
86  * generally a filename. If creds == NULL, the defaults credentials
87  * should be used.
88  *
89  * Returns GSI_SOCKET_SUCCESS on success, GSI_SOCKET_ERROR otherwise.
90  */
91 int GSI_SOCKET_use_creds(GSI_SOCKET *gsi_socket,
92  const char *creds);
93 
94 /*
95  * GSI_SOCKET_check_creds()
96  *
97  * Check that valid GSI credentials are available.
98  *
99  * Returns GSI_SOCKET_SUCCESS on success, GSI_SOCKET_ERROR otherwise.
100  */
101 int GSI_SOCKET_check_creds(GSI_SOCKET *gsi_socket);
102 
103 /*
104  * GSI_SOCKET_authentication_accept()
105  *
106  * Perform the server-side authentication process.
107  *
108  * Returns GSI_SOCKET_SUCCESS on success, GSI_SOCKET_ERROR otherwise.
109  */
110 int GSI_SOCKET_authentication_accept(GSI_SOCKET *gsi_socket);
111 
112 /*
113  * GSI_SOCKET_get_peer_name()
114  *
115  * Fill in buffer with a string representation of the authenticated
116  * identity of the entity on the other side of the socket.
117  *
118  * If the peer is not identified, returns GSI_SOCKET_ERROR.
119  *
120  * If the buffer is too small and the string is truncated returns
121  * GSI_SOCKET_TRUNCATED.
122  *
123  * Other wise returns the number of characters written into the buffer
124  * (not including the trailing NUL).
125  *
126  */
127 int GSI_SOCKET_get_peer_name(GSI_SOCKET *gsi_socket,
128  char *buffer,
129  int buffer_len);
130 
131 /*
132  * GSI_SOCKET_get_peer_hostname()
133  *
134  * Returns the hostname of the entity on the other side of the socket
135  * or NULL on error. Returned string should be free()'ed by the caller.
136  *
137  */
138 char *GSI_SOCKET_get_peer_hostname(GSI_SOCKET *gsi_socket);
139 
140 /*
141  * GSI_SOCKET_get_peer_fqans()
142  *
143  * Returns a NULL terminated list of the client's FQAN's (full quolified
144  * attribute names).
145  *
146  */
147 
148 int GSI_SOCKET_get_peer_fqans(GSI_SOCKET *gsi_socket, char ***fqans);
149 
150 /*
151  * GSI_SOCKET_write_buffer()
152  *
153  * Write the given buffer to the peer. If authentication has been done,
154  * the buffer will be protected via the GSI.
155  *
156  * Returns GSI_SOCKET_SUCCESS on success, GSI_SOCKET_ERROR otherwise.
157  */
158 int GSI_SOCKET_write_buffer(GSI_SOCKET *gsi_socket,
159  const char *buffer,
160  size_t buffer_len);
161 
162 /*
163  * GSI_SOCKET_read_token()
164  *
165  * Read a token from the peer. If authentication has been done,
166  * the buffer will be protected via the GSI.
167  *
168  * buffer will be set to point to an allocated buffer that should
169  * be freed with GSI_SOCKET_free_token(). buffer_len will be
170  * set to the length of the buffer.
171  *
172  * Returns GSI_SOCKET_SUCCESS or GSI_SOCKET_ERROR.
173  */
174 int GSI_SOCKET_read_token(GSI_SOCKET *gsi_socket,
175  unsigned char **buffer,
176  size_t *buffer_len);
177 
178 /*
179  * GSI_SOCKET_free_token()
180  *
181  * Free a token returned by GSI_SOCKET_read_token().
182  */
183 void GSI_SOCKET_free_token(unsigned char *buffer);
184 
185 /*
186  * GSI_SOCKET_delegation_init_ext()
187  *
188  * Delegate credentials to the peer.
189  *
190  * source_credentials should be a string specifying the location
191  * of the credentials to delegate. This is mechanism specific,
192  * but typically a file path. If NULL, the default credentials for
193  * the current context will be used.
194  *
195  * lifetime should be the lifetime of the delegated credentials
196  * in seconds. A value of GSI_SOCKET_DELEGATION_LIFETIME_MAXIMUM
197  * indicates that the longest possible lifetime should be delegated.
198  *
199  * passphrase is the passphrase set for the source_credentials.
200  * NULL if no passphrase is set.
201  *
202  * Returns GSI_SOCKET_SUCCESS success, GSI_SOCKET_ERROR otherwise.
203  */
204 int GSI_SOCKET_delegation_init_ext(GSI_SOCKET *gsi_socket,
205  const char *source_credentials,
206  int lifetime,
207  const char *passphrase);
208 /*
209  * Values for GSI_SOCKET_DELEGATION_init() flags:
210  */
211 #define GSI_SOCKET_DELEGATION_FLAGS_DEFAULT 0x0000
212 
213 /*
214  * Values for GSI_SOCKET_DELEGATION_init() lifetime:
215  */
216 #define GSI_SOCKET_DELEGATION_LIFETIME_MAXIMUM 0x0000
217 
218 /*
219  * Valyes for GSI_SOCKET_DELEGATION_init() restrictions:
220  */
221 #define GSI_SOCKET_DELEGATION_RESTRICTIONS_DEFAULT NULL
222 
223 /*
224  * GSI_SOCKET_delegation_accept()
225  *
226  * Accept delegated credentials from the peer.
227  *
228  * Return an allocated buffer with the given proxy encoded in PEM format.
229  * The private key is encrypted with passphrase if provided (can be NULL).
230  *
231  * Returns GSI_SOCKET_SUCCESS on success, GSI_SOCKET_ERROR otherwise. */
232 int GSI_SOCKET_delegation_accept(GSI_SOCKET *gsi_socket,
233  unsigned char **delegated_credentials,
234  int *delegated_credentials_len,
235  char *passphrase);
236 
237 /*
238  * GSI_SOCKET_delegation_accept_ext()
239  *
240  * Accept delegated credentials from the peer.
241  *
242  * delegated_credentials will be filled in with the location of
243  * the delegated credentials. This is mechanism-specific but
244  * probably a file path.
245  *
246  * passphrase is an optional passphrase to use to encrypt the
247  * delegated credentials. May be NULL.
248  *
249  * Returns GSI_SOCKET_SUCCESS on success, GSI_SOCKET_ERROR otherwise. */
250 int GSI_SOCKET_delegation_accept_ext(GSI_SOCKET *gsi_socket,
251  char *delegated_credentials,
252  int delegated_credentials_len,
253  char *passphrase);
254 
255 /*
256  * GSI_SOCKET_delegation_set_certreq()
257  *
258  * Specify the location of a PEM-encoded certificate request to be
259  * used when accepting delegation via GSI_SOCKET_delegation_accept()
260  * or GSI_SOCKET_delegation_accept_ext(), rather than generating a new
261  * keypair and certificate request as part of delegation.
262  *
263  * Returns GSI_SOCKET_SUCCESS or GSI_SOCKET_ERROR.
264  */
265 int
266 GSI_SOCKET_delegation_set_certreq(GSI_SOCKET *gsi_socket,
267  char *certreq);
268 
269 /*
270  * GSI_SOCKET_credentials_accept_ext()
271  *
272  * Accept credentials from the peer.
273  *
274  * delegated_credentials will be filled in with the location of
275  * the delegated credentials. This is mechanism-specific but
276  * probably a file path.
277  *
278  * Returns GSI_SOCKET_SUCCESS on success, GSI_SOCKET_ERROR otherwise. */
279 int
280 GSI_SOCKET_credentials_accept_ext(GSI_SOCKET *self,
281  char *credentials,
282  int credentials_len);
283 
284 int
285 GSI_SOCKET_get_creds(GSI_SOCKET *self,
286  const char *source_credentials);
287 
288 int
289 GSI_SOCKET_credentials_init_ext(GSI_SOCKET *self,
290  const char *source_credentials);
291 
292 /*
293  * GSI_SOCKET_allow_anonymous()
294  *
295  * If value=1, allow anonymous GSSAPI/SSL authentication.
296  * Otherwise, the client must have a valid GSSAPI/SSL credential.
297  * Default is to *not* allow anonymous authentication.
298  *
299  */
300 int GSI_SOCKET_allow_anonymous(GSI_SOCKET *self, const int value);
301 
302 /*
303  * GSI_SOCKET_peer_used_limited_proxy()
304  *
305  * Returns 1 if peer used a limited proxy, 0 otherwise.
306  *
307  */
308 int GSI_SOCKET_peer_used_limited_proxy(GSI_SOCKET *self);
309 
310 /*
311  * GSI_SOCKET_set_peer_limited_proxy()
312  *
313  * Set the peer's limited proxy flag (1 if yes, 0 if no).
314  * Used when secondary authentication used a limited proxy
315  * and so limited proxy policies should apply.
316  *
317  */
318 int GSI_SOCKET_set_peer_limited_proxy(GSI_SOCKET *self, int flag);
319 
320 /*
321  * GSI_SOCKET_set_max_token_len()
322  *
323  * Set the maximum size of accepted incoming tokens (in bytes).
324  * No limit is enforced by default.
325  * A zero or negative value disables the limit.
326  */
327 int GSI_SOCKET_set_max_token_len(GSI_SOCKET *self, int bytes);
328 
329 /*
330  * GSI_SOCKET_context_established()
331  *
332  * Returns 1 if the socket's secure context has been established via
333  * GSI_SOCKET_authentication_init() or
334  * GSI_SOCKET_authentication_accept(). Returns 0 otherwise.
335  *
336  */
337 int GSI_SOCKET_context_established(GSI_SOCKET *self);
338 
339 /*
340  * GSI_SOCKET_get_errno()
341  *
342  * Returns saved errno if the socket exists. Otherwise returns 0.
343  *
344  */
345 int GSI_SOCKET_get_errno(GSI_SOCKET *self);
346 
347 #endif /* !__GSI_SOCKET_H */