Grid Community Toolkit  6.2.1629922860 (tag: v6.2.20210826)
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
ssl_utils.h
1 /*
2  * ssl_utils.h
3  *
4  * Functions for interacting with SSL, X509, etc.
5  */
6 #ifndef _SSL_UTILS_H
7 #define _SSL_UTILS_H
8 
9 #include <openssl/ssl.h>
10 #include <openssl/x509.h>
11 #include <openssl/x509v3.h>
12 #include <openssl/md5.h>
13 #include <openssl/err.h>
14 #include <openssl/pem.h>
15 #include <openssl/rand.h>
16 #include <openssl/des.h>
17 #include <time.h>
18 
19 #include <globus_gsi_callback.h>
20 #include <globus_gsi_cert_utils.h>
21 #include <globus_gsi_credential.h>
22 #include <globus_gsi_proxy.h>
25 
26 /* EVP_MD_CTX_init() and EVP_MD_CTX_cleanup() not in OpenSSL 0.9.6. */
27 #if !defined(EVP_MD_CTX_FLAG_CLEANED)
28 #define EVP_MD_CTX_init(ctx)
29 #define EVP_MD_CTX_cleanup(ctx)
30 #define X509V3_set_nconf X509V3_set_conf_lhash
31 #define X509V3_EXT_add_nconf X509V3_EXT_add_conf
32 #endif
33 
34 struct _ssl_credentials;
35 typedef struct _ssl_credentials SSL_CREDENTIALS;
36 
37 struct _ssl_proxy_restrictions;
38 typedef struct _ssl_proxy_restrictions SSL_PROXY_RESTRICTIONS;
39 
40 /*
41  * Returns values for functions
42  */
43 #define SSL_SUCCESS 1
44 #define SSL_ERROR 0
45 
46 /*
47  * ssl_credentials_destroy()
48  *
49  * Destroys the given credentials, deallocating all memory
50  * associated with them.
51  */
52 void ssl_credentials_destroy(SSL_CREDENTIALS *creds);
53 
54 /*
55  * ssl_proxy_file_destroy()
56  *
57  * Fill the proxy file with zeros and unlink.
58  *
59  * Returns SSL_SUCCESS or SSL_ERROR, setting verror.
60  */
61 int ssl_proxy_file_destroy(const char *path);
62 
63 /*
64  * ssl_certificate_load_from_file()
65  *
66  * Load certificate(s) from the given file into the given set of credentials.
67  * Any existing certificates in the creds structure will be erased.
68  *
69  * Returns SSL_SUCCESS or SSL_ERROR, setting verror.
70  */
71 int ssl_certificate_load_from_file(SSL_CREDENTIALS *creds,
72  const char *path);
73 
74 /*
75  * ssl_certificate_push()
76  *
77  * Set given certificate as the creds' certificate, pushing any existing
78  * certificate in the creds structure into the constituent certificate chain.
79  *
80  * Returns SSL_SUCCESS or SSL_ERROR, setting verror.
81  */
82 int ssl_certificate_push(SSL_CREDENTIALS *creds,
83  X509 *cert);
84 
85 /*
86  * ssl_private_key_load_from_file()
87  *
88  * Load a key from the given file and store it in the given credentials
89  * structure.
90  * If pass_phrase_prompt is non-NULL, prompt for the
91  * passphrase to be entered on the tty if needed.
92  * Otherwise, if pass_phrase is non-NULL, use that passphrase
93  * to decrypt the key.
94  * Otherwise, assume the key is unencrypted.
95  * Any existing key in the creds structure will be erased.
96  *
97  * Returns SSL_SUCCESS or SSL_ERROR, setting verror.
98  */
99 int ssl_private_key_load_from_file(SSL_CREDENTIALS *creds,
100  const char *path,
101  const char *pass_phrase,
102  const char *pass_phrase_prompt);
103 
104 /*
105  * ssl_private_key_store_to_file()
106  *
107  * Returns SSL_SUCCESS or SSL_ERROR, setting verror.
108  */
109 int ssl_private_key_store_to_file(SSL_CREDENTIALS *creds,
110  const char *path,
111  const char *pass_phrase);
112 
113 
114 /*
115  * ssl_private_key_is_encrypted()
116  *
117  * Returns 1 if the private key is encrypted, 0 if unencrypted, -1 on error.
118  */
119 int ssl_private_key_is_encrypted(const char *path);
120 
121 /*
122  * ssl_proxy_from_pem()
123  *
124  * Take a buffer generated by ssl_proxy_to_pem() and return a set
125  * of credentials. pass_phrase is used if needed.
126  *
127  * Returns SSL_SUCCESS or SSL_ERROR, setting verror.
128  */
129 int ssl_proxy_from_pem(SSL_CREDENTIALS *creds,
130  const unsigned char *buffer,
131  int buffer_len,
132  const char *pass_phrase);
133 
134 /*
135  * ssl_proxy_load_from_file()
136  *
137  * Load a proxy certificate and key from the given file, using pass_phrase
138  * if needed, and storing the credentials in the given SSL_CREDENTIALS
139  * structure. pass_phrase may be NULL. Any existing credentials in
140  * the SSL_CREDENTIALS structure will be erased.
141  *
142  * Returns SSL_SUCCESS or SSL_ERROR, setting verror.
143  */
144 int ssl_proxy_load_from_file(SSL_CREDENTIALS *creds,
145  const char *path,
146  const char *pass_phrase);
147 
148 /*
149  * ssl_proxy_to_pem()
150  *
151  * Return an allocated buffer with the given proxy encoded in PEM format.
152  * The private key is encrypted with pass_phrase if provided (can be NULL).
153  *
154  * Returns SSL_SUCCESS or SSL_ERROR, setting verror.
155  */
156 int ssl_proxy_to_pem(SSL_CREDENTIALS *creds,
157  unsigned char **pbuffer,
158  int *pbuffer_len,
159  const char *pass_phrase);
160 
161 /*
162  *
163  * ssl_proxy_store_to_file()
164  *
165  * Store the the proxy in the given set of credentials to the give file.
166  * The file must not exist. If pass_phrase is non-NULL it will be used
167  * to encrypt the private key.
168  *
169  * Returns SSL_SUCCESS or SSL_ERROR, setting verror.
170  */
171 int ssl_proxy_store_to_file(SSL_CREDENTIALS *creds,
172  const char *path,
173  const char *pass_phrase);
174 
175 /*
176  * ssl_new_credentials()
177  *
178  * Return a empty credentials structure for use.
179  *
180  * Returns NULL on error.
181  */
182 SSL_CREDENTIALS *ssl_credentials_new();
183 
184 /*
185  *
186  * ssl_certreq_pem_to_der()
187  *
188  * Given the location of a file containing a PEM certificate request
189  * as input (certreq), return a DER encoded certificate request as
190  * output (buffer).
191  *
192  * Returns SSL_SUCCESS or SSL_ERROR, setting verror.
193  */
194 int ssl_certreq_pem_to_der(char *certreq,
195  unsigned char **buffer, int *buffer_length);
196 
197 /*
198  *
199  * ssl_proxy_delegation_init()
200  *
201  * Generate a request for a proxy delegation in a buffer suitable for shipping
202  * over the network.
203  *
204  * pcreds will be filled in with the private key and should be passed to
205  * ssl_proxy_delegation_finalize() to be filled in with the returned
206  * certificate.
207  *
208  * buffer will be set to point at an allocated buffer containing
209  * data to be passed to the signer to be passed into
210  * ssl_sign_proxy_request().
211  *
212  * buffer_length will be filled in with the length of buffer.
213  *
214  * requested_bits will be used as the key length for the
215  * new proxy. If 0 then the length of user_certificate key
216  * will be used.
217  *
218  * callback can point to a function that will be called
219  * during key generation - see SSLeay's doc/rsa.doc
220  * RSA_generate_key() function for details.
221  *
222  * Returns SSL_SUCCESS or SSL_ERROR, setting verror.
223  */
224 int ssl_proxy_delegation_init(SSL_CREDENTIALS **new_creds,
225  unsigned char **buffer,
226  int *buffer_length,
227  int requested_bits,
228  void (*callback)(int,int,void *));
229 
230 
231 /*
232  * ssl_proxy_delegation_finalize()
233  *
234  * Finalize the process of getting a proxy delegation using
235  * buffers in a form suitable for shipping over the network.
236  *
237  * creds should be the credentials originally obtained from
238  * ssl_proxy_request_init()
239  *
240  * buffer should be the buffer generated by ssl_proxy_request_sign().
241  *
242  * buffer_len should be the length of buffer.
243  *
244  * Returns SSL_SUCCESS or SSL_ERROR, setting verror.
245  */
246 int ssl_proxy_delegation_finalize(SSL_CREDENTIALS *creds,
247  unsigned char *buffer,
248  int buffer_length);
249 
250 /*
251  * ssl_proxy_delegation_sign()
252  *
253  * Sign a proxy delegation request and generate a proxy certificate. Input and
254  * output are buffers suitable for shipping over the network.
255  *
256  * creds contains the credentials used the sign the request.
257  *
258  * restrictions contains any restrictions to be placed on the
259  * proxy. May be NULL in which case defaults are used.
260  *
261  * request_buffer contains the buffer as generated by
262  * ssl_generate_proxy_request().
263  *
264  * request_buffer_len contains the length of request_buffer
265  * in bytes.
266  *
267  * proxy_buffer will be filled in with a pointer to an allocated
268  * buffer that contains the proxy certificate and certificate
269  * chain for feeding into ssl_finish_proxy_request.
270  *
271  * proxy_buffer_length will be filled in to contain the length
272  * of proxy_buffer.
273  *
274  * Returns SSL_SUCCESS or SSL_ERROR, setting verror.
275  */
276 int ssl_proxy_delegation_sign(SSL_CREDENTIALS *creds,
277  SSL_PROXY_RESTRICTIONS *restrictions,
278  unsigned char *request_buffer,
279  int request_buffer_length,
280  unsigned char **proxy_buffer,
281  int *proxy_buffer_length);
282 
283 /*
284  * ssl_free_buffer()
285  *
286  * Free a buffer allocated by any of the other routines in this library.
287  */
288 void ssl_free_buffer(unsigned char *buffer);
289 
290 
291 /*
292  * ssl_proxy_restrictions_new()
293  *
294  * Generate a new SSL_PROXY_RESTRICTIONS object.
295  *
296  * Returns object on success, NULL on error setting verror.
297  */
298 SSL_PROXY_RESTRICTIONS *ssl_proxy_restrictions_new();
299 
300 /*
301  * ssl_proxy_restrictions_destroy()
302  *
303  * Destroy a SSL_PROXY_RESTRICTIONS object, deallocating all memory
304  * associated with it.
305  */
306 void ssl_proxy_restrictions_destroy(SSL_PROXY_RESTRICTIONS *restrictions);
307 
308 /*
309  * ssl_proxy_restrictions_set_lifetime()
310  *
311  * Set the lifetime in the given SSL_PROXY_RESTRICTIONS object to
312  * the given number of seconds. A values of zero for seconds means
313  * to use the default.
314  *
315  * Returns SSL_SUCCESS on success, SSL_ERROR otherwise setting verror.
316  */
317 int ssl_proxy_restrictions_set_lifetime(SSL_PROXY_RESTRICTIONS *restrictions,
318  const long seconds);
319 
320 
321 /*
322  * ssl_proxy_restrictions_set_limited()
323  *
324  * Set whether a limited proxy should be delegated.
325  * A limited flag of 1 indicates yes, a flag of 0 indicates no (default).
326  *
327  * Returns SSL_SUCCESS on success, SSL_ERROR otherwise setting verror.
328  */
329 int ssl_proxy_restrictions_set_limited(SSL_PROXY_RESTRICTIONS *restrictions,
330  const int limited);
331 
332 
333 /* ssl_get_base_subject_file()
334  *
335  * Get user's subject name from certificate in the supplied filename
336  *
337  * Returns 0 on success or -1 on error
338  */
339 int
340 ssl_get_base_subject_file(const char *proxyfile, char **subject);
341 
342 /* ssl_get_base_subject()
343  *
344  * Get user's subject name from SSL_CREDENTIALS.
345  *
346  * Returns SSL_SUCCESS or SSL_ERROR
347  */
348 int
349 ssl_get_base_subject(SSL_CREDENTIALS *creds, char **subject);
350 
351 /*
352  * ssl_creds_to_buffer()
353  *
354  * Encode credentials from SSL_CREDENTIALS struct into buffer. Memory for the
355  * buffer is obtained with malloc(3) and must be freed with free(3).
356  *
357  * Returns SSL_SUCCESS or SSL_ERROR
358  */
359 int ssl_creds_to_buffer(SSL_CREDENTIALS *chain, unsigned char **buffer,
360  int *buffer_length);
361 
362 /*
363  * ssl_creds_from_buffer()
364  *
365  * Decode credentals from buffer into SSL_CREDENTIALS struct. Caller should
366  * free *creds with ssl_credentials_destroy()
367  *
368  * Returns SSL_SUCCESS or SSL_ERROR
369  */
370 int ssl_creds_from_buffer(unsigned char *buffer, int buffer_length,
371  SSL_CREDENTIALS **creds);
372 
373 /*
374  * ssl_creds_certificate_is_proxy()
375  *
376  * Returns 1 if certificate is proxy(RFC 3820, GT3, GT2) certificate.
377  * 0 if certificate is not proxy.
378  * -1 on error.
379  */
380 int ssl_creds_certificate_is_proxy(SSL_CREDENTIALS *creds);
381 
382 /*
383  * ssl_sign()
384  *
385  * Sign data with private key passed in SSL_CREDENTIALS. Memory for the
386  * signature is allocated with malloc(3) and must be freed with free(2) when
387  * no needed.
388  */
389 int ssl_sign(unsigned char *data, int length, SSL_CREDENTIALS *creds,
390  unsigned char **signature, int *signature_len);
391 
392 /*
393  * ssl_verify()
394  *
395  * Verify signature
396  */
397 int ssl_verify(unsigned char *data, int length, SSL_CREDENTIALS *creds,
398  unsigned char *signature, int signature_len);
399 
400 /*
401  * int ssl_verify_gsi_chain()
402  *
403  * Verify that supplied chain is valid for GSI authentication.
404  *
405  * Returns SSL_SUCCESS or SSL_ERROR
406  */
407 int ssl_verify_gsi_chain(SSL_CREDENTIALS *chain);
408 
409 /*
410  * int ssl_limited_proxy_chain()
411  *
412  * Return 1 if certificate chain includes a limited proxy,
413  * 0 if not, -1 on error.
414  */
415 int ssl_limited_proxy_chain(SSL_CREDENTIALS *chain);
416 
417 /*
418  * int ssl_limited_proxy_file()
419  *
420  * Return 1 if certificate chain in path includes a limited proxy,
421  * 0 if not, -1 on error.
422  */
423 int ssl_limited_proxy_file(const char path[]);
424 
425 /*
426  * ssl_get_times
427  *
428  */
429 int ssl_get_times(const char *proxyfile, time_t *not_before, time_t *not_after);
430 
431 /*
432  * ssl_error_to_verror()
433  *
434  * Transfer an error description out of the ssl error handler to verror.
435  */
436 void ssl_error_to_verror();
437 
438 /*
439  * globus_error_to_verror()
440  *
441  * Transfer an error description out of the Globus error handler to verror.
442  */
443 void globus_error_to_verror(globus_result_t result);
444 
445 /*
446  * ssl_verify_cred()
447  *
448  * Check the validity of the credentials at the given path:
449  * - check Not Before and Not After fields against current time
450  * - check signature by trusted CA
451  * - check revocation status (CRL, OCSP)
452  * Returns 0 on success, -1 on error (setting verror).
453  */
454 int ssl_verify_cred(const char path[]);
455 
456 #endif /* _SSL_UTILS_H */
Globus GSI Credential Library.
Globus GSI Callback.
Globus GSI Cert Utils Library.
Globus GSI Proxy API.
Globus GSI System Config Library.
Globus GSI System Config Library.
uint32_t globus_result_t
Definition: globus_types.h:99