First pass heimdal_gssapi authenticator.
[users/jgh/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 - 2012 */
6 /* See the file NOTICE for conditions of use and distribution. */
7
8 /* Copyright (c) Twitter Inc 2012
9    Author: Phil Pennock <pdp@exim.org> */
10
11 /* Interface to Heimdal SASL library for GSSAPI authentication. */
12
13 /* Naming and rationale
14
15 Sensibly, this integration would be deferred to a SASL library, but none
16 of them appear to offer keytab file selection interfaces in their APIs.  It
17 might be that this driver only requires minor modification to work with MIT
18 Kerberos.
19
20 Heimdal provides a number of interfaces for various forms of authentication.
21 As GS2 does not appear to provide keytab control interfaces either, we may
22 end up supporting that too.  It's possible that we could trivially expand to
23 support NTLM support via Heimdal, etc.  Rather than try to be too generic
24 immediately, this driver is directly only supporting GSSAPI.
25
26 Without rename, we could add an option for GS2 support in the future.
27 */
28
29 /* Sources
30
31 * mailcheck-imap (Perl, client-side, written by me years ago)
32 * gsasl driver (GPL, server-side)
33 * heimdal sources and man-pages, plus http://www.h5l.org/manual/
34 * FreeBSD man-pages (very informative!)
35 * http://www.ggf.org/documents/GFD.24.pdf confirming GSS_KRB5_REGISTER_ACCEPTOR_IDENTITY_X
36   semantics, that found by browsing Heimdal source to find how to set the keytab
37
38 */
39
40 #include "../exim.h"
41
42 #ifndef AUTH_HEIMDAL_GSSAPI
43 /* dummy function to satisfy compilers when we link in an "empty" file. */
44 static void dummy(int x) { dummy(x-1); }
45 #else
46
47 #include <gssapi/gssapi.h>
48 #include <gssapi/gssapi_krb5.h>
49
50 /* for the _init debugging */
51 #include <krb5.h>
52
53 /* Because __gss_krb5_register_acceptor_identity_x_oid_desc is internal */
54 #include <roken.h>
55
56 #include "heimdal_gssapi.h"
57
58 /* Authenticator-specific options. */
59 optionlist auth_heimdal_gssapi_options[] = {
60   { "server_hostname",      opt_stringptr,
61       (void *)(offsetof(auth_heimdal_gssapi_options_block, server_hostname)) },
62   { "server_keytab",        opt_stringptr,
63       (void *)(offsetof(auth_heimdal_gssapi_options_block, server_keytab)) },
64   { "server_realm",         opt_stringptr,
65       (void *)(offsetof(auth_heimdal_gssapi_options_block, server_realm)) },
66   { "server_service",       opt_stringptr,
67       (void *)(offsetof(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   NULL,                     /* server_realm */
78   US"smtp",                 /* server_service */
79 };
80
81 /* "Globals" for managing the heimdal_gssapi interface. */
82
83 /* hack around unavailable __gss_krb5_register_acceptor_identity_x_oid_desc
84 OID: 1.2.752.43.13.5
85 from heimdal lib/gssapi/krb5/external.c */
86 gss_OID_desc exim_register_keytab_OID = {6, rk_UNCONST("\x2a\x85\x70\x2b\x0d\x05")};
87
88 /* Utility functions */
89 static void
90   exim_heimdal_error_debug(const char *, krb5_context, krb5_error_code);
91 static int
92   exim_gssapi_error_defer(uschar *, OM_uint32, OM_uint32, const char *, ...)
93     PRINTF_FUNCTION(4, 5);
94
95 #define EmptyBuf(buf) do { buf.value = NULL; buf.length = 0; } while (0)
96
97
98 /*************************************************
99 *          Initialization entry point            *
100 *************************************************/
101
102 /* Called for each instance, after its options have been read, to
103 enable consistency checks to be done, or anything else that needs
104 to be set up. */
105
106 /* Heimdal provides a GSSAPI extension method (via an OID) for setting the
107 keytab; in the init, we mostly just use raw krb5 methods so that we can report
108 the keytab contents, for -D+auth debugging. */
109
110 void
111 auth_heimdal_gssapi_init(auth_instance *ablock)
112 {
113   krb5_context context;
114   krb5_keytab keytab;
115   krb5_kt_cursor cursor;
116   krb5_keytab_entry entry;
117   krb5_error_code krc;
118   char *principal, *enctype_s;
119   const char *k_keytab_typed_name = NULL;
120   auth_heimdal_gssapi_options_block *ob =
121     (auth_heimdal_gssapi_options_block *)(ablock->options_block);
122
123   ablock->server = FALSE;
124   ablock->client = FALSE;
125
126   if (!ob->server_service || !*ob->server_service) {
127     HDEBUG(D_auth) debug_printf("heimdal: missing server_service\n");
128     return;
129   }
130
131   krc = krb5_init_context(&context);
132   if (krc != 0) {
133     int kerr = errno;
134     HDEBUG(D_auth) debug_printf("heimdal: failed to initialise krb5 context: %s\n",
135         strerror(kerr));
136     return;
137   }
138
139   if (ob->server_keytab) {
140     k_keytab_typed_name = CCS string_sprintf("file:%s", expand_string(ob->server_keytab));
141     HDEBUG(D_auth) debug_printf("heimdal: using keytab %s\n", k_keytab_typed_name);
142     krc = krb5_kt_resolve(context, k_keytab_typed_name, &keytab);
143     if (krc) {
144       HDEBUG(D_auth) exim_heimdal_error_debug("krb5_kt_resolve", context, krc);
145       return;
146     }
147   } else {
148     HDEBUG(D_auth) debug_printf("heimdal: using system default keytab\n");
149     krc = krb5_kt_default(context, &keytab);
150     if (krc) {
151       HDEBUG(D_auth) exim_heimdal_error_debug("krb5_kt_default", context, krc);
152       return;
153     }
154   }
155
156   HDEBUG(D_auth) {
157     /* http://www.h5l.org/manual/HEAD/krb5/krb5_keytab_intro.html */
158     krc = krb5_kt_start_seq_get(context, keytab, &cursor);
159     if (krc)
160       exim_heimdal_error_debug("krb5_kt_start_seq_get", context, krc);
161     else {
162       while ((krc = krb5_kt_next_entry(context, keytab, &entry, &cursor)) == 0) {
163         principal = enctype_s = NULL;
164         krb5_unparse_name(context, entry.principal, &principal);
165         krb5_enctype_to_string(context, entry.keyblock.keytype, &enctype_s);
166         debug_printf("heimdal: keytab principal: %s  vno=%d  type=%s\n",
167             principal ? principal : "??",
168             entry.vno,
169             enctype_s ? enctype_s : "??");
170         free(principal);
171         free(enctype_s);
172         krb5_kt_free_entry(context, &entry);
173       }
174       krc = krb5_kt_end_seq_get(context, keytab, &cursor);
175       if (krc)
176         exim_heimdal_error_debug("krb5_kt_end_seq_get", context, krc);
177     }
178   }
179
180   krc = krb5_kt_close(context, keytab);
181   if (krc)
182     HDEBUG(D_auth) exim_heimdal_error_debug("krb5_kt_close", context, krc);
183
184   krb5_free_context(context);
185
186   /* RFC 4121 section 5.2, SHOULD support 64K input buffers */
187   if (big_buffer_size < (64 * 1024)) {
188     uschar *newbuf;
189     big_buffer_size = 64 * 1024;
190     newbuf = store_malloc(big_buffer_size);
191     store_free(big_buffer);
192     big_buffer = newbuf;
193   }
194
195   ablock->server = TRUE;
196 }
197
198
199 static void
200 exim_heimdal_error_debug(const char *label,
201     krb5_context context, krb5_error_code err)
202 {
203   const char *kerrsc;
204   kerrsc = krb5_get_error_message(context, err);
205   debug_printf("heimdal %s: %s\n", label, kerrsc ? kerrsc : "unknown error");
206   krb5_free_error_message(context, kerrsc);
207 }
208
209 /*************************************************
210 *             Server entry point                 *
211 *************************************************/
212
213 /* For interface, see auths/README */
214
215 /* GSSAPI notes:
216 OM_uint32: portable type for unsigned int32
217 gss_buffer_desc / *gss_buffer_t: hold/point-to size_t .length & void *value
218   -- all strings/etc passed in should go through one of these
219   -- when allocated by gssapi, release with gss_release_buffer()
220 */
221
222 int
223 auth_heimdal_gssapi_server(auth_instance *ablock, uschar *initial_data)
224 {
225   gss_name_t gclient = GSS_C_NO_NAME;
226   gss_name_t gserver = GSS_C_NO_NAME;
227   gss_cred_id_t gcred = GSS_C_NO_CREDENTIAL;
228   gss_ctx_id_t gcontext = GSS_C_NO_CONTEXT;
229   uschar *ex_server_str;
230   gss_buffer_desc gbufdesc = GSS_C_EMPTY_BUFFER;
231   gss_buffer_desc gbufdesc_in = GSS_C_EMPTY_BUFFER;
232   gss_buffer_desc gbufdesc_out = GSS_C_EMPTY_BUFFER;
233   gss_OID mech_type;
234   OM_uint32 maj_stat, min_stat;
235   int step, error_out, i;
236   uschar *tmp1, *tmp2, *from_client;
237   auth_heimdal_gssapi_options_block *ob =
238     (auth_heimdal_gssapi_options_block *)(ablock->options_block);
239   BOOL handled_empty_ir;
240   uschar *store_reset_point;
241   uschar sasl_config[4];
242   uschar requested_qop;
243
244   store_reset_point = store_get(0);
245
246   HDEBUG(D_auth)
247     debug_printf("heimdal: initialising auth context for %s\n", ablock->name);
248
249   /* Construct our gss_name_t gserver describing ourselves */
250   tmp1 = expand_string(ob->server_service);
251   tmp2 = expand_string(ob->server_hostname);
252   ex_server_str = string_sprintf("%s@%s", tmp1, tmp2);
253   gbufdesc.value = (void *) ex_server_str;
254   gbufdesc.length = Ustrlen(ex_server_str);
255   maj_stat = gss_import_name(&min_stat,
256       &gbufdesc, GSS_C_NT_HOSTBASED_SERVICE, &gserver);
257   if (GSS_ERROR(maj_stat))
258     return exim_gssapi_error_defer(store_reset_point, maj_stat, min_stat,
259         "gss_import_name(%s)", CS gbufdesc.value);
260
261   /* Use a specific keytab, if specified */
262   if (ob->server_keytab) {
263     gbufdesc.value = (void *) string_sprintf("file:%s", expand_string(ob->server_keytab));
264     gbufdesc.length = strlen(CS gbufdesc.value);
265     maj_stat = gss_set_sec_context_option(&min_stat,
266         &gcontext,                  /* create new security context */
267         &exim_register_keytab_OID,  /* GSS_KRB5_REGISTER_ACCEPTOR_IDENTITY_X */
268         &gbufdesc);
269     if (GSS_ERROR(maj_stat))
270       return exim_gssapi_error_defer(store_reset_point, maj_stat, min_stat,
271           "registering keytab \"%s\"", CS gbufdesc.value);
272   }
273
274   /* Acquire our credentials */
275   maj_stat = gss_acquire_cred(&min_stat,
276       gserver,             /* desired name */
277       0,                   /* time */
278       GSS_C_NULL_OID_SET,  /* desired mechs */
279       GSS_C_ACCEPT,        /* cred usage */
280       &gcred,              /* handle */
281       NULL                 /* actual mechs */,
282       NULL                 /* time rec */);
283   if (GSS_ERROR(maj_stat))
284     return exim_gssapi_error_defer(store_reset_point, maj_stat, min_stat,
285         "gss_acquire_cred(%s)", ex_server_str);
286
287   maj_stat = gss_release_name(&min_stat, &gserver);
288
289   /* Loop talking to client */
290   step = 0;
291   from_client = initial_data;
292   handled_empty_ir = FALSE;
293   error_out = OK;
294
295   /* buffer sizes: auth_get_data() uses big_buffer, which we grow per
296   GSSAPI RFC in _init, if needed, to meet the SHOULD size of 64KB.
297   (big_buffer starts life at the MUST size of 16KB). */
298
299   /* step values
300   0: getting initial data from client to feed into GSSAPI
301   1: iterating for as long as GSS_S_CONTINUE_NEEDED
302   2: GSS_S_COMPLETE, SASL wrapping for authz and qop to send to client
303   3: unpick final auth message from client
304   4: break/finish (non-step)
305   */
306   while (step < 4) {
307     switch (step) {
308       case 0:
309         if (!from_client || *from_client == '\0') {
310           if (handled_empty_ir) {
311             HDEBUG(D_auth) debug_printf("gssapi: repeated empty input, grr.\n");
312             error_out = BAD64;
313             goto ERROR_OUT;
314           } else {
315             HDEBUG(D_auth) debug_printf("gssapi: missing initial response, nudging.\n");
316             error_out = auth_get_data(&from_client, US"", 0);
317             if (error_out != OK)
318               goto ERROR_OUT;
319             continue;
320           }
321         }
322         /* We should now have the opening data from the client, base64-encoded. */
323         step += 1;
324         break;
325
326       case 1:
327         gbufdesc_in.length = auth_b64decode(from_client, USS &gbufdesc_in.value);
328         if (gclient) {
329           maj_stat = gss_release_name(&min_stat, &gclient);
330           gclient = GSS_C_NO_NAME;
331         }
332         maj_stat = gss_accept_sec_context(&min_stat,
333             &gcontext,          /* context handle */
334             gcred,              /* acceptor cred handle */
335             &gbufdesc_in,       /* input from client */
336             GSS_C_NO_CHANNEL_BINDINGS,  /* XXX fixme: use the channel bindings from GnuTLS */
337             &gclient,           /* client identifier */
338             &mech_type,         /* mechanism in use */
339             &gbufdesc_out,      /* output to send to client */
340             NULL,               /* return flags */
341             NULL,               /* time rec */
342             NULL                /* delegated cred_handle */
343             );
344         if (GSS_ERROR(maj_stat)) {
345           exim_gssapi_error_defer(NULL, maj_stat, min_stat,
346               "gss_accept_sec_context()");
347           error_out = FAIL;
348           goto ERROR_OUT;
349         }
350         if (&gbufdesc_out.length != 0) {
351           error_out = auth_get_data(&from_client,
352               gbufdesc_out.value, gbufdesc_out.length);
353           if (error_out != OK)
354             goto ERROR_OUT;
355
356           gss_release_buffer(&min_stat, &gbufdesc_out);
357           EmptyBuf(gbufdesc_out);
358         }
359         if (maj_stat == GSS_S_COMPLETE)
360           step += 1;
361         break;
362
363       case 2:
364         memset(sasl_config, 0xFF, 4);
365         /* draft-ietf-sasl-gssapi-06.txt defines bitmasks for first octet
366         0x01 No security layer
367         0x02 Integrity protection
368         0x04 Confidentiality protection
369
370         The remaining three octets are the maximum buffer size for wrappe
371         content. */
372         sasl_config[0] = 0x01;  /* Exim does not wrap/unwrap SASL layers after auth */
373         gbufdesc.value = (void *) sasl_config;
374         gbufdesc.length = 4;
375         maj_stat = gss_wrap(&min_stat,
376             gcontext,
377             0,                    /* conf_req_flag: integrity only */
378             GSS_C_QOP_DEFAULT,    /* qop requested */
379             &gbufdesc,            /* message to protect */
380             NULL,                 /* conf_state: no confidentiality applied */
381             &gbufdesc_out         /* output buffer */
382             );
383         if (GSS_ERROR(maj_stat)) {
384           exim_gssapi_error_defer(NULL, maj_stat, min_stat,
385               "gss_wrap(SASL state after auth)");
386           error_out = FAIL;
387           goto ERROR_OUT;
388         }
389         error_out = auth_get_data(&from_client,
390             gbufdesc_out.value, gbufdesc_out.length);
391         if (error_out != OK)
392           goto ERROR_OUT;
393
394         gss_release_buffer(&min_stat, &gbufdesc_out);
395         EmptyBuf(gbufdesc_out);
396         step += 1;
397         break;
398
399       case 3:
400         gbufdesc_in.length = auth_b64decode(from_client, USS &gbufdesc_in.value);
401         maj_stat = gss_unwrap(&min_stat,
402             gcontext,
403             &gbufdesc_in,       /* data from client */
404             &gbufdesc_out,      /* results */
405             NULL,               /* conf state */
406             NULL                /* qop state */
407             );
408         if (GSS_ERROR(maj_stat)) {
409           exim_gssapi_error_defer(NULL, maj_stat, min_stat,
410               "gss_unwrap(final SASL message from client)");
411           error_out = FAIL;
412           goto ERROR_OUT;
413         }
414         if (gbufdesc_out.length < 5) {
415           HDEBUG(D_auth)
416             debug_printf("gssapi: final message too short; "
417                 "need flags, buf sizes and authzid\n");
418           error_out = FAIL;
419           goto ERROR_OUT;
420         }
421
422         requested_qop = (CS gbufdesc_out.value)[0];
423         if ((requested_qop & 0x01) == 0) {
424           HDEBUG(D_auth)
425             debug_printf("gssapi: client requested security layers (%x)\n",
426                 (unsigned int) requested_qop);
427           error_out = FAIL;
428           goto ERROR_OUT;
429         }
430
431         for (i = 0; i < AUTH_VARS; i++) auth_vars[i] = NULL;
432         expand_nmax = 0;
433
434         /* Identifiers:
435         The SASL provided identifier is an unverified authzid.
436         GSSAPI provides us with a verified identifier.
437         */
438
439         /* $auth2 is authzid requested at SASL layer */
440         expand_nlength[2] = gbufdesc_out.length - 4;
441         auth_vars[1] = expand_nstring[2] =
442           string_copyn((US gbufdesc_out.value) + 4, expand_nlength[2]);
443         expand_nmax = 2;
444
445         gss_release_buffer(&min_stat, &gbufdesc_out);
446         EmptyBuf(gbufdesc_out);
447
448         /* $auth1 is GSSAPI display name */
449         maj_stat = gss_display_name(&min_stat,
450             gclient,
451             &gbufdesc_out,
452             &mech_type);
453         if (GSS_ERROR(maj_stat)) {
454           auth_vars[1] = expand_nstring[2] = NULL;
455           expand_nmax = 0;
456           exim_gssapi_error_defer(NULL, maj_stat, min_stat,
457               "gss_display_name(client identifier)");
458           error_out = FAIL;
459           goto ERROR_OUT;
460         }
461
462         expand_nlength[1] = gbufdesc_out.length;
463         auth_vars[0] = expand_nstring[1] =
464           string_copyn(gbufdesc_out.value, gbufdesc_out.length);
465
466         step += 1;
467         break;
468
469     } /* switch */
470   } /* while step */
471
472
473 ERROR_OUT:
474   maj_stat = gss_release_cred(&min_stat, &gcred);
475   if (gclient) {
476     gss_release_name(&min_stat, &gclient);
477     gclient = GSS_C_NO_NAME;
478   }
479   if (gbufdesc_out.length) {
480     gss_release_buffer(&min_stat, &gbufdesc_out);
481     EmptyBuf(gbufdesc_out);
482   }
483   if (gcontext != GSS_C_NO_CONTEXT) {
484     gss_delete_sec_context(&min_stat, &gcontext, GSS_C_NO_BUFFER);
485   }
486
487   store_reset(store_reset_point);
488
489   if (error_out != OK)
490     return error_out;
491
492   /* Auth succeeded, check server_condition */
493   return auth_check_serv_cond(ablock);
494 }
495
496
497 static int
498 exim_gssapi_error_defer(uschar *store_reset_point,
499     OM_uint32 major, OM_uint32 minor,
500     const char *format, ...)
501 {
502   va_list ap;
503   uschar buffer[STRING_SPRINTF_BUFFER_SIZE];
504   OM_uint32 maj_stat, min_stat;
505   OM_uint32 msgcontext = 0;
506   gss_buffer_desc status_string;
507
508   va_start(ap, format);
509   if (!string_vformat(buffer, sizeof(buffer), format, ap))
510     log_write(0, LOG_MAIN|LOG_PANIC_DIE,
511         "exim_gssapi_error_defer expansion larger than %d",
512         sizeof(buffer));
513   va_end(ap);
514
515   auth_defer_msg = NULL;
516
517   do {
518     maj_stat = gss_display_status(&min_stat,
519         major, GSS_C_GSS_CODE, GSS_C_NO_OID,
520         &msgcontext, &status_string);
521
522     if (auth_defer_msg == NULL) {
523       auth_defer_msg = string_copy(US status_string.value);
524     }
525
526     HDEBUG(D_auth) debug_printf("heimdal %s: %.*s\n",
527         buffer, (int)status_string.length, CS status_string.value);
528     gss_release_buffer(&min_stat, &status_string);
529
530   } while (msgcontext != 0);
531
532   if (store_reset_point)
533     store_reset(store_reset_point);
534   return DEFER;
535 }
536
537
538 /*************************************************
539 *              Client entry point                *
540 *************************************************/
541
542 /* For interface, see auths/README */
543
544 int
545 auth_heimdal_gssapi_client(
546   auth_instance *ablock,                 /* authenticator block */
547   smtp_inblock *inblock,                 /* connection inblock */
548   smtp_outblock *outblock,               /* connection outblock */
549   int timeout,                           /* command timeout */
550   uschar *buffer,                        /* buffer for reading response */
551   int buffsize)                          /* size of buffer */
552 {
553   HDEBUG(D_auth)
554     debug_printf("Client side NOT IMPLEMENTED: you should not see this!\n");
555   /* NOT IMPLEMENTED */
556   return FAIL;
557 }
558
559 /*************************************************
560 *                Diagnostic API                  *
561 *************************************************/
562
563 void
564 auth_heimdal_gssapi_version_report(FILE *f)
565 {
566   /* No build-time constants available unless we link against libraries at
567   build-time and export the result as a string into a header ourselves. */
568   fprintf(f, "Library version: Heimdal: Runtime: %s\n"
569              " Build Info: %s\n",
570           heimdal_version, heimdal_long_version);
571 }
572
573 #endif  /* AUTH_HEIMDAL_GSSAPI */
574
575 /* End of heimdal_gssapi.c */