rkerberos 0.2.3 → 0.3.0

data/ext/rkerberos/keytab.c

@@ -4,6 +4,13 @@ VALUE cKrb5Keytab, cKrb5KeytabException;
 
 
 // TypedData functions for RUBY_KRB5_KEYTAB
+static void rkrb5_keytab_typed_mark(void *ptr) {
+  if (!ptr) return;
+  RUBY_KRB5_KEYTAB *kt = (RUBY_KRB5_KEYTAB *)ptr;
+  if (kt->rb_context != Qnil)
+    rb_gc_mark(kt->rb_context);
+}
+
 void rkrb5_keytab_typed_free(void *ptr) {
   if (!ptr) return;
   RUBY_KRB5_KEYTAB *kt = (RUBY_KRB5_KEYTAB *)ptr;
@@ -11,7 +18,7 @@ void rkrb5_keytab_typed_free(void *ptr) {
     krb5_kt_close(kt->ctx, kt->keytab);
   if (kt->ctx)
     krb5_free_cred_contents(kt->ctx, &kt->creds);
-  if (kt->ctx)
+  if (kt->ctx && kt->rb_context == Qnil)
     krb5_free_context(kt->ctx);
   free(kt);
 }
@@ -23,13 +30,14 @@ size_t rkrb5_keytab_typed_size(const void *ptr) {
 // Must NOT be static so it is exported
 const rb_data_type_t rkrb5_keytab_data_type = {
   "RUBY_KRB5_KEYTAB",
-  {NULL, rkrb5_keytab_typed_free, rkrb5_keytab_typed_size,},
+  {rkrb5_keytab_typed_mark, rkrb5_keytab_typed_free, rkrb5_keytab_typed_size,},
   NULL, NULL, RUBY_TYPED_FREE_IMMEDIATELY
 };
 
 VALUE rkrb5_keytab_allocate(VALUE klass){
   RUBY_KRB5_KEYTAB* ptr = ALLOC(RUBY_KRB5_KEYTAB);
   memset(ptr, 0, sizeof(RUBY_KRB5_KEYTAB));
+  ptr->rb_context = Qnil;
   return TypedData_Wrap_Struct(klass, &rkrb5_keytab_data_type, ptr);
 }
 
@@ -167,109 +175,189 @@ static VALUE rkrb5_keytab_close(VALUE self){
   if(ptr->ctx)
     krb5_free_cred_contents(ptr->ctx, &ptr->creds);
 
-  if(ptr->ctx)
+  if(ptr->ctx && ptr->rb_context == Qnil)
     krb5_free_context(ptr->ctx);
 
   ptr->ctx = NULL;
+  ptr->rb_context = Qnil;
 
   return Qtrue;
 }
 
 /*
-static VALUE rkrb5_keytab_remove_entry(int argc, VALUE* argv, VALUE self){
+ * call-seq:
+ *   keytab.add_entry(principal:, password:, vno: 1, enctype: 18)
+ *
+ * Add a new entry to the keytab for the given +principal+ string.
+ *
+ * A key is derived from +password+ (and the principal-based salt) using
+ * +krb5_c_string_to_key+, so the resulting key will match what the KDC
+ * would generate for the same password.
+ *
+ * Options:
+ *   principal:: A Kerberos principal name string (required).
+ *   password::  The password used to derive the key (required).
+ *   vno::       Key version number (default 1).
+ *   enctype::   Encryption type as an integer (default 18,
+ *               aes256-cts-hmac-sha1-96).
+ *
+ * Returns +self+.
+ */
+static VALUE rkrb5_keytab_add_entry(int argc, VALUE* argv, VALUE self){
   RUBY_KRB5_KEYTAB* ptr;
   krb5_error_code kerror;
   krb5_keytab_entry entry;
-  char* name;
-  VALUE v_name, v_vno, v_enctype;
+  krb5_data pwd_data, salt;
+  VALUE v_opts, v_principal, v_password, v_vno, v_enctype;
+  ID kw_table[4] = { rb_intern("principal"), rb_intern("password"), rb_intern("vno"), rb_intern("enctype") };
+  VALUE kw_vals[4];
 
   TypedData_Get_Struct(self, RUBY_KRB5_KEYTAB, &rkrb5_keytab_data_type, ptr);
 
-  rb_scan_args(argc, argv, "12", &v_name, &v_vno, &v_enctype);
+  if(!ptr->ctx)
+    rb_raise(cKrb5Exception, "no context has been established");
 
-  Check_Type(v_name, T_STRING);
+  rb_scan_args(argc, argv, "0:", &v_opts);
 
-  name = StringValueCStr(v_name);
+  if(NIL_P(v_opts))
+    v_opts = rb_hash_new();
 
-  if(!ptr->ctx)
-    rb_raise(cKrb5Exception, "no context has been established");
+  rb_get_kwargs(v_opts, kw_table, 2, 2, kw_vals);
+  v_principal = kw_vals[0];
+  v_password = kw_vals[1];
+  v_vno = kw_vals[2] == Qundef ? Qnil : kw_vals[2];
+  v_enctype = kw_vals[3] == Qundef ? Qnil : kw_vals[3];
+
+  Check_Type(v_principal, T_STRING);
+  Check_Type(v_password, T_STRING);
 
-  kerror = krb5_parse_name(ptr->ctx, name, &entry.principal);
+  memset(&entry, 0, sizeof(entry));
+
+  kerror = krb5_parse_name(ptr->ctx, StringValueCStr(v_principal), &entry.principal);
 
   if(kerror)
     rb_raise(cKrb5Exception, "krb5_parse_name: %s", error_message(kerror));
 
-  if(NIL_P(v_vno))
-    entry.vno = 0;
-  else
-    entry.vno = NUM2INT(v_vno);
+  entry.vno = NIL_P(v_vno) ? 1 : NUM2INT(v_vno);
+  entry.key.enctype = NIL_P(v_enctype) ? ENCTYPE_AES256_CTS_HMAC_SHA1_96 : NUM2INT(v_enctype);
+  entry.timestamp = time(NULL);
 
-  if(NIL_P(v_enctype))
-    entry.key.enctype = 0;
-  else
-    entry.key.enctype = NUM2INT(v_enctype);
+  // Derive the salt from the principal
+  kerror = krb5_principal2salt(ptr->ctx, entry.principal, &salt);
 
-  entry.key.length = 16;
+  if(kerror){
+    krb5_free_principal(ptr->ctx, entry.principal);
+    rb_raise(cKrb5Exception, "krb5_principal2salt: %s", error_message(kerror));
+  }
 
-  kerror = krb5_kt_remove_entry(
-    ptr->ctx,
-    ptr->keytab,
-    &entry
-  );
+  // Derive key from password + salt
+  pwd_data.data   = StringValuePtr(v_password);
+  pwd_data.length = (unsigned int)RSTRING_LEN(v_password);
+
+  kerror = krb5_c_string_to_key(ptr->ctx, entry.key.enctype, &pwd_data, &salt, &entry.key);
+
+  krb5_free_data_contents(ptr->ctx, &salt);
+
+  if(kerror){
+    krb5_free_principal(ptr->ctx, entry.principal);
+    rb_raise(cKrb5Exception, "krb5_c_string_to_key: %s", error_message(kerror));
+  }
+
+  kerror = krb5_kt_add_entry(ptr->ctx, ptr->keytab, &entry);
+
+  krb5_free_keyblock_contents(ptr->ctx, &entry.key);
+  krb5_free_principal(ptr->ctx, entry.principal);
 
   if(kerror)
-    rb_raise(cKrb5KeytabException, "krb5_kt_remove_entry: %s", error_message(kerror));
+    rb_raise(cKrb5KeytabException, "krb5_kt_add_entry: %s", error_message(kerror));
 
   return self;
 }
 
-static VALUE rkrb5_keytab_add_entry(int argc, VALUE* argv, VALUE self){
+/*
+ * call-seq:
+ *   keytab.remove_entry(principal:, vno: 0, enctype: 0)
+ *
+ * Remove entries from the keytab that match the given +principal+ string,
+ * +vno+, and +enctype+.
+ *
+ * A +vno+ of 0 (the default) matches any version number.
+ * An +enctype+ of 0 (the default) matches any encryption type.
+ *
+ * When both +vno+ and +enctype+ are 0 (the defaults), all entries for
+ * the +principal+ are removed.
+ *
+ * Options:
+ *   principal:: A Kerberos principal name string (required).
+ *   vno::       Key version number to match, 0 for any (default 0).
+ *   enctype::   Encryption type to match, 0 for any (default 0).
+ *
+ * Returns +self+.
+ */
+static VALUE rkrb5_keytab_remove_entry(int argc, VALUE* argv, VALUE self){
   RUBY_KRB5_KEYTAB* ptr;
   krb5_error_code kerror;
-  krb5_keytab_entry entry;
-  char* name;
-  VALUE v_name, v_vno, v_enctype;
+  krb5_keytab_entry found_entry;
+  krb5_principal match_princ;
+  krb5_kvno match_vno;
+  krb5_enctype match_enctype;
+  int removed = 0;
+  VALUE v_opts, v_principal, v_vno, v_enctype;
+  ID kw_table[3] = { rb_intern("principal"), rb_intern("vno"), rb_intern("enctype") };
+  VALUE kw_vals[3];
 
   TypedData_Get_Struct(self, RUBY_KRB5_KEYTAB, &rkrb5_keytab_data_type, ptr);
 
-  rb_scan_args(argc, argv, "12", &v_name, &v_vno, &v_enctype);
+  if(!ptr->ctx)
+    rb_raise(cKrb5Exception, "no context has been established");
 
-  Check_Type(v_name, T_STRING);
+  rb_scan_args(argc, argv, "0:", &v_opts);
 
-  name = StringValueCStr(v_name);
+  if(NIL_P(v_opts))
+    v_opts = rb_hash_new();
 
-  if(!ptr->ctx)
-    rb_raise(cKrb5Exception, "no context has been established");
+  rb_get_kwargs(v_opts, kw_table, 1, 2, kw_vals);
+  v_principal = kw_vals[0];
+  v_vno = kw_vals[1] == Qundef ? Qnil : kw_vals[1];
+  v_enctype = kw_vals[2] == Qundef ? Qnil : kw_vals[2];
 
-  kerror = krb5_parse_name(ptr->ctx, name, &entry.principal);
+  Check_Type(v_principal, T_STRING);
+
+  kerror = krb5_parse_name(ptr->ctx, StringValueCStr(v_principal), &match_princ);
 
   if(kerror)
     rb_raise(cKrb5Exception, "krb5_parse_name: %s", error_message(kerror));
 
-  if(NIL_P(v_vno))
-    entry.vno = 0;
-  else
-    entry.vno = NUM2INT(v_vno);
+  match_vno = NIL_P(v_vno) ? 0 : NUM2INT(v_vno);
+  match_enctype = NIL_P(v_enctype) ? 0 : NUM2INT(v_enctype);
 
-  if(NIL_P(v_enctype))
-    entry.key.enctype = 0;
-  else
-    entry.key.enctype = NUM2INT(v_enctype);
+  // Retrieve the full entry via krb5_kt_get_entry and then pass the
+  // complete struct to krb5_kt_remove_entry so all fields match exactly.
+  // Loop to remove every matching entry when vno/enctype are wildcards.
+  while(1){
+    kerror = krb5_kt_get_entry(
+      ptr->ctx, ptr->keytab, match_princ,
+      match_vno, match_enctype, &found_entry
+    );
 
-  entry.key.length = 16;
+    if(kerror){
+      krb5_free_principal(ptr->ctx, match_princ);
+      if(removed)
+        return self;
+      rb_raise(cKrb5KeytabException, "krb5_kt_remove_entry: %s", error_message(kerror));
+    }
 
-  kerror = krb5_kt_add_entry(
-    ptr->ctx,
-    ptr->keytab,
-    &entry
-  );
+    kerror = krb5_kt_remove_entry(ptr->ctx, ptr->keytab, &found_entry);
+    krb5_kt_free_entry(ptr->ctx, &found_entry);
 
-  if(kerror)
-    rb_raise(cKrb5KeytabException, "krb5_kt_add_entry: %s", error_message(kerror));
+    if(kerror){
+      krb5_free_principal(ptr->ctx, match_princ);
+      rb_raise(cKrb5KeytabException, "krb5_kt_remove_entry: %s", error_message(kerror));
+    }
 
-  return self;
+    removed = 1;
+  }
 }
-*/
 
 /*
  * call-seq:
@@ -430,7 +518,7 @@ static VALUE rkrb5_keytab_dup(VALUE self){
 
 /*
  * call-seq:
- *   Kerberos::Krb5::Keytab.new(name = nil)
+ *   Kerberos::Krb5::Keytab.new(name: nil, context: nil)
  *
  * Creates and returns a new Kerberos::Krb5::Keytab object. This initializes
  * the context and keytab for future method calls on that object.
@@ -439,28 +527,66 @@ static VALUE rkrb5_keytab_dup(VALUE self){
  * name is used. If a +name+ is provided it must be in the form 'type:residual'
  * where 'type' is a type known to the Kerberos library.
  *
+ * An optional +context+ keyword argument may be provided. If given, it must
+ * be a Kerberos::Krb5::Context object and will be used instead of creating
+ * a new context via krb5_init_context.
+ *
  * Examples:
  *
  *   # Using the default keytab
  *   keytab = Kerberos::Krb5::Keytab.new
  *
  *   # Using an explicit keytab
- *   keytab = Kerberos::Krb5::Keytab.new('FILE:/etc/krb5.keytab')
+ *   keytab = Kerberos::Krb5::Keytab.new(name: 'FILE:/etc/krb5.keytab')
+ *
+ *   # Using a custom context
+ *   ctx = Kerberos::Krb5::Context.new
+ *   keytab = Kerberos::Krb5::Keytab.new(name: 'FILE:/etc/krb5.keytab', context: ctx)
  */
 static VALUE rkrb5_keytab_initialize(int argc, VALUE* argv, VALUE self){
   RUBY_KRB5_KEYTAB* ptr;
   krb5_error_code kerror;
   char keytab_name[MAX_KEYTAB_NAME_LEN];
   VALUE v_keytab_name = Qnil;
+  VALUE v_opts = Qnil;
+  VALUE v_context = Qnil;
+  ID kw_table[2] = { rb_intern("name"), rb_intern("context") };
+  VALUE kw_vals[2];
 
   TypedData_Get_Struct(self, RUBY_KRB5_KEYTAB, &rkrb5_keytab_data_type, ptr);
 
-  rb_scan_args(argc, argv, "01", &v_keytab_name);
+  rb_scan_args(argc, argv, "0:", &v_opts);
 
-  kerror = krb5_init_context(&ptr->ctx);
+  if(NIL_P(v_opts))
+    v_opts = rb_hash_new();
 
-  if(kerror)
-    rb_raise(cKrb5Exception, "krb5_init_context: %s", error_message(kerror));
+  rb_get_kwargs(v_opts, kw_table, 0, 2, kw_vals);
+  v_keytab_name = kw_vals[0] == Qundef ? Qnil : kw_vals[0];
+  v_context = kw_vals[1] == Qundef ? Qnil : kw_vals[1];
+
+  // Initialize or borrow the context
+  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;
+  }
 
   // Use the default keytab name if one isn't provided.
   if(NIL_P(v_keytab_name)){
@@ -616,6 +742,26 @@ static VALUE rkrb5_s_keytab_foreach(int argc, VALUE* argv, VALUE klass){
   return Qnil;
 }
 
+/*
+ * call-seq:
+ *   keytab.have_content? -> true or false
+ *
+ * Returns true if the keytab exists and contains entries, false otherwise.
+ */
+static VALUE rkrb5_keytab_have_content(VALUE self){
+  RUBY_KRB5_KEYTAB* ptr;
+  krb5_error_code kerror;
+
+  TypedData_Get_Struct(self, RUBY_KRB5_KEYTAB, &rkrb5_keytab_data_type, ptr);
+
+  if(!ptr->ctx)
+    rb_raise(cKrb5Exception, "no context has been established");
+
+  kerror = krb5_kt_have_content(ptr->ctx, ptr->keytab);
+
+  return kerror ? Qfalse : Qtrue;
+}
+
 void Init_keytab(void){
   /* The Kerberos::Krb5::Keytab class encapsulates a Kerberos keytab. */
   cKrb5Keytab = rb_define_class_under(cKrb5, "Keytab", rb_cObject);
@@ -644,11 +790,11 @@ void Init_keytab(void){
   rb_define_method(cKrb5Keytab, "keytab_name", rkrb5_keytab_get_name, 0);
   rb_define_method(cKrb5Keytab, "keytab_type", rkrb5_keytab_get_type, 0);
   rb_define_method(cKrb5Keytab, "dup", rkrb5_keytab_dup, 0);
+  rb_define_method(cKrb5Keytab, "have_content?", rkrb5_keytab_have_content, 0);
   rb_define_alias(cKrb5Keytab, "clone", "dup");
 
-  // TODO: Move these into Kadm5 and/or figure out how to set the vno properly.
-  // rb_define_method(cKrb5Keytab, "add_entry", rkrb5_keytab_add_entry, -1);
-  // rb_define_method(cKrb5Keytab, "remove_entry", rkrb5_keytab_remove_entry, -1);
+  rb_define_method(cKrb5Keytab, "add_entry", rkrb5_keytab_add_entry, -1);
+  rb_define_method(cKrb5Keytab, "remove_entry", rkrb5_keytab_remove_entry, -1);
 
   // Accessors
 

data/ext/rkerberos/policy.c

@@ -32,12 +32,12 @@ static VALUE rkadm5_policy_allocate(VALUE klass){
 
 /*
  * call-seq:
- *   Kerberos::Kadm5::Policy.new(options)
+ *   Kerberos::Kadm5::Policy.new(name:, min_life: nil, max_life: nil,
+ *     min_length: nil, min_classes: nil, history_num: nil)
  *
- * Returns a new policy object using +options+ you choose to pass, where
- * the +options+ argument is a hash. This does NOT actually create the policy
- * object within Kerberos. To do that pass your Policy object to the
- * Kadm5.create_policy method.
+ * Returns a new policy object using the keyword arguments you choose to pass.
+ * This does NOT actually create the policy within Kerberos. To do that pass
+ * your Policy object to the Kadm5.create_policy method.
  *
  * The possible options are:
  *
@@ -50,32 +50,34 @@ static VALUE rkadm5_policy_allocate(VALUE klass){
  *
  * If you do not provide a :name then an ArgumentError will be raised.
  */
-static VALUE rkadm5_policy_init(VALUE self, VALUE v_options){
+static VALUE rkadm5_policy_init(int argc, VALUE* argv, VALUE self){
   RUBY_KADM5_POLICY* ptr;
+  VALUE v_options;
   VALUE v_name, v_minlife, v_maxlife, v_minlength;
   VALUE v_minclasses, v_historynum;
+  ID kw_table[6] = {
+    rb_intern("name"), rb_intern("min_life"), rb_intern("max_life"),
+    rb_intern("min_length"), rb_intern("min_classes"), rb_intern("history_num")
+  };
+  VALUE kw_vals[6];
 
   TypedData_Get_Struct(self, RUBY_KADM5_POLICY, &rkadm5_policy_data_type, ptr);
 
-  Check_Type(v_options, T_HASH);
+  rb_scan_args(argc, argv, "0:", &v_options);
 
-  if(RTEST(rb_funcall(v_options, rb_intern("empty?"), 0)))
-    rb_raise(rb_eArgError, "no policy options provided");
+  if(NIL_P(v_options))
+    v_options = rb_hash_new();
 
-  v_name       = rb_hash_aref2(v_options, rb_str_new_cstr("name"));
-  v_minlife    = rb_hash_aref2(v_options, rb_str_new_cstr("min_life"));
-  v_maxlife    = rb_hash_aref2(v_options, rb_str_new_cstr("max_life"));
-  v_minlength  = rb_hash_aref2(v_options, rb_str_new_cstr("min_length"));
-  v_minclasses = rb_hash_aref2(v_options, rb_str_new_cstr("min_classes"));
-  v_historynum = rb_hash_aref2(v_options, rb_str_new_cstr("history_num"));
+  rb_get_kwargs(v_options, kw_table, 1, 5, kw_vals);
+  v_name = kw_vals[0];
+  v_minlife = kw_vals[1] == Qundef ? Qnil : kw_vals[1];
+  v_maxlife = kw_vals[2] == Qundef ? Qnil : kw_vals[2];
+  v_minlength = kw_vals[3] == Qundef ? Qnil : kw_vals[3];
+  v_minclasses = kw_vals[4] == Qundef ? Qnil : kw_vals[4];
+  v_historynum = kw_vals[5] == Qundef ? Qnil : kw_vals[5];
 
-  if(NIL_P(v_name)){
-    rb_raise(rb_eArgError, "name policy option is mandatory");
-  }
-  else{
-    ptr->policy.policy = StringValueCStr(v_name);
-    rb_iv_set(self, "@policy", v_name);
-  }
+  ptr->policy.policy = StringValueCStr(v_name);
+  rb_iv_set(self, "@policy", v_name);
 
   if(!NIL_P(v_minlife)){
     ptr->policy.pw_min_life = NUM2LONG(v_minlife);
@@ -171,7 +173,7 @@ void Init_policy(void){
 
   // Initialization Function
 
-  rb_define_method(cKadm5Policy, "initialize", rkadm5_policy_init, 1);
+  rb_define_method(cKadm5Policy, "initialize", rkadm5_policy_init, -1);
 
   // Instance methods
 

data/ext/rkerberos/principal.c

@@ -4,12 +4,19 @@ VALUE cKrb5Principal;
 
 
 // TypedData functions for RUBY_KRB5_PRINC
+static void rkrb5_princ_typed_mark(void *ptr) {
+  if (!ptr) return;
+  RUBY_KRB5_PRINC *p = (RUBY_KRB5_PRINC *)ptr;
+  if (p->rb_context != Qnil)
+    rb_gc_mark(p->rb_context);
+}
+
 static void rkrb5_princ_typed_free(void *ptr) {
   if (!ptr) return;
   RUBY_KRB5_PRINC *p = (RUBY_KRB5_PRINC *)ptr;
   if (p->principal)
     krb5_free_principal(p->ctx, p->principal);
-  if (p->ctx)
+  if (p->ctx && p->rb_context == Qnil)
     krb5_free_context(p->ctx);
   free(p);
 }
@@ -20,7 +27,7 @@ static size_t rkrb5_princ_typed_size(const void *ptr) {
 
 static const rb_data_type_t rkrb5_princ_data_type = {
   "RUBY_KRB5_PRINC",
-  {NULL, rkrb5_princ_typed_free, rkrb5_princ_typed_size,},
+  {rkrb5_princ_typed_mark, rkrb5_princ_typed_free, rkrb5_princ_typed_size,},
   NULL, NULL, RUBY_TYPED_FREE_IMMEDIATELY
 };
 
@@ -28,34 +35,78 @@ static const rb_data_type_t rkrb5_princ_data_type = {
 static VALUE rkrb5_princ_allocate(VALUE klass){
   RUBY_KRB5_PRINC* ptr = ALLOC(RUBY_KRB5_PRINC);
   memset(ptr, 0, sizeof(RUBY_KRB5_PRINC));
+  ptr->rb_context = Qnil;
   return TypedData_Wrap_Struct(klass, &rkrb5_princ_data_type, ptr);
 }
 
 /*
  * call-seq:
- *   Kerberos::Krb5::Principal.new(name)
+ *   Kerberos::Krb5::Principal.new(name: nil, context: nil)
  *
  * Creates and returns a new Krb5::Principal object. If a block is provided
  * then it yields itself.
  *
+ * A principal +name+ may be provided as a keyword argument. If not provided
+ * or nil, the principal attribute will be nil.
+ *
+ * An optional +context+ keyword argument may be provided. If given, it must
+ * be a Kerberos::Krb5::Context object and will be used instead of creating
+ * a new context via krb5_init_context.
+ *
  * Example:
  *
- *   principal1 = Kerberos::Krb5::Principal.new('Jon')
+ *   principal1 = Kerberos::Krb5::Principal.new(name: 'Jon')
  *
- *   principal2 = Kerberos::Krb5::Principal.new('Jon') do |pr|
+ *   principal2 = Kerberos::Krb5::Principal.new(name: 'Jon') do |pr|
  *     pr.expire_time = Time.now + 20000
  *   end
+ *
+ *   ctx = Kerberos::Krb5::Context.new
+ *   principal3 = Kerberos::Krb5::Principal.new(name: 'Jon', context: ctx)
  */
-static VALUE rkrb5_princ_initialize(VALUE self, VALUE v_name){
+static VALUE rkrb5_princ_initialize(int argc, VALUE* argv, VALUE self){
   RUBY_KRB5_PRINC* ptr;
   krb5_error_code kerror;
+  VALUE v_opts = Qnil;
+  VALUE v_name = Qnil;
+  VALUE v_context = Qnil;
+  ID kw_table[2] = { rb_intern("name"), rb_intern("context") };
+  VALUE kw_vals[2];
 
   TypedData_Get_Struct(self, RUBY_KRB5_PRINC, &rkrb5_princ_data_type, ptr);
 
-  kerror = krb5_init_context(&ptr->ctx);
+  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, 2, kw_vals);
+  v_name = kw_vals[0] == Qundef ? Qnil : kw_vals[0];
+  v_context = kw_vals[1] == Qundef ? Qnil : kw_vals[1];
+
+  // Initialize or borrow the context
+  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(kerror)
-    rb_raise(cKrb5Exception, "krb5_init_context failed: %s", error_message(kerror));
+    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 failed: %s", error_message(kerror));
+
+    ptr->rb_context = Qnil;
+  }
 
   if(NIL_P(v_name)){
     rb_iv_set(self, "@principal", Qnil);
@@ -233,6 +284,51 @@ static VALUE rkrb5_princ_inspect(VALUE self){
   return v_str;
 }
 
+/*
+ * call-seq:
+ *   principal.principal_type -> Integer
+ *
+ * Returns the type of the principal as an integer, e.g.
+ * KRB5_NT_PRINCIPAL (1), KRB5_NT_SRV_HST (2), etc.
+ */
+static VALUE rkrb5_princ_get_type(VALUE self){
+  RUBY_KRB5_PRINC* ptr;
+
+  TypedData_Get_Struct(self, RUBY_KRB5_PRINC, &rkrb5_princ_data_type, ptr);
+
+  if(!ptr->principal)
+    rb_raise(cKrb5Exception, "no principal has been established");
+
+  return INT2FIX(krb5_princ_type(ptr->ctx, ptr->principal));
+}
+
+/*
+ * call-seq:
+ *   principal.components -> Array
+ *
+ * Returns an array of the component strings that make up this principal
+ * name (excluding the realm). For example, "admin/instance@REALM" would
+ * return ["admin", "instance"].
+ */
+static VALUE rkrb5_princ_components(VALUE self){
+  RUBY_KRB5_PRINC* ptr;
+
+  TypedData_Get_Struct(self, RUBY_KRB5_PRINC, &rkrb5_princ_data_type, ptr);
+
+  if(!ptr->principal)
+    rb_raise(cKrb5Exception, "no principal has been established");
+
+  int n = krb5_princ_size(ptr->ctx, ptr->principal);
+  VALUE v_array = rb_ary_new_capa(n);
+
+  for(int i = 0; i < n; i++){
+    krb5_data* component = krb5_princ_component(ptr->ctx, ptr->principal, i);
+    rb_ary_push(v_array, rb_str_new(component->data, component->length));
+  }
+
+  return v_array;
+}
+
 void Init_principal(void){
   /* The Kerberos::Krb5::Principal class encapsulates a Kerberos principal. */
   cKrb5Principal = rb_define_class_under(cKrb5, "Principal", rb_cObject);
@@ -243,7 +339,7 @@ void Init_principal(void){
 
   // Constructor
 
-  rb_define_method(cKrb5Principal, "initialize", rkrb5_princ_initialize, 1);
+  rb_define_method(cKrb5Principal, "initialize", rkrb5_princ_initialize, -1);
 
   // Instance Methods
 
@@ -251,6 +347,8 @@ void Init_principal(void){
   rb_define_method(cKrb5Principal, "realm", rkrb5_princ_get_realm, 0);
   rb_define_method(cKrb5Principal, "realm=", rkrb5_princ_set_realm, 1);
   rb_define_method(cKrb5Principal, "==", rkrb5_princ_equal, 1);
+  rb_define_method(cKrb5Principal, "principal_type", rkrb5_princ_get_type, 0);
+  rb_define_method(cKrb5Principal, "components", rkrb5_princ_components, 0);
 
   // Attributes