1 /*************************************************
2 * Exim - an Internet mail transport agent *
3 *************************************************/
5 /* Copyright (c) University of Cambridge 1995 - 2018 */
6 /* See the file NOTICE for conditions of use and distribution. */
8 /* Copyright (c) Twitter Inc 2012
9 Author: Phil Pennock <pdp@exim.org> */
10 /* Copyright (c) Phil Pennock 2012 */
12 /* Interface to Heimdal library for GSSAPI authentication. */
14 /* Naming and rationale
16 Sensibly, this integration would be deferred to a SASL library, but none
17 of them appear to offer keytab file selection interfaces in their APIs. It
18 might be that this driver only requires minor modification to work with MIT
21 Heimdal provides a number of interfaces for various forms of authentication.
22 As GS2 does not appear to provide keytab control interfaces either, we may
23 end up supporting that too. It's possible that we could trivially expand to
24 support NTLM support via Heimdal, etc. Rather than try to be too generic
25 immediately, this driver is directly only supporting GSSAPI.
27 Without rename, we could add an option for GS2 support in the future.
32 * mailcheck-imap (Perl, client-side, written by me years ago)
33 * gsasl driver (GPL, server-side)
34 * heimdal sources and man-pages, plus http://www.h5l.org/manual/
35 * FreeBSD man-pages (very informative!)
36 * http://www.ggf.org/documents/GFD.24.pdf confirming GSS_KRB5_REGISTER_ACCEPTOR_IDENTITY_X
37 semantics, that found by browsing Heimdal source to find how to set the keytab; however,
38 after multiple attempts I failed to get that to work and instead switched to
39 gsskrb5_register_acceptor_identity().
44 #ifndef AUTH_HEIMDAL_GSSAPI
45 /* dummy function to satisfy compilers when we link in an "empty" file. */
46 static void dummy(int x);
47 static void dummy2(int x) { dummy(x-1); }
48 static void dummy(int x) { dummy2(x-1); }
51 #include <gssapi/gssapi.h>
52 #include <gssapi/gssapi_krb5.h>
54 /* for the _init debugging */
57 #include "heimdal_gssapi.h"
59 /* Authenticator-specific options. */
60 optionlist auth_heimdal_gssapi_options[] = {
61 { "server_hostname", opt_stringptr,
62 OPT_OFF(auth_heimdal_gssapi_options_block, server_hostname) },
63 { "server_keytab", opt_stringptr,
64 OPT_OFF(auth_heimdal_gssapi_options_block, server_keytab) },
65 { "server_service", opt_stringptr,
66 OPT_OFF(auth_heimdal_gssapi_options_block, server_service) }
69 int auth_heimdal_gssapi_options_count =
70 sizeof(auth_heimdal_gssapi_options)/sizeof(optionlist);
72 /* Defaults for the authenticator-specific options. */
73 auth_heimdal_gssapi_options_block auth_heimdal_gssapi_option_defaults = {
74 US"$primary_hostname", /* server_hostname */
75 NULL, /* server_keytab */
76 US"smtp", /* server_service */
83 void auth_heimdal_gssapi_init(auth_instance *ablock) {}
84 int auth_heimdal_gssapi_server(auth_instance *ablock, uschar *data) {return 0;}
85 int auth_heimdal_gssapi_client(auth_instance *ablock, void * sx,
86 int timeout, uschar *buffer, int buffsize) {return 0;}
87 void auth_heimdal_gssapi_version_report(FILE *f) {}
89 #else /*!MACRO_PREDEF*/
93 /* "Globals" for managing the heimdal_gssapi interface. */
95 /* Utility functions */
97 exim_heimdal_error_debug(const char *, krb5_context, krb5_error_code);
99 exim_gssapi_error_defer(rmark, OM_uint32, OM_uint32, const char *, ...)
100 PRINTF_FUNCTION(4, 5);
102 #define EmptyBuf(buf) do { buf.value = NULL; buf.length = 0; } while (0)
105 /*************************************************
106 * Initialization entry point *
107 *************************************************/
109 /* Called for each instance, after its options have been read, to
110 enable consistency checks to be done, or anything else that needs
113 /* Heimdal provides a GSSAPI extension method for setting the keytab;
114 in the init, we mostly just use raw krb5 methods so that we can report
115 the keytab contents, for -D+auth debugging. */
118 auth_heimdal_gssapi_init(auth_instance *ablock)
120 krb5_context context;
122 krb5_kt_cursor cursor;
123 krb5_keytab_entry entry;
125 char *principal, *enctype_s;
126 const char *k_keytab_typed_name = NULL;
127 auth_heimdal_gssapi_options_block *ob =
128 (auth_heimdal_gssapi_options_block *)(ablock->options_block);
130 ablock->server = FALSE;
131 ablock->client = FALSE;
133 if (!ob->server_service || !*ob->server_service)
135 HDEBUG(D_auth) debug_printf("heimdal: missing server_service\n");
139 if ((krc = krb5_init_context(&context)))
142 HDEBUG(D_auth) debug_printf("heimdal: failed to initialise krb5 context: %s\n",
147 if (ob->server_keytab)
149 k_keytab_typed_name = CCS string_sprintf("file:%s", expand_string(ob->server_keytab));
150 HDEBUG(D_auth) debug_printf("heimdal: using keytab %s\n", k_keytab_typed_name);
151 if ((krc = krb5_kt_resolve(context, k_keytab_typed_name, &keytab)))
153 HDEBUG(D_auth) exim_heimdal_error_debug("krb5_kt_resolve", context, krc);
159 HDEBUG(D_auth) debug_printf("heimdal: using system default keytab\n");
160 if ((krc = krb5_kt_default(context, &keytab)))
162 HDEBUG(D_auth) exim_heimdal_error_debug("krb5_kt_default", context, krc);
169 /* http://www.h5l.org/manual/HEAD/krb5/krb5_keytab_intro.html */
170 if ((krc = krb5_kt_start_seq_get(context, keytab, &cursor)))
171 exim_heimdal_error_debug("krb5_kt_start_seq_get", context, krc);
174 while (!(krc = krb5_kt_next_entry(context, keytab, &entry, &cursor)))
176 principal = enctype_s = NULL;
177 krb5_unparse_name(context, entry.principal, &principal);
178 krb5_enctype_to_string(context, entry.keyblock.keytype, &enctype_s);
179 debug_printf("heimdal: keytab principal: %s vno=%d type=%s\n",
180 principal ? principal : "??",
182 enctype_s ? enctype_s : "??");
185 krb5_kt_free_entry(context, &entry);
187 if ((krc = krb5_kt_end_seq_get(context, keytab, &cursor)))
188 exim_heimdal_error_debug("krb5_kt_end_seq_get", context, krc);
192 if ((krc = krb5_kt_close(context, keytab)))
193 HDEBUG(D_auth) exim_heimdal_error_debug("krb5_kt_close", context, krc);
195 krb5_free_context(context);
197 ablock->server = TRUE;
202 exim_heimdal_error_debug(const char *label,
203 krb5_context context, krb5_error_code err)
206 kerrsc = krb5_get_error_message(context, err);
207 debug_printf("heimdal %s: %s\n", label, kerrsc ? kerrsc : "unknown error");
208 krb5_free_error_message(context, kerrsc);
211 /*************************************************
212 * Server entry point *
213 *************************************************/
215 /* For interface, see auths/README */
218 OM_uint32: portable type for unsigned int32
219 gss_buffer_desc / *gss_buffer_t: hold/point-to size_t .length & void *value
220 -- all strings/etc passed in should go through one of these
221 -- when allocated by gssapi, release with gss_release_buffer()
225 auth_heimdal_gssapi_server(auth_instance *ablock, uschar *initial_data)
227 gss_name_t gclient = GSS_C_NO_NAME;
228 gss_name_t gserver = GSS_C_NO_NAME;
229 gss_cred_id_t gcred = GSS_C_NO_CREDENTIAL;
230 gss_ctx_id_t gcontext = GSS_C_NO_CONTEXT;
231 uschar *ex_server_str;
232 gss_buffer_desc gbufdesc = GSS_C_EMPTY_BUFFER;
233 gss_buffer_desc gbufdesc_in = GSS_C_EMPTY_BUFFER;
234 gss_buffer_desc gbufdesc_out = GSS_C_EMPTY_BUFFER;
236 OM_uint32 maj_stat, min_stat;
238 uschar *tmp1, *tmp2, *from_client;
239 auth_heimdal_gssapi_options_block *ob =
240 (auth_heimdal_gssapi_options_block *)(ablock->options_block);
241 BOOL handled_empty_ir;
242 rmark store_reset_point;
244 uschar sasl_config[4];
245 uschar requested_qop;
247 store_reset_point = store_mark();
250 debug_printf("heimdal: initialising auth context for %s\n", ablock->name);
252 /* Construct our gss_name_t gserver describing ourselves */
253 tmp1 = expand_string(ob->server_service);
254 tmp2 = expand_string(ob->server_hostname);
255 ex_server_str = string_sprintf("%s@%s", tmp1, tmp2);
256 gbufdesc.value = (void *) ex_server_str;
257 gbufdesc.length = Ustrlen(ex_server_str);
258 maj_stat = gss_import_name(&min_stat,
259 &gbufdesc, GSS_C_NT_HOSTBASED_SERVICE, &gserver);
260 if (GSS_ERROR(maj_stat))
261 return exim_gssapi_error_defer(store_reset_point, maj_stat, min_stat,
262 "gss_import_name(%s)", CS gbufdesc.value);
264 /* Use a specific keytab, if specified */
265 if (ob->server_keytab)
267 keytab = expand_string(ob->server_keytab);
268 maj_stat = gsskrb5_register_acceptor_identity(CCS keytab);
269 if (GSS_ERROR(maj_stat))
270 return exim_gssapi_error_defer(store_reset_point, maj_stat, min_stat,
271 "registering keytab \"%s\"", keytab);
273 debug_printf("heimdal: using keytab \"%s\"\n", keytab);
276 /* Acquire our credentials */
277 maj_stat = gss_acquire_cred(&min_stat,
278 gserver, /* desired name */
280 GSS_C_NULL_OID_SET, /* desired mechs */
281 GSS_C_ACCEPT, /* cred usage */
283 NULL /* actual mechs */,
284 NULL /* time rec */);
285 if (GSS_ERROR(maj_stat))
286 return exim_gssapi_error_defer(store_reset_point, maj_stat, min_stat,
287 "gss_acquire_cred(%s)", ex_server_str);
289 maj_stat = gss_release_name(&min_stat, &gserver);
291 HDEBUG(D_auth) debug_printf("heimdal: have server credentials.\n");
293 /* Loop talking to client */
295 from_client = initial_data;
296 handled_empty_ir = FALSE;
299 /* buffer sizes: auth_get_data() uses big_buffer, which we grow per
300 GSSAPI RFC in _init, if needed, to meet the SHOULD size of 64KB.
301 (big_buffer starts life at the MUST size of 16KB). */
304 0: getting initial data from client to feed into GSSAPI
305 1: iterating for as long as GSS_S_CONTINUE_NEEDED
306 2: GSS_S_COMPLETE, SASL wrapping for authz and qop to send to client
307 3: unpick final auth message from client
308 4: break/finish (non-step)
314 if (!from_client || !*from_client)
316 if (handled_empty_ir)
318 HDEBUG(D_auth) debug_printf("gssapi: repeated empty input, grr.\n");
323 HDEBUG(D_auth) debug_printf("gssapi: missing initial response, nudging.\n");
324 if ((error_out = auth_get_data(&from_client, US"", 0)) != OK)
326 handled_empty_ir = TRUE;
329 /* We should now have the opening data from the client, base64-encoded. */
331 HDEBUG(D_auth) debug_printf("heimdal: have initial client data\n");
335 gbufdesc_in.length = b64decode(from_client, USS &gbufdesc_in.value);
338 maj_stat = gss_release_name(&min_stat, &gclient);
339 gclient = GSS_C_NO_NAME;
341 maj_stat = gss_accept_sec_context(&min_stat,
342 &gcontext, /* context handle */
343 gcred, /* acceptor cred handle */
344 &gbufdesc_in, /* input from client */
345 GSS_C_NO_CHANNEL_BINDINGS, /* XXX fixme: use the channel bindings from GnuTLS */
346 &gclient, /* client identifier */
347 &mech_type, /* mechanism in use */
348 &gbufdesc_out, /* output to send to client */
349 NULL, /* return flags */
351 NULL /* delegated cred_handle */
353 if (GSS_ERROR(maj_stat))
355 exim_gssapi_error_defer(NULL, maj_stat, min_stat,
356 "gss_accept_sec_context()");
360 if (gbufdesc_out.length != 0)
362 error_out = auth_get_data(&from_client,
363 gbufdesc_out.value, gbufdesc_out.length);
367 gss_release_buffer(&min_stat, &gbufdesc_out);
368 EmptyBuf(gbufdesc_out);
370 if (maj_stat == GSS_S_COMPLETE)
373 HDEBUG(D_auth) debug_printf("heimdal: GSS complete\n");
376 HDEBUG(D_auth) debug_printf("heimdal: need more data\n");
380 memset(sasl_config, 0xFF, 4);
381 /* draft-ietf-sasl-gssapi-06.txt defines bitmasks for first octet
382 0x01 No security layer
383 0x02 Integrity protection
384 0x04 Confidentiality protection
386 The remaining three octets are the maximum buffer size for wrapped
388 sasl_config[0] = 0x01; /* Exim does not wrap/unwrap SASL layers after auth */
389 gbufdesc.value = (void *) sasl_config;
391 maj_stat = gss_wrap(&min_stat,
393 0, /* conf_req_flag: integrity only */
394 GSS_C_QOP_DEFAULT, /* qop requested */
395 &gbufdesc, /* message to protect */
396 NULL, /* conf_state: no confidentiality applied */
397 &gbufdesc_out /* output buffer */
399 if (GSS_ERROR(maj_stat))
401 exim_gssapi_error_defer(NULL, maj_stat, min_stat,
402 "gss_wrap(SASL state after auth)");
407 HDEBUG(D_auth) debug_printf("heimdal SASL: requesting QOP with no security layers\n");
409 error_out = auth_get_data(&from_client,
410 gbufdesc_out.value, gbufdesc_out.length);
414 gss_release_buffer(&min_stat, &gbufdesc_out);
415 EmptyBuf(gbufdesc_out);
420 gbufdesc_in.length = b64decode(from_client, USS &gbufdesc_in.value);
421 maj_stat = gss_unwrap(&min_stat,
423 &gbufdesc_in, /* data from client */
424 &gbufdesc_out, /* results */
425 NULL, /* conf state */
428 if (GSS_ERROR(maj_stat))
430 exim_gssapi_error_defer(NULL, maj_stat, min_stat,
431 "gss_unwrap(final SASL message from client)");
435 if (gbufdesc_out.length < 4)
438 debug_printf("gssapi: final message too short; "
439 "need flags, buf sizes and optional authzid\n");
444 requested_qop = (CS gbufdesc_out.value)[0];
445 if (!(requested_qop & 0x01))
448 debug_printf("gssapi: client requested security layers (%x)\n",
449 (unsigned int) requested_qop);
454 for (int i = 0; i < AUTH_VARS; i++) auth_vars[i] = NULL;
458 The SASL provided identifier is an unverified authzid.
459 GSSAPI provides us with a verified identifier, but it might be empty
463 /* $auth2 is authzid requested at SASL layer */
464 if (gbufdesc_out.length > 4)
466 expand_nlength[2] = gbufdesc_out.length - 4;
467 auth_vars[1] = expand_nstring[2] =
468 string_copyn((US gbufdesc_out.value) + 4, expand_nlength[2]);
472 gss_release_buffer(&min_stat, &gbufdesc_out);
473 EmptyBuf(gbufdesc_out);
475 /* $auth1 is GSSAPI display name */
476 maj_stat = gss_display_name(&min_stat,
477 gclient, &gbufdesc_out, &mech_type);
478 if (GSS_ERROR(maj_stat))
480 auth_vars[1] = expand_nstring[2] = NULL;
482 exim_gssapi_error_defer(NULL, maj_stat, min_stat,
483 "gss_display_name(client identifier)");
488 expand_nlength[1] = gbufdesc_out.length;
489 auth_vars[0] = expand_nstring[1] =
490 string_copyn(gbufdesc_out.value, gbufdesc_out.length);
492 if (expand_nmax == 0) /* should be: authzid was empty */
495 expand_nlength[2] = expand_nlength[1];
496 auth_vars[1] = expand_nstring[2] = string_copyn(expand_nstring[1], expand_nlength[1]);
498 debug_printf("heimdal SASL: empty authzid, set to dup of GSSAPI display name\n");
502 debug_printf("heimdal SASL: happy with client request\n"
503 " auth1 (verified GSSAPI display-name): \"%s\"\n"
504 " auth2 (unverified SASL requested authzid): \"%s\"\n",
505 auth_vars[0], auth_vars[1]);
515 maj_stat = gss_release_cred(&min_stat, &gcred);
518 gss_release_name(&min_stat, &gclient);
519 gclient = GSS_C_NO_NAME;
521 if (gbufdesc_out.length)
523 gss_release_buffer(&min_stat, &gbufdesc_out);
524 EmptyBuf(gbufdesc_out);
526 if (gcontext != GSS_C_NO_CONTEXT)
527 gss_delete_sec_context(&min_stat, &gcontext, GSS_C_NO_BUFFER);
529 store_reset(store_reset_point);
534 /* Auth succeeded, check server_condition */
535 return auth_check_serv_cond(ablock);
540 exim_gssapi_error_defer(rmark store_reset_point,
541 OM_uint32 major, OM_uint32 minor,
542 const char *format, ...)
545 OM_uint32 maj_stat, min_stat;
546 OM_uint32 msgcontext = 0;
547 gss_buffer_desc status_string;
552 va_start(ap, format);
553 g = string_vformat(NULL, SVFMT_EXTEND|SVFMT_REBUFFER, format, ap);
557 auth_defer_msg = NULL;
560 maj_stat = gss_display_status(&min_stat,
561 major, GSS_C_GSS_CODE, GSS_C_NO_OID, &msgcontext, &status_string);
564 auth_defer_msg = string_copy(US status_string.value);
566 HDEBUG(D_auth) debug_printf("heimdal %s: %.*s\n",
567 string_from_gstring(g), (int)status_string.length,
568 CS status_string.value);
569 gss_release_buffer(&min_stat, &status_string);
571 } while (msgcontext != 0);
573 if (store_reset_point)
574 store_reset(store_reset_point);
579 /*************************************************
580 * Client entry point *
581 *************************************************/
583 /* For interface, see auths/README */
586 auth_heimdal_gssapi_client(
587 auth_instance *ablock, /* authenticator block */
588 void * sx, /* connection */
589 int timeout, /* command timeout */
590 uschar *buffer, /* buffer for reading response */
591 int buffsize) /* size of buffer */
594 debug_printf("Client side NOT IMPLEMENTED: you should not see this!\n");
595 /* NOT IMPLEMENTED */
599 /*************************************************
601 *************************************************/
604 auth_heimdal_gssapi_version_report(FILE *f)
606 /* No build-time constants available unless we link against libraries at
607 build-time and export the result as a string into a header ourselves. */
608 fprintf(f, "Library version: Heimdal: Runtime: %s\n"
610 heimdal_version, heimdal_long_version);
613 #endif /*!MACRO_PREDEF*/
614 #endif /* AUTH_HEIMDAL_GSSAPI */
616 /* End of heimdal_gssapi.c */