rkerberos 0.2.3 → 0.3.0

data/MANIFEST.md

@@ -1,24 +1,29 @@
 * CHANGES.md
+* EXAMPLES.md
+* Gemfile
+* LICENSE
 * rkerberos.gemspec
 * MANIFEST.md
 * Rakefile
-* README
-* ext/ccache.c
-* ext/context.c
-* ext/extconf.rb
-* ext/kadm5.c
-* ext/keytab.c
-* ext/keytab_entry.c
-* ext/rkerberos.c
-* ext/rkerberos.h
-* ext/policy.c
-* ext/principal.c
+* README.md
+* ext/rkerberos/ccache.c
+* ext/rkerberos/config.c
+* ext/rkerberos/context.c
+* ext/rkerberos/extconf.rb
+* ext/rkerberos/kadm5.c
+* ext/rkerberos/keytab.c
+* ext/rkerberos/keytab_entry.c
+* ext/rkerberos/policy.c
+* ext/rkerberos/principal.c
+* ext/rkerberos/rkerberos.c
+* ext/rkerberos/rkerberos.h
 * spec/config_spec.rb
 * spec/context_spec.rb
-* spec/credentials_spec.rb
+* spec/credentials_cache_spec.rb
 * spec/kadm5_spec.rb
 * spec/keytab_entry_spec.rb
 * spec/krb5_keytab_spec.rb
 * spec/krb5_spec.rb
 * spec/policy_spec.rb
 * spec/principal_spec.rb
+* spec/spec_helper.rb

data/README.md

@@ -18,17 +18,17 @@ puts krb.get_permitted_enctypes.keys.join(',')
 
 # Credentials cache
 cc = Kerberos::Krb5::CredentialsCache.new
-krb.verify_init_creds(nil, nil, cc)
+krb.verify_init_creds(ccache: cc)
 puts cc.primary_principal
 
 # Keytab
 kt_name = Kerberos::Krb5::Keytab.new.default_name # e.g. "FILE:/etc/krb5.keytab"
-krb.get_init_creds_keytab('host/server.example.com', kt_name)
-krb.get_init_creds_keytab('host/server.example.com', kt_name, nil, cc) # or write to cache
+krb.get_init_creds_keytab(principal: 'host/server.example.com', keytab: kt_name)
+krb.get_init_creds_keytab(principal: 'host/server.example.com', keytab: kt_name, ccache: cc) # or write to cache
 
 # Admin
 Kerberos::Kadm5.new(principal: ENV['KRB5_ADMIN_PRINCIPAL'], password: ENV['KRB5_ADMIN_PASSWORD']) do |kadmin|
-  kadmin.create_principal('newuser@EXAMPLE.COM', 'initialpass')
+  kadmin.create_principal(name: 'newuser@EXAMPLE.COM', password: 'initialpass')
   kadmin.set_password('newuser@EXAMPLE.COM', 'betterpass')
   kadmin.delete_principal('newuser@EXAMPLE.COM')
 end
@@ -79,7 +79,7 @@ ctx.close
 # Testing
 
 ## Prerequisites
-- Ruby 3.4 or later
+- Ruby 3.2 or later
 - Docker or Podman
 - docker-compose or podman-compose
 

data/ext/rkerberos/ccache.c

@@ -4,6 +4,13 @@ VALUE cKrb5CCache;
 
 
 // TypedData functions for RUBY_KRB5_CCACHE
