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 */