rkerberos 0.2.3 → 0.3.1

data/ext/rkerberos/rkerberos.c

@@ -25,6 +25,13 @@ VALUE rb_hash_aref2(VALUE v_hash, VALUE v_key){
 
 
 // TypedData functions for RUBY_KRB5
+static void rkrb5_typed_mark(void *ptr) {
+  if (!ptr) return;
+  RUBY_KRB5 *r = (RUBY_KRB5 *)ptr;
+  if (r->rb_context != Qnil)
+    rb_gc_mark(r->rb_context);
+}
+
 static void rkrb5_typed_free(void *ptr) {
   if (!ptr) return;
   RUBY_KRB5 *r = (RUBY_KRB5 *)ptr;
@@ -34,8 +41,10 @@ static void rkrb5_typed_free(void *ptr) {
     krb5_free_cred_contents(r->ctx, &r->creds);
   if (r->princ)
     krb5_free_principal(r->ctx, r->princ);
-  if (r->ctx)
+  if (r->ctx && r->rb_context == Qnil)
     krb5_free_context(r->ctx);
+  else if (r->rb_context != Qnil)
+    rkrb5_context_release(r->rb_context);
   free(r);
 }
 
@@ -43,9 +52,9 @@ static size_t rkrb5_typed_size(const void *ptr) {
   return sizeof(RUBY_KRB5);
 }
 
-static const rb_data_type_t rkrb5_data_type = {
+const rb_data_type_t rkrb5_data_type = {
   "RUBY_KRB5",
-  {NULL, rkrb5_typed_free, rkrb5_typed_size,},
+  {rkrb5_typed_mark, rkrb5_typed_free, rkrb5_typed_size,},
   NULL, NULL, RUBY_TYPED_FREE_IMMEDIATELY
 };
 
@@ -53,26 +62,53 @@ static const rb_data_type_t rkrb5_data_type = {
 static VALUE rkrb5_allocate(VALUE klass){
   RUBY_KRB5* ptr = ALLOC(RUBY_KRB5);
   memset(ptr, 0, sizeof(RUBY_KRB5));
+  ptr->rb_context = Qnil;
   return TypedData_Wrap_Struct(klass, &rkrb5_data_type, ptr);
 }
 
 /*
  * call-seq:
- *   Kerberos::Krb5.new
+ *   Kerberos::Krb5.new(context: nil)
  *
  * Creates and returns a new Kerberos::Krb5 object. This initializes the
  * context for future method calls on that object.
+ *
+ * If a +context+ keyword argument is provided, it must be a
+ * Kerberos::Krb5::Context object. The context will be borrowed rather than
+ * creating a new one internally via krb5_init_context. The caller is
+ * retained for the lifetime of this Krb5 instance. The Context cannot be
+ * closed normally until this object has been closed.
+ *
+ * A block form is also supported. If a block is given, the object is
+ * yielded to the block and automatically closed when the block returns.
  */
-static VALUE rkrb5_initialize(VALUE self){
+static VALUE rkrb5_initialize(int argc, VALUE* argv, VALUE self){
   RUBY_KRB5* ptr;
+  VALUE v_opts, v_context;
+  ID kw_table[1] = { rb_intern("context") };
+  VALUE kw_vals[1];
   krb5_error_code kerror;
 
   TypedData_Get_Struct(self, RUBY_KRB5, &rkrb5_data_type, ptr);
 
-  kerror = krb5_init_context(&ptr->ctx);
+  rb_scan_args(argc, argv, "0:", &v_opts);
 
-  if(kerror)
-    rb_raise(cKrb5Exception, "krb5_init_context: %s", error_message(kerror));
+  if(NIL_P(v_opts))
+    v_opts = rb_hash_new();
+
+  rb_get_kwargs(v_opts, kw_table, 0, 1, kw_vals);
+  v_context = kw_vals[0] == Qundef ? Qnil : kw_vals[0];
+
+  if(!NIL_P(v_context)){
+    ptr->ctx = rkrb5_context_borrow(v_context);
+    ptr->rb_context = v_context;
+  }
+  else{
+    kerror = krb5_init_context(&ptr->ctx);
+
+    if(kerror)
+      rb_raise(cKrb5Exception, "krb5_init_context: %s", error_message(kerror));
+  }
 
   if(rb_block_given_p()){
     rb_ensure(rb_yield, self, rkrb5_close, self);
@@ -95,6 +131,9 @@ static VALUE rkrb5_get_default_realm(VALUE self){
 
   TypedData_Get_Struct(self, RUBY_KRB5, &rkrb5_data_type, ptr);
 
+  if(!ptr->ctx)
+    rb_raise(cKrb5Exception, "no context has been established");
+
   kerror = krb5_get_default_realm(ptr->ctx, &realm);
 
   if(kerror)
@@ -121,6 +160,9 @@ static VALUE rkrb5_set_default_realm(int argc, VALUE* argv, VALUE self){
 
   TypedData_Get_Struct(self, RUBY_KRB5, &rkrb5_data_type, ptr);
 
+  if(!ptr->ctx)
+    rb_raise(cKrb5Exception, "no context has been established");
+
   rb_scan_args(argc, argv, "01", &v_realm);
 
   if(NIL_P(v_realm)){
@@ -140,7 +182,7 @@ static VALUE rkrb5_set_default_realm(int argc, VALUE* argv, VALUE self){
 }
 
 /* call-seq:
- *   krb5.get_init_creds_keytab(principal = nil, keytab = nil, service = nil, ccache = nil)
+ *   krb5.get_init_creds_keytab(principal: nil, keytab: nil, service: nil, ccache: nil)
  *
  * Acquire credentials for +principal+ from +keytab+ using +service+. If
  * no principal is specified, then a principal is derived from the service
@@ -154,7 +196,10 @@ static VALUE rkrb5_set_default_realm(int argc, VALUE* argv, VALUE self){
  */
 static VALUE rkrb5_get_init_creds_keytab(int argc, VALUE* argv, VALUE self){
   RUBY_KRB5* ptr;
-  VALUE v_user, v_keytab_name, v_service, v_ccache;
+  VALUE v_user = Qnil, v_keytab_name = Qnil, v_service = Qnil, v_ccache = Qnil;
+  VALUE v_kwargs = Qnil;
+  ID kw_table[4] = { rb_intern("principal"), rb_intern("keytab"), rb_intern("service"), rb_intern("ccache") };
+  VALUE kw_vals[4];
   char* user;
   char* service;
   char keytab_name[MAX_KEYTAB_NAME_LEN];
@@ -181,7 +226,16 @@ static VALUE rkrb5_get_init_creds_keytab(int argc, VALUE* argv, VALUE self){
   krb5_free_cred_contents(ptr->ctx, &ptr->creds);
   memset(&ptr->creds, 0, sizeof(ptr->creds));
 
-  rb_scan_args(argc, argv, "04", &v_user, &v_keytab_name, &v_service, &v_ccache);
+  rb_scan_args(argc, argv, "0:", &v_kwargs);
+
+  if(NIL_P(v_kwargs))
+    v_kwargs = rb_hash_new();
+
+  rb_get_kwargs(v_kwargs, kw_table, 0, 4, kw_vals);
+  if(kw_vals[0] != Qundef) v_user = kw_vals[0];
+  if(kw_vals[1] != Qundef) v_keytab_name = kw_vals[1];
+  if(kw_vals[2] != Qundef) v_service = kw_vals[2];
+  if(kw_vals[3] != Qundef) v_ccache = kw_vals[3];
 
   // Validate argument types before allocating opt, so type errors don't leak it.
   if(!NIL_P(v_user))
@@ -261,6 +315,11 @@ static VALUE rkrb5_get_init_creds_keytab(int argc, VALUE* argv, VALUE self){
     RUBY_KRB5_CCACHE* ccptr;
     TypedData_Get_Struct(v_ccache, RUBY_KRB5_CCACHE, &rkrb5_ccache_data_type, ccptr);
 
+    if(!ccptr->ctx || !ccptr->ccache){
+      krb5_get_init_creds_opt_free(ptr->ctx, opt);
+      rb_raise(cKrb5Exception, "credentials cache is closed or destroyed");
+    }
+
     kerror = krb5_get_init_creds_opt_set_out_ccache(ptr->ctx, opt, ccptr->ccache);
     if(kerror) {
       krb5_get_init_creds_opt_free(ptr->ctx, opt);
@@ -300,7 +359,7 @@ static VALUE rkrb5_get_init_creds_keytab(int argc, VALUE* argv, VALUE self){
  *
  * Example:
  *
- * krb5.get_init_creds_password('foo', 'XXXXXX') # Authenticate 'foo' user
+ * krb5.get_init_creds_password(principal: 'foo', password: 'XXXXXX') # Authenticate 'foo' user
  * krb5.change_password('XXXXXX', 'YYYYYY')      # Change password for 'foo'
  */
 static VALUE rkrb5_change_password(VALUE self, VALUE v_old, VALUE v_new){
@@ -328,6 +387,9 @@ static VALUE rkrb5_change_password(VALUE self, VALUE v_old, VALUE v_new){
   if(!ptr->princ)
     rb_raise(cKrb5Exception, "no principal has been established");
 
+  memset(&result_string, 0, sizeof(result_string));
+  memset(&pw_result_string, 0, sizeof(pw_result_string));
+
   krb5_free_cred_contents(ptr->ctx, &ptr->creds);
   memset(&ptr->creds, 0, sizeof(ptr->creds));
 
@@ -378,19 +440,26 @@ static VALUE rkrb5_change_password(VALUE self, VALUE v_old, VALUE v_new){
 
 /*
  * call-seq:
- *   krb5.get_init_creds_password(user, password, service = nil)
+ *   krb5.get_init_creds_password(principal: nil, password: nil, service: nil, ccache: nil)
  *
- * Authenticates the credentials of +user+ using +password+ against +service+,
+ * Authenticates the credentials of +principal+ using +password+ against +service+,
  * and has the effect of setting the principal and context internally. This method
  * must typically be called before using other methods.
+ *
+ * When +ccache+ is given, the acquired credentials will be written into the
+ * provided Kerberos::Krb5::CredentialsCache.
  */
 static VALUE rkrb5_get_init_creds_passwd(int argc, VALUE* argv, VALUE self){
   RUBY_KRB5* ptr;
-  VALUE v_user, v_pass, v_service;
+  VALUE v_user = Qnil, v_pass = Qnil, v_service = Qnil, v_ccache = Qnil;
+  VALUE v_kwargs = Qnil;
+  ID kw_table[4] = { rb_intern("principal"), rb_intern("password"), rb_intern("service"), rb_intern("ccache") };
+  VALUE kw_vals[4];
   char* user;
   char* pass;
   char* service;
   krb5_error_code kerror;
+  krb5_get_init_creds_opt* opt = NULL;
 
   TypedData_Get_Struct(self, RUBY_KRB5, &rkrb5_data_type, ptr);
 
@@ -406,7 +475,19 @@ static VALUE rkrb5_get_init_creds_passwd(int argc, VALUE* argv, VALUE self){
   krb5_free_cred_contents(ptr->ctx, &ptr->creds);
   memset(&ptr->creds, 0, sizeof(ptr->creds));
 
-  rb_scan_args(argc, argv, "21", &v_user, &v_pass, &v_service);
+  rb_scan_args(argc, argv, "0:", &v_kwargs);
+
+  if(NIL_P(v_kwargs))
+    v_kwargs = rb_hash_new();
+
+  rb_get_kwargs(v_kwargs, kw_table, 0, 4, kw_vals);
+  if(kw_vals[0] != Qundef) v_user = kw_vals[0];
+  if(kw_vals[1] != Qundef) v_pass = kw_vals[1];
+  if(kw_vals[2] != Qundef) v_service = kw_vals[2];
+  if(kw_vals[3] != Qundef) v_ccache = kw_vals[3];
+
+  if(NIL_P(v_user) || NIL_P(v_pass))
+    rb_raise(rb_eArgError, "principal and password are required");
 
   Check_Type(v_user, T_STRING);
   Check_Type(v_pass, T_STRING);
@@ -426,6 +507,24 @@ static VALUE rkrb5_get_init_creds_passwd(int argc, VALUE* argv, VALUE self){
   if(kerror)
     rb_raise(cKrb5Exception, "krb5_parse_name: %s", error_message(kerror));
 
+  if(!NIL_P(v_ccache)){
+    RUBY_KRB5_CCACHE* ccptr;
+    TypedData_Get_Struct(v_ccache, RUBY_KRB5_CCACHE, &rkrb5_ccache_data_type, ccptr);
+
+    if(!ccptr->ctx || !ccptr->ccache)
+      rb_raise(cKrb5Exception, "credentials cache is closed or destroyed");
+
+    kerror = krb5_get_init_creds_opt_alloc(ptr->ctx, &opt);
+    if(kerror)
+      rb_raise(cKrb5Exception, "krb5_get_init_creds_opt_alloc: %s", error_message(kerror));
+
+    kerror = krb5_get_init_creds_opt_set_out_ccache(ptr->ctx, opt, ccptr->ccache);
+    if(kerror){
+      krb5_get_init_creds_opt_free(ptr->ctx, opt);
+      rb_raise(cKrb5Exception, "krb5_get_init_creds_opt_set_out_ccache: %s", error_message(kerror));
+    }
+  }
+
   kerror = krb5_get_init_creds_password(
     ptr->ctx,
     &ptr->creds,
@@ -435,9 +534,12 @@ static VALUE rkrb5_get_init_creds_passwd(int argc, VALUE* argv, VALUE self){
     NULL,
     0,
     service,
-    NULL
+    opt
   );
 
+  if(opt)
+    krb5_get_init_creds_opt_free(ptr->ctx, opt);
+
   if(kerror)
     rb_raise(cKrb5Exception, "krb5_get_init_creds_password: %s", error_message(kerror));
 
@@ -446,7 +548,7 @@ static VALUE rkrb5_get_init_creds_passwd(int argc, VALUE* argv, VALUE self){
 
  /*
  * call-seq:
- *   krb5.authenticate!(user, password, service = nil)
+ *   krb5.authenticate!(principal:, password:, service: nil)
  *
  * Convenience method that: acquires initial credentials via password and
  * immediately verifies those credentials using `verify_init_creds` with
@@ -458,7 +560,9 @@ static VALUE rkrb5_get_init_creds_passwd(int argc, VALUE* argv, VALUE self){
  */
 static VALUE rkrb5_authenticate_bang(int argc, VALUE* argv, VALUE self){
   RUBY_KRB5* ptr;
-  VALUE v_user, v_pass, v_service;
+  VALUE v_kwargs, v_user, v_pass, v_service;
+  ID kw_table[3] = { rb_intern("principal"), rb_intern("password"), rb_intern("service") };
+  VALUE kw_vals[3];
   char* user;
   char* pass;
   char* service;
@@ -479,8 +583,15 @@ static VALUE rkrb5_authenticate_bang(int argc, VALUE* argv, VALUE self){
   krb5_free_cred_contents(ptr->ctx, &ptr->creds);
   memset(&ptr->creds, 0, sizeof(ptr->creds));
 
-  // Require user and password, optional service
-  rb_scan_args(argc, argv, "21", &v_user, &v_pass, &v_service);
+  rb_scan_args(argc, argv, "0:", &v_kwargs);
+
+  if(NIL_P(v_kwargs))
+    v_kwargs = rb_hash_new();
+
+  rb_get_kwargs(v_kwargs, kw_table, 2, 1, kw_vals);
+  v_user = kw_vals[0];
+  v_pass = kw_vals[1];
+  v_service = kw_vals[2] == Qundef ? Qnil : kw_vals[2];
 
   Check_Type(v_user, T_STRING);
   Check_Type(v_pass, T_STRING);
@@ -516,14 +627,7 @@ static VALUE rkrb5_authenticate_bang(int argc, VALUE* argv, VALUE self){
   if(kerror)
     rb_raise(cKrb5Exception, "krb5_get_init_creds_password: %s", error_message(kerror));
 
-  /*
-   * Try strict verification first (AP-REQ nofail). If strict verification
-   * cannot be performed (e.g. missing keytab or other environment issue),
-   * fall back to the standard verification so authenticate! remains useful
-   * in minimal test environments.
-   */
   krb5_verify_init_creds_opt vicopt;
-  krb5_error_code kerror_strict = 0;
 
   krb5_verify_init_creds_opt_init(&vicopt);
   krb5_verify_init_creds_opt_set_ap_req_nofail(&vicopt, TRUE);
@@ -536,19 +640,12 @@ static VALUE rkrb5_authenticate_bang(int argc, VALUE* argv, VALUE self){
       rb_raise(cKrb5Exception, "krb5_parse_name(service): %s", error_message(kerror));
   }
 
-  // First, attempt strict verification
   kerror = krb5_verify_init_creds(ptr->ctx, &ptr->creds, server_princ, NULL, NULL, &vicopt);
 
   if(kerror){
-    /* strict verification failed — try a best-effort standard verify */
-    kerror_strict = kerror;
-    kerror = krb5_verify_init_creds(ptr->ctx, &ptr->creds, server_princ, NULL, NULL, NULL);
-    if(kerror){
-      if(server_princ)
-        krb5_free_principal(ptr->ctx, server_princ);
-      /* raise the original strict-verification error to inform caller */
-      rb_raise(cKrb5Exception, "krb5_verify_init_creds: %s", error_message(kerror_strict));
-    }
+    if(server_princ)
+      krb5_free_principal(ptr->ctx, server_princ);
+    rb_raise(cKrb5Exception, "krb5_verify_init_creds: %s", error_message(kerror));
   }
 
   if(server_princ)
@@ -580,11 +677,14 @@ static VALUE rkrb5_close(VALUE self){
   if(ptr->princ)
     krb5_free_principal(ptr->ctx, ptr->princ);
 
-  if(ptr->ctx)
+  if(ptr->ctx && ptr->rb_context == Qnil)
     krb5_free_context(ptr->ctx);
+  else if(ptr->rb_context != Qnil)
+    rkrb5_context_release(ptr->rb_context);
 
   ptr->ctx = NULL;
   ptr->princ = NULL;
+  ptr->rb_context = Qnil;
 
   return Qtrue;
 }
@@ -701,7 +801,7 @@ static VALUE rkrb5_get_permitted_enctypes(VALUE self){
 
 /*
  * call-seq:
- *   krb5.verify_init_creds(server = nil, keytab = nil, ccache = nil)
+ *   krb5.verify_init_creds(server: nil, keytab: nil, ccache: nil)
  *
  * Verifies the initial credentials currently stored in the internal
  * credentials structure. Optionally a server principal string, a
@@ -711,7 +811,10 @@ static VALUE rkrb5_get_permitted_enctypes(VALUE self){
  */
 static VALUE rkrb5_verify_init_creds(int argc, VALUE* argv, VALUE self){
   RUBY_KRB5* ptr;
-  VALUE v_server, v_keytab, v_ccache;
+  VALUE v_server = Qnil, v_keytab = Qnil, v_ccache = Qnil;
+  VALUE v_kwargs = Qnil;
+  ID kw_table[3] = { rb_intern("server"), rb_intern("keytab"), rb_intern("ccache") };
+  VALUE kw_vals[3];
   krb5_error_code kerror;
   krb5_principal server_princ = NULL;
   RUBY_KRB5_KEYTAB* ktptr = NULL;
@@ -719,7 +822,15 @@ static VALUE rkrb5_verify_init_creds(int argc, VALUE* argv, VALUE self){
   krb5_keytab keytab = NULL;
   krb5_ccache *ccache_ptr = NULL;
 
-  rb_scan_args(argc, argv, "03", &v_server, &v_keytab, &v_ccache);
+  rb_scan_args(argc, argv, "0:", &v_kwargs);
+
+  if(NIL_P(v_kwargs))
+    v_kwargs = rb_hash_new();
+
+  rb_get_kwargs(v_kwargs, kw_table, 0, 3, kw_vals);
+  if(kw_vals[0] != Qundef) v_server = kw_vals[0];
+  if(kw_vals[1] != Qundef) v_keytab = kw_vals[1];
+  if(kw_vals[2] != Qundef) v_ccache = kw_vals[2];
 
   TypedData_Get_Struct(self, RUBY_KRB5, &rkrb5_data_type, ptr);
 
@@ -734,12 +845,20 @@ static VALUE rkrb5_verify_init_creds(int argc, VALUE* argv, VALUE self){
   if(!NIL_P(v_keytab)){
     // Will raise TypeError if object isn't the expected Keytab typed data
     TypedData_Get_Struct(v_keytab, RUBY_KRB5_KEYTAB, &rkrb5_keytab_data_type, ktptr);
+
+    if(!ktptr->ctx || !ktptr->keytab)
+      rb_raise(cKrb5Exception, "keytab is closed");
+
     keytab = ktptr->keytab;
   }
 
   if(!NIL_P(v_ccache)){
     // Will raise TypeError if object isn't the expected CCache typed data
     TypedData_Get_Struct(v_ccache, RUBY_KRB5_CCACHE, &rkrb5_ccache_data_type, ccptr);
+
+    if(!ccptr->ctx || !ccptr->ccache)
+      rb_raise(cKrb5Exception, "credentials cache is closed or destroyed");
+
     ccache_ptr = &ccptr->ccache;
   }
 
@@ -747,6 +866,22 @@ static VALUE rkrb5_verify_init_creds(int argc, VALUE* argv, VALUE self){
   if(ptr->creds.client == NULL)
     rb_raise(cKrb5Exception, "no credentials have been acquired");
 
+  /* A resolved FILE cache may not exist on disk yet. Create it before
+     krb5_verify_init_creds attempts to store any credentials it fetches. */
+  if(ccache_ptr && *ccache_ptr){
+    krb5_principal cache_princ = NULL;
+
+    kerror = krb5_cc_get_principal(ptr->ctx, *ccache_ptr, &cache_princ);
+
+    if(kerror == KRB5_CC_NOTFOUND || kerror == KRB5_FCC_NOFILE)
+      kerror = krb5_cc_initialize(ptr->ctx, *ccache_ptr, ptr->creds.client);
+    else if(!kerror)
+      krb5_free_principal(ptr->ctx, cache_princ);
+
+    if(kerror)
+      rb_raise(cKrb5Exception, "credentials cache setup: %s", error_message(kerror));
+  }
+
   // Optional server principal (parse after context & arg validation)
   if(!NIL_P(v_server)){
     kerror = krb5_parse_name(ptr->ctx, StringValueCStr(v_server), &server_princ);
@@ -762,16 +897,11 @@ static VALUE rkrb5_verify_init_creds(int argc, VALUE* argv, VALUE self){
   if(kerror)
     rb_raise(cKrb5Exception, "krb5_verify_init_creds: %s", error_message(kerror));
 
-  /* If the caller supplied a CredentialsCache object, store the verified
-     credentials there so Ruby-level callers can inspect the cache. */
+  /* Include the initial credential in addition to any credentials fetched
+     and stored by krb5_verify_init_creds. */
   if(ccache_ptr && *ccache_ptr){
     krb5_error_code k2;
 
-    k2 = krb5_cc_initialize(ptr->ctx, *ccache_ptr, ptr->creds.client);
-
-    if(k2)
-      rb_raise(cKrb5Exception, "krb5_cc_initialize: %s", error_message(k2));
-
     k2 = krb5_cc_store_cred(ptr->ctx, *ccache_ptr, &ptr->creds);
 
     if(k2)
@@ -781,6 +911,83 @@ static VALUE rkrb5_verify_init_creds(int argc, VALUE* argv, VALUE self){
   return Qtrue;
 }
 
+/*
+ * call-seq:
+ *   krb5.get_host_realm(hostname) -> Array
+ *
+ * Returns an array of realm names associated with +hostname+.
+ * Uses the Kerberos library's host-to-realm mapping (krb5.conf
+ * [domain_realm] section, DNS lookups, etc.).
+ */
+static VALUE rkrb5_get_host_realm(VALUE self, VALUE v_host){
+  RUBY_KRB5* ptr;
+  char** realms;
+  char** p;
+  krb5_error_code kerror;
+
+  TypedData_Get_Struct(self, RUBY_KRB5, &rkrb5_data_type, ptr);
+
+  if(!ptr->ctx)
+    rb_raise(cKrb5Exception, "no context has been established");
+
+  Check_Type(v_host, T_STRING);
+
+  kerror = krb5_get_host_realm(ptr->ctx, StringValueCStr(v_host), &realms);
+
+  if(kerror)
+    rb_raise(cKrb5Exception, "krb5_get_host_realm: %s", error_message(kerror));
+
+  VALUE v_array = rb_ary_new();
+
+  for(p = realms; p && *p; p++)
+    rb_ary_push(v_array, rb_str_new2(*p));
+
+  krb5_free_host_realm(ptr->ctx, realms);
+
+  return v_array;
+}
+
+/*
+ * call-seq:
+ *   krb5.expand_hostname(hostname) -> String
+ *
+ * Canonicalizes +hostname+ by performing a forward DNS lookup followed
+ * by a reverse lookup, returning the canonical hostname.
+ */
+static VALUE rkrb5_expand_hostname(VALUE self, VALUE v_host){
+  RUBY_KRB5* ptr;
+  char* canonical;
+  krb5_error_code kerror;
+
+  TypedData_Get_Struct(self, RUBY_KRB5, &rkrb5_data_type, ptr);
+
+  if(!ptr->ctx)
+    rb_raise(cKrb5Exception, "no context has been established");
+
+  Check_Type(v_host, T_STRING);
+
+  kerror = krb5_expand_hostname(ptr->ctx, StringValueCStr(v_host), &canonical);
+
+  if(kerror)
+    rb_raise(cKrb5Exception, "krb5_expand_hostname: %s", error_message(kerror));
+
+  VALUE v_result = rb_str_new2(canonical);
+  krb5_free_string(ptr->ctx, canonical);
+
+  return v_result;
+}
+
+/*
+ * call-seq:
+ *   Kerberos::Krb5.thread_safe?
+ *
+ * Returns true if the Kerberos library was built with multithread support,
+ * false otherwise.
+ */
+static VALUE rkrb5_s_thread_safe(VALUE klass){
+  return krb5_is_thread_safe() ? Qtrue : Qfalse;
+}
+
 void Init_rkerberos(void){
   mKerberos      = rb_define_module("Kerberos");
   cKrb5          = rb_define_class_under(mKerberos, "Krb5", rb_cObject);
@@ -790,7 +997,10 @@ void Init_rkerberos(void){
   rb_define_alloc_func(cKrb5, rkrb5_allocate);
 
   // Initializers
-  rb_define_method(cKrb5, "initialize", rkrb5_initialize, 0);
+  rb_define_method(cKrb5, "initialize", rkrb5_initialize, -1);
+
+  // Singleton Methods
+  rb_define_singleton_method(cKrb5, "thread_safe?", rkrb5_s_thread_safe, 0);
 
   // Krb5 Methods
   rb_define_method(cKrb5, "authenticate!", rkrb5_authenticate_bang, -1);
@@ -803,13 +1013,20 @@ void Init_rkerberos(void){
   rb_define_method(cKrb5, "get_permitted_enctypes", rkrb5_get_permitted_enctypes, 0);
   rb_define_method(cKrb5, "set_default_realm", rkrb5_set_default_realm, -1);
   rb_define_method(cKrb5, "verify_init_creds", rkrb5_verify_init_creds, -1);
+  rb_define_method(cKrb5, "get_host_realm", rkrb5_get_host_realm, 1);
+  rb_define_method(cKrb5, "expand_hostname", rkrb5_expand_hostname, 1);
 
   // Aliases
   rb_define_alias(cKrb5, "default_realm", "get_default_realm");
+  rb_define_alias(cKrb5, "default_realm=", "set_default_realm");
   rb_define_alias(cKrb5, "default_principal", "get_default_principal");
+  rb_define_alias(cKrb5, "host_realm", "get_host_realm");
+  rb_define_alias(cKrb5, "init_creds_password", "get_init_creds_password");
+  rb_define_alias(cKrb5, "init_creds_keytab", "get_init_creds_keytab");
+  rb_define_alias(cKrb5, "permitted_enctypes", "get_permitted_enctypes");
 
-  /* 0.2.3: The version of the custom rkerberos library */
-  rb_define_const(cKrb5, "VERSION", rb_str_new2("0.2.3"));
+  /* 0.3.1: The version of the custom rkerberos library */
+  rb_define_const(cKrb5, "VERSION", rb_str_new2("0.3.1"));
 
   // Encoding type constants
 

data/ext/rkerberos/rkerberos.h

@@ -8,6 +8,8 @@
 
 // Make the context data type visible to other C files
 extern const rb_data_type_t rkrb5_context_data_type;
+// Make the Krb5 data type visible to other C files
+extern const rb_data_type_t rkrb5_data_type;
 // Make the config data type visible to other C files
 extern const rb_data_type_t rkadm5_config_data_type;
 
@@ -47,6 +49,10 @@ void Init_ccache();
 // Defined in rkerberos.c
 VALUE rb_hash_aref2(VALUE, VALUE);
 
+// Defined in context.c
+krb5_context rkrb5_context_borrow(VALUE);
+void rkrb5_context_release(VALUE);
+
 // Variable declarations
 extern VALUE mKerberos;
 extern VALUE cKrb5;
@@ -67,12 +73,15 @@ typedef struct {
   krb5_creds creds;
   krb5_principal princ;
   krb5_keytab keytab;
+  VALUE rb_context;
 } RUBY_KRB5;
 
 // Kerberos::Context
 typedef struct {
   krb5_context ctx;
   krb5_enctype etypes;
+  size_t borrowers;
+  int closed;
 } RUBY_KRB5_CONTEXT;
 
 // Kerberos::Kadm5
@@ -81,6 +90,7 @@ typedef struct {
   krb5_principal princ;
   void* handle;
   char** db_args;
+  VALUE rb_context; // Ruby Context object when borrowed, Qnil if ctx is owned
 } RUBY_KADM5;
 
 // Kerberos::Krb5::Keytab::Entry
@@ -96,23 +106,27 @@ typedef struct {
   krb5_context ctx;
   krb5_creds creds;
   krb5_keytab keytab;
+  VALUE rb_context; // Ruby Context object when borrowed, Qnil if ctx is owned
 } RUBY_KRB5_KEYTAB;
 
 typedef struct {
   krb5_context ctx;
   krb5_principal principal;
+  VALUE rb_context; // Ruby Context object when borrowed, Qnil if ctx is owned
 } RUBY_KRB5_PRINC;
 
 typedef struct {
   krb5_context ctx;
   krb5_ccache ccache;
   krb5_principal principal;
+  VALUE rb_context; // Ruby Context object when borrowed, Qnil if ctx is owned
 } RUBY_KRB5_CCACHE;
 
 #ifdef HAVE_KADM5_ADMIN_H
 typedef struct {
   krb5_context ctx;
   kadm5_config_params config;
+  VALUE rb_context; // Ruby Context object when borrowed, Qnil if ctx is owned
 } RUBY_KADM5_CONFIG;
 
 typedef struct {

data/rkerberos.gemspec

@@ -2,15 +2,18 @@ require 'rubygems'
 
 Gem::Specification.new do |spec|
   spec.name       = 'rkerberos'
-  spec.version    = '0.2.3'
+  spec.version    = '0.3.1'
   spec.authors    = ['Daniel Berger', 'Dominic Cleal', 'Simon Levermann']
   spec.license    = 'Artistic-2.0'
   spec.email      = ['djberg96@gmail.com', 'dominic@cleal.org', 'simon-rubygems@slevermann.de']
-  spec.homepage   = 'http://github.com/rkerberos/rkerberos'
-  spec.summary    = 'A Ruby interface for the the Kerberos library'
+  spec.homepage   = 'https://github.com/rkerberos/rkerberos'
+  spec.summary    = 'A Ruby interface for the Kerberos library'
+  spec.required_ruby_version = '>= 3.2'
   spec.test_files = Dir['spec/**/*_spec.rb']
   spec.extensions = ['ext/rkerberos/extconf.rb']
-  spec.files      = Dir['**/*'].grep_v(%r{\A(?:\.git|docker|Dockerfile)})
+  spec.files      = Dir['**/*']
+    .select { |file| File.file?(file) }
+    .grep_v(%r{\A(?:\.git|docker|Dockerfile|Gemfile\.lock\z|tmp(?:/|\z))|\.gem\z})
 
   spec.add_development_dependency('rake-compiler')
   spec.add_development_dependency('rspec', '>= 3.0')
@@ -22,13 +25,13 @@ Gem::Specification.new do |spec|
   EOF
 
   spec.metadata = {
-    'homepage_uri'          => 'https://github.com/rkerberos/rkerberos',
     'bug_tracker_uri'       => 'https://github.com/rkerberos/rkerberos/issues',
-    'changelog_uri'         => 'https://github.com/rkerberos/rkerberos/blob/main/CHANGES.md',
+    'changelog_uri'         => 'https://github.com/rkerberos/rkerberos/blob/master/CHANGES.md',
     'documentation_uri'     => 'https://github.com/rkerberos/rkerberos/wiki',
+    'homepage_uri'          => 'https://github.com/rkerberos/rkerberos',
     'source_code_uri'       => 'https://github.com/rkerberos/rkerberos',
     'wiki_uri'              => 'https://github.com/rkerberos/rkerberos/wiki',
-    'github_repo'           => 'https://github.com/djberg96/rkerberos',
+    'github_repo'           => 'https://github.com/rkerberos/rkerberos',
     'funding_uri'           => 'https://github.com/sponsors/rkerberos',
     'rubygems_mfa_required' => 'true'
   }