+static void rkrb5_ccache_typed_mark(void *ptr) {
+  if (!ptr) return;
+  RUBY_KRB5_CCACHE *c = (RUBY_KRB5_CCACHE *)ptr;
+  if (c->rb_context != Qnil)
+    rb_gc_mark(c->rb_context);
+}
+
 static void rkrb5_ccache_typed_free(void *ptr) {
   if (!ptr) return;
   RUBY_KRB5_CCACHE *c = (RUBY_KRB5_CCACHE *)ptr;
@@ -11,7 +18,7 @@ static void rkrb5_ccache_typed_free(void *ptr) {
     krb5_cc_close(c->ctx, c->ccache);
   if (c->principal)
     krb5_free_principal(c->ctx, c->principal);
-  if (c->ctx)
+  if (c->ctx && c->rb_context == Qnil)
     krb5_free_context(c->ctx);
   free(c);
 }
@@ -22,7 +29,7 @@ static size_t rkrb5_ccache_typed_size(const void *ptr) {
 
 const rb_data_type_t rkrb5_ccache_data_type = {
   "RUBY_KRB5_CCACHE",
-  {NULL, rkrb5_ccache_typed_free, rkrb5_ccache_typed_size,},
+  {rkrb5_ccache_typed_mark, rkrb5_ccache_typed_free, rkrb5_ccache_typed_size,},
   NULL, NULL, RUBY_TYPED_FREE_IMMEDIATELY
 };
 
@@ -30,20 +37,28 @@ const rb_data_type_t rkrb5_ccache_data_type = {
 static VALUE rkrb5_ccache_allocate(VALUE klass){
   RUBY_KRB5_CCACHE* ptr = ALLOC(RUBY_KRB5_CCACHE);
   memset(ptr, 0, sizeof(RUBY_KRB5_CCACHE));
+  ptr->rb_context = Qnil;
   return TypedData_Wrap_Struct(klass, &rkrb5_ccache_data_type, ptr);
 }
 
 /*
  * call-seq:
- *   Kerberos::CredentialsCache.new(principal = nil, cache_name = nil)
+ *   Kerberos::CredentialsCache.new(principal: nil, cache_name: nil, context: nil)
+ *
+ * Creates and returns a new Kerberos::CredentialsCache object. Accepts the
+ * following keyword arguments:
+ *
+ * - +principal+: A string principal name. If specified, the credentials cache
+ *   is created or refreshed with this as the primary principal. If a cache
+ *   already exists, its contents are destroyed. May also be an object that
+ *   responds to the `.principal` method.
  *
- * Creates and returns a new Kerberos::CredentialsCache object. If cache_name
- * is specified, then that cache is used, which must be in "type:residual"
- * format, where 'type' is a type known to Kerberos (typically 'FILE').
+ * - +cache_name+: The name of the credentials cache to use, which must be in
+ *   "type:residual" format, where 'type' is a type known to Kerberos
+ *   (typically 'FILE'). If omitted, the default cache is used.
  *
- * If a +principal+ is specified, then it creates or refreshes the credentials
- * cache with the primary principal set to +principal+. If the credentials
- * cache already exists, its contents are destroyed.
+ * - +context+: A Kerberos::Krb5::Context object. If provided, that context is
+ *   used instead of creating a new one via krb5_init_context.
  *
  * Note that the principal's credentials are not set via the constructor.
  * It merely creates the cache and sets the default principal.
@@ -51,23 +66,55 @@ static VALUE rkrb5_ccache_allocate(VALUE klass){
 static VALUE rkrb5_ccache_initialize(int argc, VALUE* argv, VALUE self){
   RUBY_KRB5_CCACHE* ptr;
   krb5_error_code kerror;
-  VALUE v_principal, v_name;
+  VALUE v_opts, v_principal, v_name, v_context;
+  ID kw_table[3] = { rb_intern("principal"), rb_intern("cache_name"), rb_intern("context") };
+  VALUE kw_vals[3];
 
   TypedData_Get_Struct(self, RUBY_KRB5_CCACHE, &rkrb5_ccache_data_type, ptr);
 
-  rb_scan_args(argc, argv, "02", &v_principal, &v_name);
+  rb_scan_args(argc, argv, "0:", &v_opts);
+
+  if(NIL_P(v_opts))
+    v_opts = rb_hash_new();
+
+  rb_get_kwargs(v_opts, kw_table, 0, 3, kw_vals);
+  v_principal = kw_vals[0] == Qundef ? Qnil : kw_vals[0];
+  v_name = kw_vals[1] == Qundef ? Qnil : kw_vals[1];
+  v_context = kw_vals[2] == Qundef ? Qnil : kw_vals[2];
+
+  if(!NIL_P(v_principal)){
+    if(rb_respond_to(v_principal, rb_intern("principal")))
+      v_principal = rb_funcall(v_principal, rb_intern("principal"), 0);
 
-  if(RTEST(v_principal))
     Check_Type(v_principal, T_STRING);
+  }
 
-  // Initialize the context
-  kerror = krb5_init_context(&ptr->ctx);
+  // Initialize or borrow the context
+  if(!NIL_P(v_context)){
+    RUBY_KRB5_CONTEXT* ctx_ptr;
 
-  if(kerror)
-    rb_raise(cKrb5Exception, "krb5_init_context: %s", error_message(kerror));
+    if(!rb_obj_is_kind_of(v_context, cKrb5Context))
+      rb_raise(rb_eTypeError, "context must be a Kerberos::Krb5::Context object");
+
+    TypedData_Get_Struct(v_context, RUBY_KRB5_CONTEXT, &rkrb5_context_data_type, ctx_ptr);
+
+    if(!ctx_ptr->ctx)
+      rb_raise(cKrb5Exception, "context is closed");
+
+    ptr->ctx = ctx_ptr->ctx;
+    ptr->rb_context = v_context;
+  }
+  else{
+    kerror = krb5_init_context(&ptr->ctx);
+
+    if(kerror)
+      rb_raise(cKrb5Exception, "krb5_init_context: %s", error_message(kerror));
+
+    ptr->rb_context = Qnil;
+  }
 
   // Convert the principal name to a principal object
-  if(RTEST(v_principal)){
+  if(!NIL_P(v_principal)){
     kerror = krb5_parse_name(
       ptr->ctx,
       StringValueCStr(v_principal),
@@ -127,12 +174,13 @@ static VALUE rkrb5_ccache_close(VALUE self){
   if(ptr->principal)
     krb5_free_principal(ptr->ctx, ptr->principal);
 
-  if(ptr->ctx)
+  if(ptr->ctx && ptr->rb_context == Qnil)
     krb5_free_context(ptr->ctx);
 
   ptr->ccache = NULL;
   ptr->ctx = NULL;
   ptr->principal = NULL;
+  ptr->rb_context = Qnil;
 
   return self;
 }
@@ -228,11 +276,6 @@ static VALUE rkrb5_ccache_primary_principal(VALUE self){
   return v_name;
 }
 
-// Simple wrapper around krb5_cc_get_principal returning a principal name string.
-static VALUE rkrb5_ccache_principal(VALUE self){
-  return rkrb5_ccache_primary_principal(self);
-}
-
 /*
  * call-seq:
  *   ccache.destroy
@@ -264,12 +307,13 @@ static VALUE rkrb5_ccache_destroy(VALUE self){
       if(ptr->principal)
         krb5_free_principal(ptr->ctx, ptr->principal);
 
-      if(ptr->ctx)
+      if(ptr->ctx && ptr->rb_context == Qnil)
         krb5_free_context(ptr->ctx);
 
       ptr->ccache = NULL;
       ptr->ctx = NULL;
       ptr->principal = NULL;
+      ptr->rb_context = Qnil;
 
       rb_raise(cKrb5Exception, "krb5_cc_destroy: %s", error_message(kerror));
     }
@@ -278,12 +322,13 @@ static VALUE rkrb5_ccache_destroy(VALUE self){
   if(ptr->principal)
     krb5_free_principal(ptr->ctx, ptr->principal);
 
-  if(ptr->ctx)
+  if(ptr->ctx && ptr->rb_context == Qnil)
     krb5_free_context(ptr->ctx);
 
   ptr->ccache = NULL;
   ptr->ctx = NULL;
   ptr->principal = NULL;
+  ptr->rb_context = Qnil;
 
   return v_bool;
 }
@@ -329,6 +374,35 @@ static VALUE rkrb5_ccache_dup(VALUE self){
   return newobj;
 }
 
+/*
+ * call-seq:
+ *   ccache.full_name -> String
+ *
+ * Returns the full name of the credential cache, including the type prefix,
+ * e.g. "FILE:/tmp/krb5cc_1000".
+ */
+static VALUE rkrb5_ccache_full_name(VALUE self){
+  RUBY_KRB5_CCACHE* ptr;
+  char *full_name;
+  krb5_error_code kerror;
+  VALUE result;
+
+  TypedData_Get_Struct(self, RUBY_KRB5_CCACHE, &rkrb5_ccache_data_type, ptr);
+
+  if(!ptr->ctx)
+    rb_raise(cKrb5Exception, "no context has been established");
+
+  kerror = krb5_cc_get_full_name(ptr->ctx, ptr->ccache, &full_name);
+
+  if(kerror)
+    rb_raise(cKrb5Exception, "krb5_cc_get_full_name: %s", error_message(kerror));
+
+  result = rb_str_new2(full_name);
+  krb5_free_string(ptr->ctx, full_name);
+
+  return result;
+}
+
 void Init_ccache(void){
   /* The Kerberos::Krb5::CredentialsCache class encapsulates a Kerberos credentials cache. */
   cKrb5CCache = rb_define_class_under(cKrb5, "CredentialsCache", rb_cObject);
@@ -346,10 +420,11 @@ void Init_ccache(void){
   rb_define_method(cKrb5CCache, "cache_type", rkrb5_ccache_get_type, 0);
   rb_define_method(cKrb5CCache, "destroy", rkrb5_ccache_destroy, 0);
   rb_define_method(cKrb5CCache, "primary_principal", rkrb5_ccache_primary_principal, 0);
-  rb_define_method(cKrb5CCache, "principal", rkrb5_ccache_principal, 0);
+  rb_define_method(cKrb5CCache, "full_name", rkrb5_ccache_full_name, 0);
   rb_define_method(cKrb5CCache, "dup", rkrb5_ccache_dup, 0);
   rb_define_alias(cKrb5CCache, "clone", "dup");
 
   // Aliases
   rb_define_alias(cKrb5CCache, "delete", "destroy");
+  rb_define_alias(cKrb5CCache, "principal", "primary_principal");
 }

data/ext/rkerberos/config.c

@@ -6,12 +6,20 @@ VALUE cKeySalt;
 
 
 // TypedData functions for RUBY_KADM5_CONFIG
+static void rkadm5_config_typed_mark(void *ptr) {
+  if (!ptr) return;
+  RUBY_KADM5_CONFIG *c = (RUBY_KADM5_CONFIG *)ptr;
+  if (c->rb_context != Qnil)
+    rb_gc_mark(c->rb_context);
+}
+
 static void rkadm5_config_typed_free(void *ptr) {
   if (!ptr) return;
   RUBY_KADM5_CONFIG *c = (RUBY_KADM5_CONFIG *)ptr;
   if (c->ctx) {
     kadm5_free_config_params(c->ctx, &c->config);
-    krb5_free_context(c->ctx);
+    if (c->rb_context == Qnil)
+      krb5_free_context(c->ctx);
   }
   free(c);
 }
@@ -22,7 +30,7 @@ static size_t rkadm5_config_typed_size(const void *ptr) {
 
 const rb_data_type_t rkadm5_config_data_type = {
   "RUBY_KADM5_CONFIG",
-  {NULL, rkadm5_config_typed_free, rkadm5_config_typed_size,},
+  {rkadm5_config_typed_mark, rkadm5_config_typed_free, rkadm5_config_typed_size,},
   NULL, NULL, RUBY_TYPED_FREE_IMMEDIATELY
 };
 
@@ -30,6 +38,7 @@ const rb_data_type_t rkadm5_config_data_type = {
 static VALUE rkadm5_config_allocate(VALUE klass){
   RUBY_KADM5_CONFIG* ptr = ALLOC(RUBY_KADM5_CONFIG);
   memset(ptr, 0, sizeof(RUBY_KADM5_CONFIG));
+  ptr->rb_context = Qnil;
   return TypedData_Wrap_Struct(klass, &rkadm5_config_data_type, ptr);
 }
 
@@ -43,23 +52,60 @@ static VALUE rkeysalt_new(krb5_enctype enctype, krb5_int32 salttype){
 }
 
 /*
+ * call-seq:
+ *   Kerberos::Kadm5::Config.new(context: nil)
+ *
  * Returns a Kerberos::Kadm5::Config object. This object contains Kerberos
  * admin configuration.
  *
+ * Accepts the following keyword argument:
+ *
+ * - +context+: A Kerberos::Krb5::Context object. If provided, that context is
+ *   used instead of creating a new one via krb5_init_context.
+ *
  * Note that the returned object is frozen. Changes made to the Kerberos
  * admin configuration options after the call will not be reflected in this
  * object.
  */
-static VALUE rkadm5_config_initialize(VALUE self){
+static VALUE rkadm5_config_initialize(int argc, VALUE* argv, VALUE self){
   RUBY_KADM5_CONFIG* ptr;
   krb5_error_code kerror;
+  VALUE v_opts, v_context;
+  ID kw_table[1] = { rb_intern("context") };
+  VALUE kw_vals[1];
 
   TypedData_Get_Struct(self, RUBY_KADM5_CONFIG, &rkadm5_config_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)){
+    RUBY_KRB5_CONTEXT* ctx_ptr;
+
+    if(!rb_obj_is_kind_of(v_context, cKrb5Context))
+      rb_raise(rb_eTypeError, "context must be a Kerberos::Krb5::Context object");
+
+    TypedData_Get_Struct(v_context, RUBY_KRB5_CONTEXT, &rkrb5_context_data_type, ctx_ptr);
+
+    if(!ctx_ptr->ctx)
+      rb_raise(cKrb5Exception, "context is closed");
+
+    ptr->ctx = ctx_ptr->ctx;
+    ptr->rb_context = v_context;
+  }
+  else{
+    kerror = krb5_init_context(&ptr->ctx);
+
+    if(kerror)
+      rb_raise(cKrb5Exception, "krb5_init_context: %s", error_message(kerror));
+
+    ptr->rb_context = Qnil;
+  }
 
   kerror = kadm5_get_config_params(
     ptr->ctx,
@@ -300,7 +346,7 @@ void Init_config(void){
 
   // Initializer
 
-  rb_define_method(cKadm5Config, "initialize", rkadm5_config_initialize, 0);
+  rb_define_method(cKadm5Config, "initialize", rkadm5_config_initialize, -1);
 
   // Methods
 

data/ext/rkerberos/context.c

@@ -53,11 +53,11 @@ static VALUE rkrb5_context_close(VALUE self){
 
 /*
  * call-seq:
- *   Kerberos::Context.new(options = {})
+ *   Kerberos::Krb5::Context.new(secure: false, profile: nil)
  *
  * Creates and returns a new Kerberos::Context object.
  *
- * The options hash may be one or both of the following keys:
+ * The following keyword arguments are supported:
  *
  *   :secure  => true|false           # Use config files only, ignore env variables
  *   :profile => '/path/to/krb5.conf' # Use the specified profile file
@@ -68,11 +68,13 @@ static VALUE rkrb5_context_initialize(int argc, VALUE *argv, VALUE self){
   RUBY_KRB5_CONTEXT* ptr;
   VALUE v_opts;
   VALUE v_secure, v_profile;
+  ID kw_table[2] = { rb_intern("secure"), rb_intern("profile") };
+  VALUE kw_vals[2];
   krb5_error_code kerror;
 
   TypedData_Get_Struct(self, RUBY_KRB5_CONTEXT, &rkrb5_context_data_type, ptr);
 
-  rb_scan_args(argc, argv, "01", &v_opts);
+  rb_scan_args(argc, argv, "0:", &v_opts);
 
   // Default behavior is a normal context that may respect environment.
   if (NIL_P(v_opts)) {
@@ -83,10 +85,9 @@ static VALUE rkrb5_context_initialize(int argc, VALUE *argv, VALUE self){
     return self;
   }
 
-  Check_Type(v_opts, T_HASH);
-
-  v_secure = rb_hash_aref2(v_opts, ID2SYM(rb_intern("secure")));
-  v_profile = rb_hash_aref2(v_opts, ID2SYM(rb_intern("profile")));
+  rb_get_kwargs(v_opts, kw_table, 0, 2, kw_vals);
+  v_secure = kw_vals[0] == Qundef ? Qfalse : kw_vals[0];
+  v_profile = kw_vals[1] == Qundef ? Qnil : kw_vals[1];
 
   /*
    * If a profile path is supplied, load it via profile_init_path() and
@@ -133,6 +134,66 @@ static VALUE rkrb5_context_initialize(int argc, VALUE *argv, VALUE self){
   return self;
 }
 
+/*
+ * call-seq:
+ *   context.default_realm -> String
+ *
+ * Returns the default realm from this context.
+ */
+static VALUE rkrb5_context_default_realm(VALUE self){
+  RUBY_KRB5_CONTEXT* ptr;
+  char* realm;
+  krb5_error_code kerror;
+
+  TypedData_Get_Struct(self, RUBY_KRB5_CONTEXT, &rkrb5_context_data_type, ptr);
+
+  if(!ptr->ctx)
+    rb_raise(cKrb5Exception, "no context has been established");
+
+  kerror = krb5_get_default_realm(ptr->ctx, &realm);
+
+  if(kerror)
+    rb_raise(cKrb5Exception, "krb5_get_default_realm: %s", error_message(kerror));
+
+  VALUE v_realm = rb_str_new2(realm);
+  krb5_free_default_realm(ptr->ctx, realm);
+
+  return v_realm;
+}
+
+/*
+ * call-seq:
+ *   context.default_realm = realm
+ *
+ * Sets the default realm for this context. If +realm+ is nil the default
+ * from krb5.conf is restored.
+ */
+static VALUE rkrb5_context_set_default_realm(VALUE self, VALUE v_realm){
+  RUBY_KRB5_CONTEXT* ptr;
+  char* realm;
+  krb5_error_code kerror;
+
+  TypedData_Get_Struct(self, RUBY_KRB5_CONTEXT, &rkrb5_context_data_type, ptr);
+
+  if(!ptr->ctx)
+    rb_raise(cKrb5Exception, "no context has been established");
+
+  if(NIL_P(v_realm)){
+    realm = NULL;
+  }
+  else{
+    Check_Type(v_realm, T_STRING);
+    realm = StringValueCStr(v_realm);
+  }
+
+  kerror = krb5_set_default_realm(ptr->ctx, realm);
+
+  if(kerror)
+    rb_raise(cKrb5Exception, "krb5_set_default_realm: %s", error_message(kerror));
+
+  return v_realm;
+}
+
 void Init_context(void){
   /* The Kerberos::Krb5::Context class encapsulates a Kerberos context. */
   cKrb5Context = rb_define_class_under(cKrb5, "Context", rb_cObject);
@@ -145,4 +206,6 @@ void Init_context(void){
 
   // Instance Methods
   rb_define_method(cKrb5Context, "close", rkrb5_context_close, 0);
+  rb_define_method(cKrb5Context, "default_realm", rkrb5_context_default_realm, 0);
+  rb_define_method(cKrb5Context, "default_realm=", rkrb5_context_set_default_realm, 1);
 }