Docs: Fix various typos (Closes 2650, 2651)
[exim.git] / src / src / auths / heimdal_gssapi.c
1 /*************************************************
2 *     Exim - an Internet mail transport agent    *
3 *************************************************/
4
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. */
8
9 /* Copyright (c) Twitter Inc 2012
10    Author: Phil Pennock <pdp@exim.org> */
11 /* Copyright (c) Phil Pennock 2012 */
12
13 /* Interface to Heimdal library for GSSAPI authentication. */
14
15 /* Naming and rationale
16
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
20 Kerberos.
21
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.
27
28 Without rename, we could add an option for GS2 support in the future.
29 */
30
31 /* Sources
32
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().
41 */
42
43 #include "../exim.h"
44
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); }
50 #else
51
52 #include <gssapi/gssapi.h>
53 #include <gssapi/gssapi_krb5.h>
54
55 /* for the _init debugging */
56 #include <krb5.h>
57
58 #include "heimdal_gssapi.h"
59
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) }
68 };
69
70 int auth_heimdal_gssapi_options_count =
71   sizeof(auth_heimdal_gssapi_options)/sizeof(optionlist);
72
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 */
78 };
79
80
81 #ifdef MACRO_PREDEF
82
83 /* Dummy values */
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) {}
89
90 #else   /*!MACRO_PREDEF*/
91
92
93
94 /* "Globals" for managing the heimdal_gssapi interface. */
95
96 /* Utility functions */
97 static void
98   exim_heimdal_error_debug(const char *, krb5_context, krb5_error_code);
99 static int
100   exim_gssapi_error_defer(rmark, OM_uint32, OM_uint32, const char *, ...)
101     PRINTF_FUNCTION(4, 5);
102
103 #define EmptyBuf(buf) do { buf.value = NULL; buf.length = 0; } while (0)
104
105
106 /*************************************************
107 *          Initialization entry point            *
108 *************************************************/
109
110 /* Called for each instance, after its options have been read, to
111 enable consistency checks to be done, or anything else that needs
112 to be set up. */
113
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. */
117
118 void
119 auth_heimdal_gssapi_init(auth_instance *ablock)
120 {
121 krb5_context context;
122 krb5_keytab keytab;
123 krb5_kt_cursor cursor;
124 krb5_keytab_entry entry;
125 krb5_error_code krc;
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);
130
131 ablock->server = FALSE;
132 ablock->client = FALSE;
133
134 if (!ob->server_service || !*ob->server_service)
135   {
136   HDEBUG(D_auth) debug_printf("heimdal: missing server_service\n");
137   return;
138   }
139
140 if ((krc = krb5_init_context(&context)))
141   {
142   int kerr = errno;
143   HDEBUG(D_auth) debug_printf("heimdal: failed to initialise krb5 context: %s\n",
144       strerror(kerr));
145   return;
146   }
147
148 if (ob->server_keytab)
149   {
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)))
153     {
154     HDEBUG(D_auth) exim_heimdal_error_debug("krb5_kt_resolve", context, krc);
155     return;
156     }
157   }
158 else
159  {
160   HDEBUG(D_auth) debug_printf("heimdal: using system default keytab\n");
161   if ((krc = krb5_kt_default(context, &keytab)))
162     {
163     HDEBUG(D_auth) exim_heimdal_error_debug("krb5_kt_default", context, krc);
164     return;
165     }
166   }
167
168 HDEBUG(D_auth)
169   {
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);
173   else
174     {
175     while (!(krc = krb5_kt_next_entry(context, keytab, &entry, &cursor)))
176       {
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 : "??",
182           entry.vno,
183           enctype_s ? enctype_s : "??");
184       free(principal);
185       free(enctype_s);
186       krb5_kt_free_entry(context, &entry);
187       }
188     if ((krc = krb5_kt_end_seq_get(context, keytab, &cursor)))
189       exim_heimdal_error_debug("krb5_kt_end_seq_get", context, krc);
190     }
191   }
192
193 if ((krc = krb5_kt_close(context, keytab)))
194   HDEBUG(D_auth) exim_heimdal_error_debug("krb5_kt_close", context, krc);
195
196 krb5_free_context(context);
197
198 ablock->server = TRUE;
199 }
200
201
202 static void
203 exim_heimdal_error_debug(const char *label,
204     krb5_context context, krb5_error_code err)
205 {
206 const char *kerrsc;
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);
210 }
211
212 /*************************************************
213 *             Server entry point                 *
214 *************************************************/
215
216 /* For interface, see auths/README */
217
218 /* GSSAPI notes:
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()
223 */
224
225 int
226 auth_heimdal_gssapi_server(auth_instance *ablock, uschar *initial_data)
227 {
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;
236 gss_OID mech_type;
237 OM_uint32 maj_stat, min_stat;
238 int step, error_out;
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;
244 uschar *keytab;
245 uschar sasl_config[4];
246 uschar requested_qop;
247
248 store_reset_point = store_mark();
249
250 HDEBUG(D_auth)
251   debug_printf("heimdal: initialising auth context for %s\n", ablock->name);
252
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);
264
265 /* Use a specific keytab, if specified */
266 if (ob->server_keytab) 
267   {
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);
273   HDEBUG(D_auth)
274     debug_printf("heimdal: using keytab \"%s\"\n", keytab);
275   }
276
277 /* Acquire our credentials */
278 maj_stat = gss_acquire_cred(&min_stat,
279     gserver,             /* desired name */
280     0,                   /* time */
281     GSS_C_NULL_OID_SET,  /* desired mechs */
282     GSS_C_ACCEPT,        /* cred usage */
283     &gcred,              /* handle */
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);
289
290 maj_stat = gss_release_name(&min_stat, &gserver);
291
292 HDEBUG(D_auth) debug_printf("heimdal: have server credentials.\n");
293
294 /* Loop talking to client */
295 step = 0;
296 from_client = initial_data;
297 handled_empty_ir = FALSE;
298 error_out = OK;
299
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). */
303
304 /* step values
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)
310 */
311 while (step < 4)
312   switch (step)
313     {
314     case 0:
315       if (!from_client || !*from_client)
316         {
317         if (handled_empty_ir)
318           {
319           HDEBUG(D_auth) debug_printf("gssapi: repeated empty input, grr.\n");
320           error_out = BAD64;
321           goto ERROR_OUT;
322           }
323
324         HDEBUG(D_auth) debug_printf("gssapi: missing initial response, nudging.\n");
325         if ((error_out = auth_get_data(&from_client, US"", 0)) != OK)
326           goto ERROR_OUT;
327         handled_empty_ir = TRUE;
328         continue;
329         }
330       /* We should now have the opening data from the client, base64-encoded. */
331       step += 1;
332       HDEBUG(D_auth) debug_printf("heimdal: have initial client data\n");
333       break;
334
335     case 1:
336       gbufdesc_in.length = b64decode(from_client, USS &gbufdesc_in.value);
337       if (gclient)
338         {
339         maj_stat = gss_release_name(&min_stat, &gclient);
340         gclient = GSS_C_NO_NAME;
341         }
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 */
351           NULL,               /* time rec */
352           NULL                /* delegated cred_handle */
353           );
354       if (GSS_ERROR(maj_stat))
355         {
356         exim_gssapi_error_defer(NULL, maj_stat, min_stat,
357             "gss_accept_sec_context()");
358         error_out = FAIL;
359         goto ERROR_OUT;
360         }
361       if (gbufdesc_out.length != 0)
362         {
363         error_out = auth_get_data(&from_client,
364             gbufdesc_out.value, gbufdesc_out.length);
365         if (error_out != OK)
366           goto ERROR_OUT;
367
368         gss_release_buffer(&min_stat, &gbufdesc_out);
369         EmptyBuf(gbufdesc_out);
370         }
371       if (maj_stat == GSS_S_COMPLETE)
372         {
373         step += 1;
374         HDEBUG(D_auth) debug_printf("heimdal: GSS complete\n");
375         }
376       else
377         HDEBUG(D_auth) debug_printf("heimdal: need more data\n");
378       break;
379
380     case 2:
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
386
387       The remaining three octets are the maximum buffer size for wrapped
388       content. */
389       sasl_config[0] = 0x01;  /* Exim does not wrap/unwrap SASL layers after auth */
390       gbufdesc.value = (void *) sasl_config;
391       gbufdesc.length = 4;
392       maj_stat = gss_wrap(&min_stat,
393           gcontext,
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 */
399           );
400       if (GSS_ERROR(maj_stat))
401         {
402         exim_gssapi_error_defer(NULL, maj_stat, min_stat,
403             "gss_wrap(SASL state after auth)");
404         error_out = FAIL;
405         goto ERROR_OUT;
406         }
407
408       HDEBUG(D_auth) debug_printf("heimdal SASL: requesting QOP with no security layers\n");
409
410       error_out = auth_get_data(&from_client,
411           gbufdesc_out.value, gbufdesc_out.length);
412       if (error_out != OK)
413         goto ERROR_OUT;
414
415       gss_release_buffer(&min_stat, &gbufdesc_out);
416       EmptyBuf(gbufdesc_out);
417       step += 1;
418       break;
419
420     case 3:
421       gbufdesc_in.length = b64decode(from_client, USS &gbufdesc_in.value);
422       maj_stat = gss_unwrap(&min_stat,
423           gcontext,
424           &gbufdesc_in,       /* data from client */
425           &gbufdesc_out,      /* results */
426           NULL,               /* conf state */
427           NULL                /* qop state */
428           );
429       if (GSS_ERROR(maj_stat))
430         {
431         exim_gssapi_error_defer(NULL, maj_stat, min_stat,
432             "gss_unwrap(final SASL message from client)");
433         error_out = FAIL;
434         goto ERROR_OUT;
435         }
436       if (gbufdesc_out.length < 4)
437         {
438         HDEBUG(D_auth)
439           debug_printf("gssapi: final message too short; "
440               "need flags, buf sizes and optional authzid\n");
441         error_out = FAIL;
442         goto ERROR_OUT;
443         }
444
445       requested_qop = (CS gbufdesc_out.value)[0];
446       if (!(requested_qop & 0x01))
447         {
448         HDEBUG(D_auth)
449           debug_printf("gssapi: client requested security layers (%x)\n",
450               (unsigned int) requested_qop);
451         error_out = FAIL;
452         goto ERROR_OUT;
453         }
454
455       for (int i = 0; i < AUTH_VARS; i++) auth_vars[i] = NULL;
456       expand_nmax = 0;
457
458       /* Identifiers:
459       The SASL provided identifier is an unverified authzid.
460       GSSAPI provides us with a verified identifier, but it might be empty
461       for some clients.
462       */
463
464       /* $auth2 is authzid requested at SASL layer */
465       if (gbufdesc_out.length > 4)
466         {
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]);
470         expand_nmax = 2;
471         }
472
473       gss_release_buffer(&min_stat, &gbufdesc_out);
474       EmptyBuf(gbufdesc_out);
475
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))
480         {
481         auth_vars[1] = expand_nstring[2] = NULL;
482         expand_nmax = 0;
483         exim_gssapi_error_defer(NULL, maj_stat, min_stat,
484             "gss_display_name(client identifier)");
485         error_out = FAIL;
486         goto ERROR_OUT;
487         }
488
489       expand_nlength[1] = gbufdesc_out.length;
490       auth_vars[0] = expand_nstring[1] =
491         string_copyn(gbufdesc_out.value, gbufdesc_out.length);
492
493       if (expand_nmax == 0)     /* should be: authzid was empty */
494         {
495         expand_nmax = 2;
496         expand_nlength[2] = expand_nlength[1];
497         auth_vars[1] = expand_nstring[2] = string_copyn(expand_nstring[1], expand_nlength[1]);
498         HDEBUG(D_auth)
499           debug_printf("heimdal SASL: empty authzid, set to dup of GSSAPI display name\n");
500         }
501
502       HDEBUG(D_auth)
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]);
507
508       step += 1;
509       break;
510
511     } /* switch */
512   /* while step */
513
514
515 ERROR_OUT:
516 maj_stat = gss_release_cred(&min_stat, &gcred);
517 if (gclient)
518   {
519   gss_release_name(&min_stat, &gclient);
520   gclient = GSS_C_NO_NAME;
521   }
522 if (gbufdesc_out.length)
523   {
524   gss_release_buffer(&min_stat, &gbufdesc_out);
525   EmptyBuf(gbufdesc_out);
526   }
527 if (gcontext != GSS_C_NO_CONTEXT)
528   gss_delete_sec_context(&min_stat, &gcontext, GSS_C_NO_BUFFER);
529
530 store_reset(store_reset_point);
531
532 if (error_out != OK)
533   return error_out;
534
535 /* Auth succeeded, check server_condition */
536 return auth_check_serv_cond(ablock);
537 }
538
539
540 static int
541 exim_gssapi_error_defer(rmark store_reset_point,
542     OM_uint32 major, OM_uint32 minor,
543     const char *format, ...)
544 {
545 va_list ap;
546 OM_uint32 maj_stat, min_stat;
547 OM_uint32 msgcontext = 0;
548 gss_buffer_desc status_string;
549 gstring * g;
550
551 HDEBUG(D_auth)
552   {
553   va_start(ap, format);
554   g = string_vformat(NULL, SVFMT_EXTEND|SVFMT_REBUFFER, format, ap);
555   va_end(ap);
556   }
557
558 auth_defer_msg = NULL;
559
560 do {
561   maj_stat = gss_display_status(&min_stat,
562       major, GSS_C_GSS_CODE, GSS_C_NO_OID, &msgcontext, &status_string);
563
564   if (!auth_defer_msg)
565     auth_defer_msg = string_copy(US status_string.value);
566
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);
571
572   } while (msgcontext != 0);
573
574 if (store_reset_point)
575   store_reset(store_reset_point);
576 return DEFER;
577 }
578
579
580 /*************************************************
581 *              Client entry point                *
582 *************************************************/
583
584 /* For interface, see auths/README */
585
586 int
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 */
593 {
594 HDEBUG(D_auth)
595   debug_printf("Client side NOT IMPLEMENTED: you should not see this!\n");
596 /* NOT IMPLEMENTED */
597 return FAIL;
598 }
599
600 /*************************************************
601 *                Diagnostic API                  *
602 *************************************************/
603
604 void
605 auth_heimdal_gssapi_version_report(FILE *f)
606 {
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"
610            " Build Info: %s\n",
611         heimdal_version, heimdal_long_version);
612 }
613
614 #endif   /*!MACRO_PREDEF*/
615 #endif  /* AUTH_HEIMDAL_GSSAPI */
616
617 /* End of heimdal_gssapi.c */