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 (void *)(offsetof(auth_heimdal_gssapi_options_block, server_hostname)) },
63 { "server_keytab", opt_stringptr,
64 (void *)(offsetof(auth_heimdal_gssapi_options_block, server_keytab)) },
65 { "server_service", opt_stringptr,
66 (void *)(offsetof(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 krc = krb5_init_context(&context);
143 HDEBUG(D_auth) debug_printf("heimdal: failed to initialise krb5 context: %s\n",
148 if (ob->server_keytab)
150 k_keytab_typed_name = CCS string_sprintf("file:%s", expand_string(ob->server_keytab));
151 HDEBUG(D_auth) debug_printf("heimdal: using keytab %s\n", k_keytab_typed_name);
152 krc = krb5_kt_resolve(context, k_keytab_typed_name, &keytab);
155 HDEBUG(D_auth) exim_heimdal_error_debug("krb5_kt_resolve", context, krc);
161 HDEBUG(D_auth) debug_printf("heimdal: using system default keytab\n");
162 krc = krb5_kt_default(context, &keytab);
165 HDEBUG(D_auth) exim_heimdal_error_debug("krb5_kt_default", context, krc);
172 /* http://www.h5l.org/manual/HEAD/krb5/krb5_keytab_intro.html */
173 krc = krb5_kt_start_seq_get(context, keytab, &cursor);
175 exim_heimdal_error_debug("krb5_kt_start_seq_get", context, krc);
178 while ((krc = krb5_kt_next_entry(context, keytab, &entry, &cursor)) == 0)
180 principal = enctype_s = NULL;
181 krb5_unparse_name(context, entry.principal, &principal);
182 krb5_enctype_to_string(context, entry.keyblock.keytype, &enctype_s);
183 debug_printf("heimdal: keytab principal: %s vno=%d type=%s\n",
184 principal ? principal : "??",
186 enctype_s ? enctype_s : "??");
189 krb5_kt_free_entry(context, &entry);
191 krc = krb5_kt_end_seq_get(context, keytab, &cursor);
193 exim_heimdal_error_debug("krb5_kt_end_seq_get", context, krc);
197 krc = krb5_kt_close(context, keytab);
199 HDEBUG(D_auth) exim_heimdal_error_debug("krb5_kt_close", context, krc);
201 krb5_free_context(context);
203 /* RFC 4121 section 5.2, SHOULD support 64K input buffers */
204 if (big_buffer_size < (64 * 1024))
207 big_buffer_size = 64 * 1024;
208 newbuf = store_malloc(big_buffer_size);
209 store_free(big_buffer);
213 ablock->server = TRUE;
218 exim_heimdal_error_debug(const char *label,
219 krb5_context context, krb5_error_code err)
222 kerrsc = krb5_get_error_message(context, err);
223 debug_printf("heimdal %s: %s\n", label, kerrsc ? kerrsc : "unknown error");
224 krb5_free_error_message(context, kerrsc);
227 /*************************************************
228 * Server entry point *
229 *************************************************/
231 /* For interface, see auths/README */
234 OM_uint32: portable type for unsigned int32
235 gss_buffer_desc / *gss_buffer_t: hold/point-to size_t .length & void *value
236 -- all strings/etc passed in should go through one of these
237 -- when allocated by gssapi, release with gss_release_buffer()
241 auth_heimdal_gssapi_server(auth_instance *ablock, uschar *initial_data)
243 gss_name_t gclient = GSS_C_NO_NAME;
244 gss_name_t gserver = GSS_C_NO_NAME;
245 gss_cred_id_t gcred = GSS_C_NO_CREDENTIAL;
246 gss_ctx_id_t gcontext = GSS_C_NO_CONTEXT;
247 uschar *ex_server_str;
248 gss_buffer_desc gbufdesc = GSS_C_EMPTY_BUFFER;
249 gss_buffer_desc gbufdesc_in = GSS_C_EMPTY_BUFFER;
250 gss_buffer_desc gbufdesc_out = GSS_C_EMPTY_BUFFER;
252 OM_uint32 maj_stat, min_stat;
254 uschar *tmp1, *tmp2, *from_client;
255 auth_heimdal_gssapi_options_block *ob =
256 (auth_heimdal_gssapi_options_block *)(ablock->options_block);
257 BOOL handled_empty_ir;
258 rmark store_reset_point;
260 uschar sasl_config[4];
261 uschar requested_qop;
263 store_reset_point = store_mark();
266 debug_printf("heimdal: initialising auth context for %s\n", ablock->name);
268 /* Construct our gss_name_t gserver describing ourselves */
269 tmp1 = expand_string(ob->server_service);
270 tmp2 = expand_string(ob->server_hostname);
271 ex_server_str = string_sprintf("%s@%s", tmp1, tmp2);
272 gbufdesc.value = (void *) ex_server_str;
273 gbufdesc.length = Ustrlen(ex_server_str);
274 maj_stat = gss_import_name(&min_stat,
275 &gbufdesc, GSS_C_NT_HOSTBASED_SERVICE, &gserver);
276 if (GSS_ERROR(maj_stat))
277 return exim_gssapi_error_defer(store_reset_point, maj_stat, min_stat,
278 "gss_import_name(%s)", CS gbufdesc.value);
280 /* Use a specific keytab, if specified */
281 if (ob->server_keytab)
283 keytab = expand_string(ob->server_keytab);
284 maj_stat = gsskrb5_register_acceptor_identity(CCS keytab);
285 if (GSS_ERROR(maj_stat))
286 return exim_gssapi_error_defer(store_reset_point, maj_stat, min_stat,
287 "registering keytab \"%s\"", keytab);
289 debug_printf("heimdal: using keytab \"%s\"\n", keytab);
292 /* Acquire our credentials */
293 maj_stat = gss_acquire_cred(&min_stat,
294 gserver, /* desired name */
296 GSS_C_NULL_OID_SET, /* desired mechs */
297 GSS_C_ACCEPT, /* cred usage */
299 NULL /* actual mechs */,
300 NULL /* time rec */);
301 if (GSS_ERROR(maj_stat))
302 return exim_gssapi_error_defer(store_reset_point, maj_stat, min_stat,
303 "gss_acquire_cred(%s)", ex_server_str);
305 maj_stat = gss_release_name(&min_stat, &gserver);
307 HDEBUG(D_auth) debug_printf("heimdal: have server credentials.\n");
309 /* Loop talking to client */
311 from_client = initial_data;
312 handled_empty_ir = FALSE;
315 /* buffer sizes: auth_get_data() uses big_buffer, which we grow per
316 GSSAPI RFC in _init, if needed, to meet the SHOULD size of 64KB.
317 (big_buffer starts life at the MUST size of 16KB). */
320 0: getting initial data from client to feed into GSSAPI
321 1: iterating for as long as GSS_S_CONTINUE_NEEDED
322 2: GSS_S_COMPLETE, SASL wrapping for authz and qop to send to client
323 3: unpick final auth message from client
324 4: break/finish (non-step)
330 if (!from_client || *from_client == '\0')
332 if (handled_empty_ir)
334 HDEBUG(D_auth) debug_printf("gssapi: repeated empty input, grr.\n");
340 HDEBUG(D_auth) debug_printf("gssapi: missing initial response, nudging.\n");
341 error_out = auth_get_data(&from_client, US"", 0);
344 handled_empty_ir = TRUE;
348 /* We should now have the opening data from the client, base64-encoded. */
350 HDEBUG(D_auth) debug_printf("heimdal: have initial client data\n");
354 gbufdesc_in.length = b64decode(from_client, USS &gbufdesc_in.value);
357 maj_stat = gss_release_name(&min_stat, &gclient);
358 gclient = GSS_C_NO_NAME;
360 maj_stat = gss_accept_sec_context(&min_stat,
361 &gcontext, /* context handle */
362 gcred, /* acceptor cred handle */
363 &gbufdesc_in, /* input from client */
364 GSS_C_NO_CHANNEL_BINDINGS, /* XXX fixme: use the channel bindings from GnuTLS */
365 &gclient, /* client identifier */
366 &mech_type, /* mechanism in use */
367 &gbufdesc_out, /* output to send to client */
368 NULL, /* return flags */
370 NULL /* delegated cred_handle */
372 if (GSS_ERROR(maj_stat))
374 exim_gssapi_error_defer(NULL, maj_stat, min_stat,
375 "gss_accept_sec_context()");
379 if (gbufdesc_out.length != 0)
381 error_out = auth_get_data(&from_client,
382 gbufdesc_out.value, gbufdesc_out.length);
386 gss_release_buffer(&min_stat, &gbufdesc_out);
387 EmptyBuf(gbufdesc_out);
389 if (maj_stat == GSS_S_COMPLETE)
392 HDEBUG(D_auth) debug_printf("heimdal: GSS complete\n");
395 HDEBUG(D_auth) debug_printf("heimdal: need more data\n");
399 memset(sasl_config, 0xFF, 4);
400 /* draft-ietf-sasl-gssapi-06.txt defines bitmasks for first octet
401 0x01 No security layer
402 0x02 Integrity protection
403 0x04 Confidentiality protection
405 The remaining three octets are the maximum buffer size for wrapped
407 sasl_config[0] = 0x01; /* Exim does not wrap/unwrap SASL layers after auth */
408 gbufdesc.value = (void *) sasl_config;
410 maj_stat = gss_wrap(&min_stat,
412 0, /* conf_req_flag: integrity only */
413 GSS_C_QOP_DEFAULT, /* qop requested */
414 &gbufdesc, /* message to protect */
415 NULL, /* conf_state: no confidentiality applied */
416 &gbufdesc_out /* output buffer */
418 if (GSS_ERROR(maj_stat))
420 exim_gssapi_error_defer(NULL, maj_stat, min_stat,
421 "gss_wrap(SASL state after auth)");
426 HDEBUG(D_auth) debug_printf("heimdal SASL: requesting QOP with no security layers\n");
428 error_out = auth_get_data(&from_client,
429 gbufdesc_out.value, gbufdesc_out.length);
433 gss_release_buffer(&min_stat, &gbufdesc_out);
434 EmptyBuf(gbufdesc_out);
439 gbufdesc_in.length = b64decode(from_client, USS &gbufdesc_in.value);
440 maj_stat = gss_unwrap(&min_stat,
442 &gbufdesc_in, /* data from client */
443 &gbufdesc_out, /* results */
444 NULL, /* conf state */
447 if (GSS_ERROR(maj_stat))
449 exim_gssapi_error_defer(NULL, maj_stat, min_stat,
450 "gss_unwrap(final SASL message from client)");
454 if (gbufdesc_out.length < 4)
457 debug_printf("gssapi: final message too short; "
458 "need flags, buf sizes and optional authzid\n");
463 requested_qop = (CS gbufdesc_out.value)[0];
464 if ((requested_qop & 0x01) == 0)
467 debug_printf("gssapi: client requested security layers (%x)\n",
468 (unsigned int) requested_qop);
473 for (int i = 0; i < AUTH_VARS; i++) auth_vars[i] = NULL;
477 The SASL provided identifier is an unverified authzid.
478 GSSAPI provides us with a verified identifier, but it might be empty
482 /* $auth2 is authzid requested at SASL layer */
483 if (gbufdesc_out.length > 4)
485 expand_nlength[2] = gbufdesc_out.length - 4;
486 auth_vars[1] = expand_nstring[2] =
487 string_copyn((US gbufdesc_out.value) + 4, expand_nlength[2]);
491 gss_release_buffer(&min_stat, &gbufdesc_out);
492 EmptyBuf(gbufdesc_out);
494 /* $auth1 is GSSAPI display name */
495 maj_stat = gss_display_name(&min_stat,
499 if (GSS_ERROR(maj_stat))
501 auth_vars[1] = expand_nstring[2] = NULL;
503 exim_gssapi_error_defer(NULL, maj_stat, min_stat,
504 "gss_display_name(client identifier)");
509 expand_nlength[1] = gbufdesc_out.length;
510 auth_vars[0] = expand_nstring[1] =
511 string_copyn(gbufdesc_out.value, gbufdesc_out.length);
513 if (expand_nmax == 0) /* should be: authzid was empty */
516 expand_nlength[2] = expand_nlength[1];
517 auth_vars[1] = expand_nstring[2] = string_copyn(expand_nstring[1], expand_nlength[1]);
519 debug_printf("heimdal SASL: empty authzid, set to dup of GSSAPI display name\n");
523 debug_printf("heimdal SASL: happy with client request\n"
524 " auth1 (verified GSSAPI display-name): \"%s\"\n"
525 " auth2 (unverified SASL requested authzid): \"%s\"\n",
526 auth_vars[0], auth_vars[1]);
536 maj_stat = gss_release_cred(&min_stat, &gcred);
539 gss_release_name(&min_stat, &gclient);
540 gclient = GSS_C_NO_NAME;
542 if (gbufdesc_out.length)
544 gss_release_buffer(&min_stat, &gbufdesc_out);
545 EmptyBuf(gbufdesc_out);
547 if (gcontext != GSS_C_NO_CONTEXT)
548 gss_delete_sec_context(&min_stat, &gcontext, GSS_C_NO_BUFFER);
550 store_reset(store_reset_point);
555 /* Auth succeeded, check server_condition */
556 return auth_check_serv_cond(ablock);
561 exim_gssapi_error_defer(rmark store_reset_point,
562 OM_uint32 major, OM_uint32 minor,
563 const char *format, ...)
566 OM_uint32 maj_stat, min_stat;
567 OM_uint32 msgcontext = 0;
568 gss_buffer_desc status_string;
573 va_start(ap, format);
574 g = string_vformat(NULL, SVFMT_EXTEND|SVFMT_REBUFFER, format, ap);
578 auth_defer_msg = NULL;
581 maj_stat = gss_display_status(&min_stat,
582 major, GSS_C_GSS_CODE, GSS_C_NO_OID, &msgcontext, &status_string);
585 auth_defer_msg = string_copy(US status_string.value);
587 HDEBUG(D_auth) debug_printf("heimdal %s: %.*s\n",
588 string_from_gstring(g), (int)status_string.length,
589 CS status_string.value);
590 gss_release_buffer(&min_stat, &status_string);
592 } while (msgcontext != 0);
594 if (store_reset_point)
595 store_reset(store_reset_point);
600 /*************************************************
601 * Client entry point *
602 *************************************************/
604 /* For interface, see auths/README */
607 auth_heimdal_gssapi_client(
608 auth_instance *ablock, /* authenticator block */
609 void * sx, /* connection */
610 int timeout, /* command timeout */
611 uschar *buffer, /* buffer for reading response */
612 int buffsize) /* size of buffer */
615 debug_printf("Client side NOT IMPLEMENTED: you should not see this!\n");
616 /* NOT IMPLEMENTED */
620 /*************************************************
622 *************************************************/
625 auth_heimdal_gssapi_version_report(FILE *f)
627 /* No build-time constants available unless we link against libraries at
628 build-time and export the result as a string into a header ourselves. */
629 fprintf(f, "Library version: Heimdal: Runtime: %s\n"
631 heimdal_version, heimdal_long_version);
634 #endif /*!MACRO_PREDEF*/
635 #endif /* AUTH_HEIMDAL_GSSAPI */
637 /* End of heimdal_gssapi.c */