1 /*************************************************
2 * Exim - an Internet mail transport agent *
3 *************************************************/
5 /* Copyright (c) University of Cambridge 1995 - 2018 */
6 /* Copyright (c) The Exim Maintainers 2020 */
7 /* See the file NOTICE for conditions of use and distribution. */
9 /* Copyright (c) Twitter Inc 2012
10 Author: Phil Pennock <pdp@exim.org> */
11 /* Copyright (c) Phil Pennock 2012 */
13 /* Interface to Heimdal library for GSSAPI authentication. */
15 /* Naming and rationale
17 Sensibly, this integration would be deferred to a SASL library, but none
18 of them appear to offer keytab file selection interfaces in their APIs. It
19 might be that this driver only requires minor modification to work with MIT
22 Heimdal provides a number of interfaces for various forms of authentication.
23 As GS2 does not appear to provide keytab control interfaces either, we may
24 end up supporting that too. It's possible that we could trivially expand to
25 support NTLM support via Heimdal, etc. Rather than try to be too generic
26 immediately, this driver is directly only supporting GSSAPI.
28 Without rename, we could add an option for GS2 support in the future.
33 * mailcheck-imap (Perl, client-side, written by me years ago)
34 * gsasl driver (GPL, server-side)
35 * heimdal sources and man-pages, plus http://www.h5l.org/manual/
36 * FreeBSD man-pages (very informative!)
37 * http://www.ggf.org/documents/GFD.24.pdf confirming GSS_KRB5_REGISTER_ACCEPTOR_IDENTITY_X
38 semantics, that found by browsing Heimdal source to find how to set the keytab; however,
39 after multiple attempts I failed to get that to work and instead switched to
40 gsskrb5_register_acceptor_identity().
45 #ifndef AUTH_HEIMDAL_GSSAPI
46 /* dummy function to satisfy compilers when we link in an "empty" file. */
47 static void dummy(int x);
48 static void dummy2(int x) { dummy(x-1); }
49 static void dummy(int x) { dummy2(x-1); }
52 #include <gssapi/gssapi.h>
53 #include <gssapi/gssapi_krb5.h>
55 /* for the _init debugging */
58 #include "heimdal_gssapi.h"
60 /* Authenticator-specific options. */
61 optionlist auth_heimdal_gssapi_options[] = {
62 { "server_hostname", opt_stringptr,
63 OPT_OFF(auth_heimdal_gssapi_options_block, server_hostname) },
64 { "server_keytab", opt_stringptr,
65 OPT_OFF(auth_heimdal_gssapi_options_block, server_keytab) },
66 { "server_service", opt_stringptr,
67 OPT_OFF(auth_heimdal_gssapi_options_block, server_service) }
70 int auth_heimdal_gssapi_options_count =
71 sizeof(auth_heimdal_gssapi_options)/sizeof(optionlist);
73 /* Defaults for the authenticator-specific options. */
74 auth_heimdal_gssapi_options_block auth_heimdal_gssapi_option_defaults = {
75 US"$primary_hostname", /* server_hostname */
76 NULL, /* server_keytab */
77 US"smtp", /* server_service */
84 void auth_heimdal_gssapi_init(auth_instance *ablock) {}
85 int auth_heimdal_gssapi_server(auth_instance *ablock, uschar *data) {return 0;}
86 int auth_heimdal_gssapi_client(auth_instance *ablock, void * sx,
87 int timeout, uschar *buffer, int buffsize) {return 0;}
88 void auth_heimdal_gssapi_version_report(FILE *f) {}
90 #else /*!MACRO_PREDEF*/
94 /* "Globals" for managing the heimdal_gssapi interface. */
96 /* Utility functions */
98 exim_heimdal_error_debug(const char *, krb5_context, krb5_error_code);
100 exim_gssapi_error_defer(rmark, OM_uint32, OM_uint32, const char *, ...)
101 PRINTF_FUNCTION(4, 5);
103 #define EmptyBuf(buf) do { buf.value = NULL; buf.length = 0; } while (0)
106 /*************************************************
107 * Initialization entry point *
108 *************************************************/
110 /* Called for each instance, after its options have been read, to
111 enable consistency checks to be done, or anything else that needs
114 /* Heimdal provides a GSSAPI extension method for setting the keytab;
115 in the init, we mostly just use raw krb5 methods so that we can report
116 the keytab contents, for -D+auth debugging. */
119 auth_heimdal_gssapi_init(auth_instance *ablock)
121 krb5_context context;
123 krb5_kt_cursor cursor;
124 krb5_keytab_entry entry;
126 char *principal, *enctype_s;
127 const char *k_keytab_typed_name = NULL;
128 auth_heimdal_gssapi_options_block *ob =
129 (auth_heimdal_gssapi_options_block *)(ablock->options_block);
131 ablock->server = FALSE;
132 ablock->client = FALSE;
134 if (!ob->server_service || !*ob->server_service)
136 HDEBUG(D_auth) debug_printf("heimdal: missing server_service\n");
140 if ((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 if ((krc = krb5_kt_resolve(context, k_keytab_typed_name, &keytab)))
154 HDEBUG(D_auth) exim_heimdal_error_debug("krb5_kt_resolve", context, krc);
160 HDEBUG(D_auth) debug_printf("heimdal: using system default keytab\n");
161 if ((krc = krb5_kt_default(context, &keytab)))
163 HDEBUG(D_auth) exim_heimdal_error_debug("krb5_kt_default", context, krc);
170 /* http://www.h5l.org/manual/HEAD/krb5/krb5_keytab_intro.html */
171 if ((krc = krb5_kt_start_seq_get(context, keytab, &cursor)))
172 exim_heimdal_error_debug("krb5_kt_start_seq_get", context, krc);
175 while (!(krc = krb5_kt_next_entry(context, keytab, &entry, &cursor)))
177 principal = enctype_s = NULL;
178 krb5_unparse_name(context, entry.principal, &principal);
179 krb5_enctype_to_string(context, entry.keyblock.keytype, &enctype_s);
180 debug_printf("heimdal: keytab principal: %s vno=%d type=%s\n",
181 principal ? principal : "??",
183 enctype_s ? enctype_s : "??");
186 krb5_kt_free_entry(context, &entry);
188 if ((krc = krb5_kt_end_seq_get(context, keytab, &cursor)))
189 exim_heimdal_error_debug("krb5_kt_end_seq_get", context, krc);
193 if ((krc = krb5_kt_close(context, keytab)))
194 HDEBUG(D_auth) exim_heimdal_error_debug("krb5_kt_close", context, krc);
196 krb5_free_context(context);
198 ablock->server = TRUE;
203 exim_heimdal_error_debug(const char *label,
204 krb5_context context, krb5_error_code err)
207 kerrsc = krb5_get_error_message(context, err);
208 debug_printf("heimdal %s: %s\n", label, kerrsc ? kerrsc : "unknown error");
209 krb5_free_error_message(context, kerrsc);
212 /*************************************************
213 * Server entry point *
214 *************************************************/
216 /* For interface, see auths/README */
219 OM_uint32: portable type for unsigned int32
220 gss_buffer_desc / *gss_buffer_t: hold/point-to size_t .length & void *value
221 -- all strings/etc passed in should go through one of these
222 -- when allocated by gssapi, release with gss_release_buffer()
226 auth_heimdal_gssapi_server(auth_instance *ablock, uschar *initial_data)
228 gss_name_t gclient = GSS_C_NO_NAME;
229 gss_name_t gserver = GSS_C_NO_NAME;
230 gss_cred_id_t gcred = GSS_C_NO_CREDENTIAL;
231 gss_ctx_id_t gcontext = GSS_C_NO_CONTEXT;
232 uschar *ex_server_str;
233 gss_buffer_desc gbufdesc = GSS_C_EMPTY_BUFFER;
234 gss_buffer_desc gbufdesc_in = GSS_C_EMPTY_BUFFER;
235 gss_buffer_desc gbufdesc_out = GSS_C_EMPTY_BUFFER;
237 OM_uint32 maj_stat, min_stat;
239 uschar *tmp1, *tmp2, *from_client;
240 auth_heimdal_gssapi_options_block *ob =
241 (auth_heimdal_gssapi_options_block *)(ablock->options_block);
242 BOOL handled_empty_ir;
243 rmark store_reset_point;
245 uschar sasl_config[4];
246 uschar requested_qop;
248 store_reset_point = store_mark();
251 debug_printf("heimdal: initialising auth context for %s\n", ablock->name);
253 /* Construct our gss_name_t gserver describing ourselves */
254 tmp1 = expand_string(ob->server_service);
255 tmp2 = expand_string(ob->server_hostname);
256 ex_server_str = string_sprintf("%s@%s", tmp1, tmp2);
257 gbufdesc.value = (void *) ex_server_str;
258 gbufdesc.length = Ustrlen(ex_server_str);
259 maj_stat = gss_import_name(&min_stat,
260 &gbufdesc, GSS_C_NT_HOSTBASED_SERVICE, &gserver);
261 if (GSS_ERROR(maj_stat))
262 return exim_gssapi_error_defer(store_reset_point, maj_stat, min_stat,
263 "gss_import_name(%s)", CS gbufdesc.value);
265 /* Use a specific keytab, if specified */
266 if (ob->server_keytab)
268 keytab = expand_string(ob->server_keytab);
269 maj_stat = gsskrb5_register_acceptor_identity(CCS keytab);
270 if (GSS_ERROR(maj_stat))
271 return exim_gssapi_error_defer(store_reset_point, maj_stat, min_stat,
272 "registering keytab \"%s\"", keytab);
274 debug_printf("heimdal: using keytab \"%s\"\n", keytab);
277 /* Acquire our credentials */
278 maj_stat = gss_acquire_cred(&min_stat,
279 gserver, /* desired name */
281 GSS_C_NULL_OID_SET, /* desired mechs */
282 GSS_C_ACCEPT, /* cred usage */
284 NULL /* actual mechs */,
285 NULL /* time rec */);
286 if (GSS_ERROR(maj_stat))
287 return exim_gssapi_error_defer(store_reset_point, maj_stat, min_stat,
288 "gss_acquire_cred(%s)", ex_server_str);
290 maj_stat = gss_release_name(&min_stat, &gserver);
292 HDEBUG(D_auth) debug_printf("heimdal: have server credentials.\n");
294 /* Loop talking to client */
296 from_client = initial_data;
297 handled_empty_ir = FALSE;
300 /* buffer sizes: auth_get_data() uses big_buffer, which we grow per
301 GSSAPI RFC in _init, if needed, to meet the SHOULD size of 64KB.
302 (big_buffer starts life at the MUST size of 16KB). */
305 0: getting initial data from client to feed into GSSAPI
306 1: iterating for as long as GSS_S_CONTINUE_NEEDED
307 2: GSS_S_COMPLETE, SASL wrapping for authz and qop to send to client
308 3: unpick final auth message from client
309 4: break/finish (non-step)
315 if (!from_client || !*from_client)
317 if (handled_empty_ir)
319 HDEBUG(D_auth) debug_printf("gssapi: repeated empty input, grr.\n");
324 HDEBUG(D_auth) debug_printf("gssapi: missing initial response, nudging.\n");
325 if ((error_out = auth_get_data(&from_client, US"", 0)) != OK)
327 handled_empty_ir = TRUE;
330 /* We should now have the opening data from the client, base64-encoded. */
332 HDEBUG(D_auth) debug_printf("heimdal: have initial client data\n");
336 gbufdesc_in.length = b64decode(from_client, USS &gbufdesc_in.value);
339 maj_stat = gss_release_name(&min_stat, &gclient);
340 gclient = GSS_C_NO_NAME;
342 maj_stat = gss_accept_sec_context(&min_stat,
343 &gcontext, /* context handle */
344 gcred, /* acceptor cred handle */
345 &gbufdesc_in, /* input from client */
346 GSS_C_NO_CHANNEL_BINDINGS, /* XXX fixme: use the channel bindings from GnuTLS */
347 &gclient, /* client identifier */
348 &mech_type, /* mechanism in use */
349 &gbufdesc_out, /* output to send to client */
350 NULL, /* return flags */
352 NULL /* delegated cred_handle */
354 if (GSS_ERROR(maj_stat))
356 exim_gssapi_error_defer(NULL, maj_stat, min_stat,
357 "gss_accept_sec_context()");
361 if (gbufdesc_out.length != 0)
363 error_out = auth_get_data(&from_client,
364 gbufdesc_out.value, gbufdesc_out.length);
368 gss_release_buffer(&min_stat, &gbufdesc_out);
369 EmptyBuf(gbufdesc_out);
371 if (maj_stat == GSS_S_COMPLETE)
374 HDEBUG(D_auth) debug_printf("heimdal: GSS complete\n");
377 HDEBUG(D_auth) debug_printf("heimdal: need more data\n");
381 memset(sasl_config, 0xFF, 4);
382 /* draft-ietf-sasl-gssapi-06.txt defines bitmasks for first octet
383 0x01 No security layer
384 0x02 Integrity protection
385 0x04 Confidentiality protection
387 The remaining three octets are the maximum buffer size for wrapped
389 sasl_config[0] = 0x01; /* Exim does not wrap/unwrap SASL layers after auth */
390 gbufdesc.value = (void *) sasl_config;
392 maj_stat = gss_wrap(&min_stat,
394 0, /* conf_req_flag: integrity only */
395 GSS_C_QOP_DEFAULT, /* qop requested */
396 &gbufdesc, /* message to protect */
397 NULL, /* conf_state: no confidentiality applied */
398 &gbufdesc_out /* output buffer */
400 if (GSS_ERROR(maj_stat))
402 exim_gssapi_error_defer(NULL, maj_stat, min_stat,
403 "gss_wrap(SASL state after auth)");
408 HDEBUG(D_auth) debug_printf("heimdal SASL: requesting QOP with no security layers\n");
410 error_out = auth_get_data(&from_client,
411 gbufdesc_out.value, gbufdesc_out.length);
415 gss_release_buffer(&min_stat, &gbufdesc_out);
416 EmptyBuf(gbufdesc_out);
421 gbufdesc_in.length = b64decode(from_client, USS &gbufdesc_in.value);
422 maj_stat = gss_unwrap(&min_stat,
424 &gbufdesc_in, /* data from client */
425 &gbufdesc_out, /* results */
426 NULL, /* conf state */
429 if (GSS_ERROR(maj_stat))
431 exim_gssapi_error_defer(NULL, maj_stat, min_stat,
432 "gss_unwrap(final SASL message from client)");
436 if (gbufdesc_out.length < 4)
439 debug_printf("gssapi: final message too short; "
440 "need flags, buf sizes and optional authzid\n");
445 requested_qop = (CS gbufdesc_out.value)[0];
446 if (!(requested_qop & 0x01))
449 debug_printf("gssapi: client requested security layers (%x)\n",
450 (unsigned int) requested_qop);
455 for (int i = 0; i < AUTH_VARS; i++) auth_vars[i] = NULL;
459 The SASL provided identifier is an unverified authzid.
460 GSSAPI provides us with a verified identifier, but it might be empty
464 /* $auth2 is authzid requested at SASL layer */
465 if (gbufdesc_out.length > 4)
467 expand_nlength[2] = gbufdesc_out.length - 4;
468 auth_vars[1] = expand_nstring[2] =
469 string_copyn((US gbufdesc_out.value) + 4, expand_nlength[2]);
473 gss_release_buffer(&min_stat, &gbufdesc_out);
474 EmptyBuf(gbufdesc_out);
476 /* $auth1 is GSSAPI display name */
477 maj_stat = gss_display_name(&min_stat,
478 gclient, &gbufdesc_out, &mech_type);
479 if (GSS_ERROR(maj_stat))
481 auth_vars[1] = expand_nstring[2] = NULL;
483 exim_gssapi_error_defer(NULL, maj_stat, min_stat,
484 "gss_display_name(client identifier)");
489 expand_nlength[1] = gbufdesc_out.length;
490 auth_vars[0] = expand_nstring[1] =
491 string_copyn(gbufdesc_out.value, gbufdesc_out.length);
493 if (expand_nmax == 0) /* should be: authzid was empty */
496 expand_nlength[2] = expand_nlength[1];
497 auth_vars[1] = expand_nstring[2] = string_copyn(expand_nstring[1], expand_nlength[1]);
499 debug_printf("heimdal SASL: empty authzid, set to dup of GSSAPI display name\n");
503 debug_printf("heimdal SASL: happy with client request\n"
504 " auth1 (verified GSSAPI display-name): \"%s\"\n"
505 " auth2 (unverified SASL requested authzid): \"%s\"\n",
506 auth_vars[0], auth_vars[1]);
516 maj_stat = gss_release_cred(&min_stat, &gcred);
519 gss_release_name(&min_stat, &gclient);
520 gclient = GSS_C_NO_NAME;
522 if (gbufdesc_out.length)
524 gss_release_buffer(&min_stat, &gbufdesc_out);
525 EmptyBuf(gbufdesc_out);
527 if (gcontext != GSS_C_NO_CONTEXT)
528 gss_delete_sec_context(&min_stat, &gcontext, GSS_C_NO_BUFFER);
530 store_reset(store_reset_point);
535 /* Auth succeeded, check server_condition */
536 return auth_check_serv_cond(ablock);
541 exim_gssapi_error_defer(rmark store_reset_point,
542 OM_uint32 major, OM_uint32 minor,
543 const char *format, ...)
546 OM_uint32 maj_stat, min_stat;
547 OM_uint32 msgcontext = 0;
548 gss_buffer_desc status_string;
553 va_start(ap, format);
554 g = string_vformat(NULL, SVFMT_EXTEND|SVFMT_REBUFFER, format, ap);
558 auth_defer_msg = NULL;
561 maj_stat = gss_display_status(&min_stat,
562 major, GSS_C_GSS_CODE, GSS_C_NO_OID, &msgcontext, &status_string);
565 auth_defer_msg = string_copy(US status_string.value);
567 HDEBUG(D_auth) debug_printf("heimdal %s: %.*s\n",
568 string_from_gstring(g), (int)status_string.length,
569 CS status_string.value);
570 gss_release_buffer(&min_stat, &status_string);
572 } while (msgcontext != 0);
574 if (store_reset_point)
575 store_reset(store_reset_point);
580 /*************************************************
581 * Client entry point *
582 *************************************************/
584 /* For interface, see auths/README */
587 auth_heimdal_gssapi_client(
588 auth_instance *ablock, /* authenticator block */
589 void * sx, /* connection */
590 int timeout, /* command timeout */
591 uschar *buffer, /* buffer for reading response */
592 int buffsize) /* size of buffer */
595 debug_printf("Client side NOT IMPLEMENTED: you should not see this!\n");
596 /* NOT IMPLEMENTED */
600 /*************************************************
602 *************************************************/
605 auth_heimdal_gssapi_version_report(FILE *f)
607 /* No build-time constants available unless we link against libraries at
608 build-time and export the result as a string into a header ourselves. */
609 fprintf(f, "Library version: Heimdal: Runtime: %s\n"
611 heimdal_version, heimdal_long_version);
614 #endif /*!MACRO_PREDEF*/
615 #endif /* AUTH_HEIMDAL_GSSAPI */
617 /* End of heimdal_gssapi.c */