vacman_controller 0.2.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 3d98133ea201d0ae3720517f298c719979a91fee
-  data.tar.gz: 1c6ae1f43a4cc27ff8285073ea9d789c0b5c6c62
+SHA256:
+  metadata.gz: 5ddbe7c0b1cf7bc1f64efa3ffa86ea66925dbdb27afa2f68434f0acfd3493fb8
+  data.tar.gz: cf653c109a8ba1bebdae0ecbdef5662978a05e56bfab0ee8a9f223ebc922d6fc
 SHA512:
-  metadata.gz: 6c7e8cec7e94fab24bad7188374685263192721cf70ba66e751ef73e25dd24dbe0baaaed9e46b7a8d2e5fcc1e9f5055c4058857f85bf458e28297093312948e1
-  data.tar.gz: 862c00c0d793e934d9bdb88af6bd7f06ac5cae8264a77a63afd84563f4c642fa9c65a8f5373083fb7e0c4edfa0f126e890f460e2992a147eb7daa4518a09dd88
+  metadata.gz: e81eed72afeda1a0d31053e55cc3eeaa7274e6324f02f8eb528361edd285e61a9a5e15b6a0de21abc8a1659c143f8dfcc93a449c6ebfa61f55e1cbf3aee2b13c
+  data.tar.gz: 97857b1596694fd6d40ff34aa8aad9b88b273b62fe69e2c5d90320c83fd21772599add8ce3f69a8e6094f5b03eed4d90c568fc78c923f9313951b71c8655f9a0

data/ext/vacman_controller/extconf.rb

@@ -17,8 +17,8 @@ append_cflags "-I#{VACMAN_CONTROLLER}/include -Wall -std=c99 -Wno-declaration-af
 append_ldflags "-L#{VACMAN_CONTROLLER}/lib -laal2sdk -Wl,-rpath #{VACMAN_CONTROLLER}/lib"
 
 if find_library('aal2sdk', 'AAL2DPXInit', "#{VACMAN_CONTROLLER}/lib")
-  create_makefile('vacman_controller/vacman_controller')
- else
+  create_makefile('vacman_controller/low_level')
+else
   puts "No libaal2sdk found"
   exit 1
 end

data/ext/vacman_controller/{vacman_controller.c → low_level.c}

@@ -1,60 +1,79 @@
+/*
+ * Vacman Controller wrapper
+ *
+ * This Ruby Extension wraps the VASCO Vacman Controller
+ * library and makes its API accessible to Ruby code.
+ *
+ * (C) 2013 https://github.com/mlankenau
+ * (C) 2019 m.barnaba@ifad.org
+ */
+
 #include <ruby.h>
 #include <string.h>
 #include <aal2sdk.h>
 
-static VALUE e_vacmanerror;  // our ruby exception type
-TKernelParms KernelParms;    // Kernel Params
+
+/* The Vacman default kernel parameters, set up upon extension initialisation. */
+TKernelParms g_KernelParms;
+
+/* Ruby exception type, defined as VacmanController::Error in Ruby land. */
+static VALUE e_VacmanError;
+
 
 /*
- * raise an error and tell wich method failed with wich error code
+ * Raises an Error, decoding the Vacman Controller error code.
  */
-static void vacman_raise_error(const char* method, int error_code) {
-  aat_ascii error_message[100];
-  AAL2GetErrorMsg (error_code, error_message);
-  rb_raise(e_vacmanerror, "%s error %d: %s", method, error_code, error_message);
+static void vacman_library_error(const char* method, int vacman_error_code) {
+  aat_ascii vacman_error_message[100]; // Recommended value in documentation.
+
+  AAL2GetErrorMsg(vacman_error_code, vacman_error_message);
+
+  char error_message[256];
+  snprintf(error_message, 255, "%s error %d: %s", method, vacman_error_code,
+           vacman_error_message);
+
+  VALUE exc = rb_exc_new2(e_VacmanError, error_message);
+  rb_iv_set(exc, "@library_method", rb_str_new2(method));
+  rb_iv_set(exc, "@error_code",     INT2FIX(vacman_error_code));
+  rb_iv_set(exc, "@error_message",  rb_str_new2(vacman_error_message));
+
+  rb_exc_raise(exc);
 }
 
 
 /*
- * convert a ruby hash to TDigipassBlob structure
+ * Use AAL2GetLibraryVersion to obtain library version and return it as a Ruby Hash
  */
-static VALUE rbhash_get_key(VALUE token, const char *property, int type) {
-  VALUE ret = rb_hash_aref(token, rb_str_new2(property));
+static VALUE vacman_library_version(VALUE module) {
+  aat_ascii version[16];
+  aat_int32 version_len = sizeof(version);
 
-  if (ret == Qnil) {
-    rb_raise(e_vacmanerror, "invalid token object given: %s property is nil", property);
-    return Qnil;
-  }
+  aat_ascii bitness[4];
+  aat_int32 bitness_len = sizeof(bitness);
 
-  if (!RB_TYPE_P(ret, type)) {
-    rb_raise(e_vacmanerror, "invalid token object given: %s property is not of the correct type", property);
-    return Qnil;
-  }
+  aat_ascii type[8];
+  aat_int32 type_len = sizeof(type);
 
-  return ret;
-}
+  aat_int32 result = AAL2GetLibraryVersion(version, &version_len, bitness,
+      &bitness_len, type, &type_len);
 
-static void rbhash_to_digipass(VALUE token, TDigipassBlob* dpdata) {
-  if (!RB_TYPE_P(token, T_HASH)) {
-    rb_raise(e_vacmanerror, "invalid token object given, requires an hash");
-    return;
+  if (result != 0) {
+    vacman_library_error("AAL2GetLibraryVersion", result);
+    return Qnil;
   }
 
-  VALUE blob     = rbhash_get_key(token, "blob",     T_STRING);
-  VALUE serial   = rbhash_get_key(token, "serial",   T_STRING);
-  VALUE app_name = rbhash_get_key(token, "app_name", T_STRING);
-  VALUE flag1    = rbhash_get_key(token, "flags1",   T_FIXNUM);
-  VALUE flag2    = rbhash_get_key(token, "flags2",   T_FIXNUM);
-
-  memset(dpdata, 0, sizeof(*dpdata));
+  VALUE hash = rb_hash_new();
+  rb_hash_aset(hash, rb_str_new2("version"), rb_str_new2(version));
+  rb_hash_aset(hash, rb_str_new2("bitness"), rb_str_new2(bitness));
+  rb_hash_aset(hash, rb_str_new2("type"),    rb_str_new2(type));
 
-  strcpy(dpdata->Blob, rb_string_value_cstr(&blob));
-  strncpy(dpdata->Serial, rb_string_value_cstr(&serial), sizeof(dpdata->Serial));
-  strncpy(dpdata->AppName, rb_string_value_cstr(&app_name), sizeof(dpdata->AppName));
-  dpdata->DPFlags[0] = rb_fix2int(flag1);
-  dpdata->DPFlags[1] = rb_fix2int(flag2);
+  return hash;
 }
 
+
+/*
+ * Convert a TDigipassBlob structure into a Ruby Hash
+ */
 static void digipass_to_rbhash(TDigipassBlob* dpdata, VALUE hash) {
   char buffer[256];
 
@@ -74,39 +93,62 @@ static void digipass_to_rbhash(TDigipassBlob* dpdata, VALUE hash) {
   rb_hash_aset(hash, rb_str_new2("flags2"), rb_fix_new(dpdata->DPFlags[1]));
 }
 
+
 /*
- * Get library version and return it as an hash
+ * Gets the given property from the given token hash and raises an Error
+ * if the following conditions occur:
+ *
+ * * The key is not found
+ * * The key is not of the given type
+ *
+ * Otherwise, the value corresponding to the key is returned.
+ *
  */
-static VALUE vacman_library_version(VALUE module) {
-  aat_ascii version[16];
-  aat_int32 version_len = sizeof(version);
+static VALUE rbhash_get_key(VALUE token, const char *property, int type) {
+  VALUE ret = rb_hash_aref(token, rb_str_new2(property));
 
-  aat_ascii bitness[4];
-  aat_int32 bitness_len = sizeof(bitness);
+  if (ret == Qnil) {
+    rb_raise(e_VacmanError, "invalid token object given: %s property is nil", property);
+    return Qnil;
+  }
 
-  aat_ascii type[8];
-  aat_int32 type_len = sizeof(type);
+  if (!RB_TYPE_P(ret, type)) {
+    rb_raise(e_VacmanError, "invalid token object given: %s property is not of the correct type", property);
+    return Qnil;
+  }
 
-  aat_int32 result = AAL2GetLibraryVersion(version, &version_len, bitness,
-      &bitness_len, type, &type_len);
+  return ret;
+}
 
-  if (result != 0) {
-    vacman_raise_error("AAL2GetLibraryVersion", result);
-    return Qnil;
+
+/*
+ * Convert a Ruby Hash with the required keys to a TDigipassBlob structure.
+ */
+static void rbhash_to_digipass(VALUE token, TDigipassBlob* dpdata) {
+  if (!RB_TYPE_P(token, T_HASH)) {
+    rb_raise(e_VacmanError, "invalid token object given, requires an hash");
+    return;
   }
 
-  VALUE hash = rb_hash_new();
-  rb_hash_aset(hash, rb_str_new2("version"), rb_str_new2(version));
-  rb_hash_aset(hash, rb_str_new2("bitness"), rb_str_new2(bitness));
-  rb_hash_aset(hash, rb_str_new2("type"),    rb_str_new2(type));
+  VALUE blob     = rbhash_get_key(token, "blob",     T_STRING);
+  VALUE serial   = rbhash_get_key(token, "serial",   T_STRING);
+  VALUE app_name = rbhash_get_key(token, "app_name", T_STRING);
+  VALUE flag1    = rbhash_get_key(token, "flags1",   T_FIXNUM);
+  VALUE flag2    = rbhash_get_key(token, "flags2",   T_FIXNUM);
 
-  return hash;
+  memset(dpdata, 0, sizeof(*dpdata));
+
+  strcpy(dpdata->Blob, rb_string_value_cstr(&blob));
+  strncpy(dpdata->Serial, rb_string_value_cstr(&serial), sizeof(dpdata->Serial));
+  strncpy(dpdata->AppName, rb_string_value_cstr(&app_name), sizeof(dpdata->AppName));
+  dpdata->DPFlags[0] = rb_fix2int(flag1);
+  dpdata->DPFlags[1] = rb_fix2int(flag2);
 }
 
 
+
 /*
- * generate a password
- * this will not work with all the dpx files available, it must be prepared for it
+ * Generate an OTP from the given token, if the token allows it.
  */
 static VALUE vacman_generate_password(VALUE module, VALUE token) {
   TDigipassBlob dpdata;
@@ -116,11 +158,11 @@ static VALUE vacman_generate_password(VALUE module, VALUE token) {
   aat_ascii password[18];
   memset(password, 0, sizeof(password));
 
-  aat_int32 result = AAL2GenPassword(&dpdata, &KernelParms, password, NULL);
+  aat_int32 result = AAL2GenPassword(&dpdata, &g_KernelParms, password, NULL);
   digipass_to_rbhash(&dpdata, token);
 
   if (result != 0) {
-    vacman_raise_error("AAL2GenPassword", result);
+    vacman_library_error("AAL2GenPassword", result);
     return Qnil;
   }
 
@@ -129,7 +171,7 @@ static VALUE vacman_generate_password(VALUE module, VALUE token) {
 
 
 /*
- * Properties names and IDs registry
+ * Vacman properties names and IDs registry
  */
 struct token_property {
   const char *name;
@@ -192,10 +234,11 @@ static long vacman_get_property_id(char *property_name) {
     }
   }
 
-  rb_raise(e_vacmanerror, "Invalid property name `%s'", property_name);
+  rb_raise(e_VacmanError, "Invalid property name `%s'", property_name);
   return 0;
 }
 
+
 /*
  * Get token property names
  */
@@ -212,7 +255,7 @@ static VALUE vacman_get_token_property_names(void) {
 
 
 /*
- * Get token properties
+ * Get the given property value from the given token.
  */
 static VALUE vacman_get_token_property(VALUE module, VALUE token, VALUE property) {
   TDigipassBlob dpdata;
@@ -220,19 +263,19 @@ static VALUE vacman_get_token_property(VALUE module, VALUE token, VALUE property
 
   aat_ascii value[64];
   aat_int32 property_id = vacman_get_property_id(StringValueCStr(property));
-  aat_int32 result = AAL2GetTokenProperty(&dpdata, &KernelParms, property_id, value);
+  aat_int32 result = AAL2GetTokenProperty(&dpdata, &g_KernelParms, property_id, value);
 
   if (result == 0) {
     return rb_str_new2(value);
   } else {
-    vacman_raise_error("AAL2GetTokenProperty", result);
+    vacman_library_error("AAL2GetTokenProperty", result);
     return Qnil;
   }
 }
 
 
 /*
- * Set token properties
+ * Set the given token property to the given value.
  */
 static VALUE vacman_set_token_property(VALUE module, VALUE token, VALUE property, VALUE rbval) {
   TDigipassBlob dpdata;
@@ -242,75 +285,75 @@ static VALUE vacman_set_token_property(VALUE module, VALUE token, VALUE property
 
   rbhash_to_digipass(token, &dpdata);
 
-  aat_int32 result = AAL2SetTokenProperty(&dpdata, &KernelParms, property_id, value);
+  aat_int32 result = AAL2SetTokenProperty(&dpdata, &g_KernelParms, property_id, value);
 
   digipass_to_rbhash(&dpdata, token);
 
   if (result == 0) {
     return Qtrue;
   } else {
-    vacman_raise_error("AAL2SetTokenProperty", result);
+    vacman_library_error("AAL2SetTokenProperty", result);
     return Qnil;
   }
 }
 
 
 /*
- * Set token static password
+ * Changes the static password on the given token.
  */
 static VALUE vacman_set_token_pin(VALUE module, VALUE token, VALUE pin) {
   TDigipassBlob dpdata;
 
   if (!RB_TYPE_P(pin, T_STRING)) {
-    rb_raise(e_vacmanerror, "invalid pin given, requires a string");
+    rb_raise(e_VacmanError, "invalid pin given, requires a string");
     return Qnil;
   }
 
   rbhash_to_digipass(token, &dpdata);
 
   aat_ascii *passwd = StringValueCStr(pin);
-  aat_int32 result = AAL2ChangeStaticPassword(&dpdata, &KernelParms, passwd, passwd);
+  aat_int32 result = AAL2ChangeStaticPassword(&dpdata, &g_KernelParms, passwd, passwd);
 
   digipass_to_rbhash(&dpdata, token);
 
   if (result == 0) {
     return Qtrue;
   } else {
-    vacman_raise_error("AAL2ChangeStaticPassword", result);
+    vacman_library_error("AAL2ChangeStaticPassword", result);
     return Qnil;
   }
 }
 
 
 /*
- * verify password
- * this is the main usecase, check the use input for authentication
+ * Verifies the given OTP against the given token.
  */
-static VALUE vacman_verify_password(VALUE module, VALUE token, VALUE password ) {
+static VALUE vacman_verify_password(VALUE module, VALUE token, VALUE password) {
   TDigipassBlob dpdata;
 
   rbhash_to_digipass(token, &dpdata);
 
-  aat_int32 result = AAL2VerifyPassword(&dpdata, &KernelParms, rb_string_value_cstr(&password), 0);
+  aat_int32 result = AAL2VerifyPassword(&dpdata, &g_KernelParms, rb_string_value_cstr(&password), 0);
 
   digipass_to_rbhash(&dpdata, token);
 
   if (result == 0)
     return Qtrue;
   else {
-    vacman_raise_error("AAL2VerifyPassword", result);
+    vacman_library_error("AAL2VerifyPassword", result);
     return Qnil;
   }
 }
 
 
-
 /*
- * Import a .DPX file containing token seeds and initialisation values.
+ * Imports a .DPX file containing token seeds and initialisation values.
+ *
+ * Pass the pre-shared key to validate it as the second argument. The
+ * key is not validated by the AAL2 library, if you pass a different
+ * key than the one that was used to create the DPX, you will get back
+ * tokens that generate different OTPs.
  *
- * Pass the pre-shared key to validate it as the second argument. Or if
- * you don't have the key, replace the DC line with one from a file you
- * know the key. Yes.
  */
 static VALUE vacman_import(VALUE module, VALUE filename, VALUE key) {
   TDPXHandle dpx_handle;
@@ -318,11 +361,15 @@ static VALUE vacman_import(VALUE module, VALUE filename, VALUE key) {
   aat_ascii appl_names[13*8];
   aat_int16 token_count;
 
-  aat_int32 result = AAL2DPXInit(&dpx_handle, rb_string_value_cstr(&filename), rb_string_value_cstr(&key),
-      &appl_count, appl_names, &token_count);
+  aat_int32 result = AAL2DPXInit(&dpx_handle,
+                                 rb_string_value_cstr(&filename),
+                                 rb_string_value_cstr(&key),
+                                 &appl_count,
+                                 appl_names,
+                                 &token_count);
 
   if (result != 0) {
-    vacman_raise_error("AAL2DPXInit", result);
+    vacman_library_error("AAL2DPXInit", result);
     return Qnil;
   }
 
@@ -335,7 +382,7 @@ static VALUE vacman_import(VALUE module, VALUE filename, VALUE key) {
 
   while (1) {
     result = AAL2DPXGetToken(&dpx_handle,
-        &KernelParms,
+        &g_KernelParms,
         appl_names,
         sw_out_serial_No,
         sw_out_type,
@@ -344,9 +391,10 @@ static VALUE vacman_import(VALUE module, VALUE filename, VALUE key) {
 
 
     if (result < 0) {
-      vacman_raise_error("AAL2DPXGetToken", result);
+      vacman_library_error("AAL2DPXGetToken", result);
       return Qnil;
     }
+
     if (result == 107) break;
 
     VALUE hash = rb_hash_new();
@@ -361,30 +409,48 @@ static VALUE vacman_import(VALUE module, VALUE filename, VALUE key) {
   return list;
 }
 
+
+/*
+ * Vacman Controller kernel properties
+ */
 struct kernel_property {
   const char *name;
   aat_int32 *value;
   aat_int32 deflt;
 };
 static struct kernel_property kernel_properties[] = {
-  { "ITimeWindow",    &KernelParms.ITimeWindow,    30  },  // Identification Window size in time steps
-  { "STimeWindow",    &KernelParms.STimeWindow,    24  },  // Signature Window size in secs
-  { "DiagLevel",      &KernelParms.DiagLevel,      0   },  // Requested Diagnostic Level
-  { "GMTAdjust",      &KernelParms.GMTAdjust,      0   },  // GMT Time adjustment to perform
-  { "CheckChallenge", &KernelParms.CheckChallenge, 0   },  // Verify Challenge Corrupted (mandatory for Gordian)
-  { "IThreshold",     &KernelParms.IThreshold,     3   },  // Identification Error Threshold
-  { "SThreshold",     &KernelParms.SThreshold,     1   },  // Signature Error Threshold
-  { "ChkInactDays",   &KernelParms.ChkInactDays,   0   },  // Check Inactive Days
-  { "DeriveVector",   &KernelParms.DeriveVector,   0   },  // Vector used to make Data Encryption unique
-  { "SyncWindow",     &KernelParms.SyncWindow,     2   },  // Synchronisation Time Window (h)
-  { "OnLineSG",       &KernelParms.OnLineSG,       2   },  // On line signature
-  { "EventWindow",    &KernelParms.EventWindow,    100 },  // Event Window size in nbr of iterations
-  { "HSMSlotId",      &KernelParms.HSMSlotId,      0   },  // HSM Slot id uses to store DB and Transport Key
+  { "ITimeWindow",    &g_KernelParms.ITimeWindow,    30  },  // Identification Window size in time steps
+  { "STimeWindow",    &g_KernelParms.STimeWindow,    24  },  // Signature Window size in secs
+  { "DiagLevel",      &g_KernelParms.DiagLevel,      0   },  // Requested Diagnostic Level
+  { "GMTAdjust",      &g_KernelParms.GMTAdjust,      0   },  // GMT Time adjustment to perform
+  { "CheckChallenge", &g_KernelParms.CheckChallenge, 0   },  // Verify Challenge Corrupted (mandatory for Gordian)
+  { "IThreshold",     &g_KernelParms.IThreshold,     3   },  // Identification Error Threshold
+  { "SThreshold",     &g_KernelParms.SThreshold,     1   },  // Signature Error Threshold
+  { "ChkInactDays",   &g_KernelParms.ChkInactDays,   0   },  // Check Inactive Days
+  { "DeriveVector",   &g_KernelParms.DeriveVector,   0   },  // Vector used to make Data Encryption unique
+  { "SyncWindow",     &g_KernelParms.SyncWindow,     2   },  // Synchronisation Time Window (h)
+  { "OnLineSG",       &g_KernelParms.OnLineSG,       2   },  // On line signature
+  { "EventWindow",    &g_KernelParms.EventWindow,    100 },  // Event Window size in nbr of iterations
+  { "HSMSlotId",      &g_KernelParms.HSMSlotId,      0   },  // HSM Slot id uses to store DB and Transport Key
 };
 static size_t kernel_properties_count = sizeof(kernel_properties)/sizeof(struct kernel_property);
 
 /*
- * Get kernel property names
+ * Initialise the kernel parameters with their defaults
+ */
+static void vacman_init_kernel_params() {
+  memset(&g_KernelParms, 0, sizeof(g_KernelParms));
+
+  g_KernelParms.ParmCount = 19; /* Number of valid parameters in this list */
+
+  for (size_t i = 0; i < kernel_properties_count; i++) {
+    *kernel_properties[i].value = kernel_properties[i].deflt;
+  }
+}
+
+
+/*
+ * Get kernel parameter names
  */
 static VALUE vacman_get_kernel_property_names(void) {
   VALUE ret = rb_ary_new();
@@ -397,6 +463,7 @@ static VALUE vacman_get_kernel_property_names(void) {
   return ret;
 }
 
+
 /*
  * Set kernel parameter
  */
@@ -411,7 +478,7 @@ static VALUE vacman_set_kernel_param(VALUE module, VALUE paramname, VALUE rbval)
     }
   }
 
-  rb_raise(e_vacmanerror, "Invalid kernel param %s", name);
+  rb_raise(e_VacmanError, "Invalid kernel param %s", name);
   return Qnil;
 }
 
@@ -428,48 +495,36 @@ static VALUE vacman_get_kernel_param(VALUE module, VALUE paramname) {
     }
   }
 
-  rb_raise(e_vacmanerror, "Invalid kernel param %s", name);
+  rb_raise(e_VacmanError, "Invalid kernel param %s", name);
   return Qnil;
 }
 
-/*
- * Init the kernel parameters, with their defaults
- */
-static void init_kernel_params() {
-  memset(&KernelParms, 0, sizeof(TKernelParms));
-
-  KernelParms.ParmCount = 19; /* Number of valid parameters in this list */
-
-  for (size_t i = 0; i < kernel_properties_count; i++) {
-    *kernel_properties[i].value = kernel_properties[i].deflt;
-  }
-}
-
 
 /*
- * rubys entry point to load the extension
+ * Extension entry point
  */
-void Init_vacman_controller(void) {
-  VALUE vacman_module = rb_define_module("VacmanLowLevel");
-
-  e_vacmanerror = rb_define_class("VacmanError", rb_eStandardError);
-  init_kernel_params();
-
-  rb_define_singleton_method(vacman_module, "version",            vacman_library_version, 0);
-
-  rb_define_singleton_method(vacman_module, "import",             vacman_import, 2);
-
-  rb_define_singleton_method(vacman_module, "generate_password",  vacman_generate_password, 1);
-  rb_define_singleton_method(vacman_module, "verify_password",    vacman_verify_password, 2);
-
-  rb_define_singleton_method(vacman_module, "get_kernel_param",   vacman_get_kernel_param, 1);
-  rb_define_singleton_method(vacman_module, "set_kernel_param",   vacman_set_kernel_param, 2);
-
-  rb_define_singleton_method(vacman_module, "get_token_property", vacman_get_token_property, 2);
-  rb_define_singleton_method(vacman_module, "set_token_property", vacman_set_token_property, 3);
-
-  rb_define_singleton_method(vacman_module, "set_token_pin",      vacman_set_token_pin, 2);
-
-  rb_define_singleton_method(vacman_module, "token_property_names", vacman_get_token_property_names, 0);
-  rb_define_singleton_method(vacman_module, "kernel_property_names", vacman_get_kernel_property_names, 0);
+void Init_low_level(void) {
+  VALUE controller = rb_define_module("VacmanController");
+  VALUE lowlevel   = rb_define_module_under(controller, "LowLevel");
+
+  e_VacmanError = rb_define_class_under(controller, "Error", rb_eStandardError);
+
+  vacman_init_kernel_params();
+
+  /* Global methods */
+  rb_define_singleton_method(lowlevel, "library_version",       vacman_library_version, 0);
+  rb_define_singleton_method(lowlevel, "import",                vacman_import, 2);
+
+  /* Token methods */
+  rb_define_singleton_method(lowlevel, "token_property_names",  vacman_get_token_property_names, 0);
+  rb_define_singleton_method(lowlevel, "get_token_property",    vacman_get_token_property, 2);
+  rb_define_singleton_method(lowlevel, "set_token_property",    vacman_set_token_property, 3);
+  rb_define_singleton_method(lowlevel, "generate_password",     vacman_generate_password, 1);
+  rb_define_singleton_method(lowlevel, "verify_password",       vacman_verify_password, 2);
+  rb_define_singleton_method(lowlevel, "set_token_pin",         vacman_set_token_pin, 2);
+
+  /* Kernel methods */
+  rb_define_singleton_method(lowlevel, "kernel_property_names", vacman_get_kernel_property_names, 0);
+  rb_define_singleton_method(lowlevel, "get_kernel_param",      vacman_get_kernel_param, 1);
+  rb_define_singleton_method(lowlevel, "set_kernel_param",      vacman_set_kernel_param, 2);
 }

data/lib/vacman_controller.rb

@@ -1,176 +1,60 @@
-require 'vacman_controller/vacman_controller'
+require 'vacman_controller/low_level'
+require 'vacman_controller/token'
+require 'vacman_controller/kernel'
+require 'vacman_controller/error'
 
-# Provides VACMAN Controller functionality to identify and authorize user via VASCO DIGIPASS tokens.
-#
+# Wraps VACMAN Controller functionality for Ruby.
 #
 module VacmanController
-  extend self
-
-  # Import .dpx file containing the secure token-data
-  #
-  # == Parameters:
-  # filename::
-  #   The path of the .dpx file to load
-  # key::
-  #   The secure key to decrypt the dpx file
-  #
-  # == Returns:
-  # A list of hashes. Each hash contains
-  #   serial: the serial number of the token
-  #   blob:   the blob containing some secret magic data
-  #   app_name: the application name (the security method)
-  #   flags1: some flags
-  #   flags2: more flags
-  #
-  # this hash must be persisted and regained for each call of verify_password and generate_password
-  #
-  def import(filename, key)
-    VacmanLowLevel.import(filename, key)
-  end
-
-
-
-  # Generate a Password for a user. This does the same as hitting the button on your hardware token
-  #
-  # == Parameters:
-  # hash::
-  #   The hash for a specific token (you get these in import)
-  #
-  # == Returns:
-  # The password string. The password is only valid for a period (todo: add method to change the period, currently its 30 seconds)
-  #
-  def generate_password(hash)
-    VacmanLowLevel.generate_password(hash)
-  end
-
-
-
-  # Verify a password. This is the usecase a user sends you a password generated by his token and we have to verify it.
-  #
-  # == Parameters:
-  # hash::
-  #   The hash for a specific token (you get these in import)
-  # pw::
-  #   The password provided by the user
-  #
-  # == Returns:
-  # true if the password is valid, false otherwise
-  #
-  # ATTENTION: it is very important to persist the hash afterwards!!!
-  #
-  def verify_password(hash, pw)
-    VacmanLowLevel.verify_password(hash, pw)
-  end
-
-
-
-  # Gets the available kernel property names
-  #
-  def kernel_property_names
-    @_kernel_property_names ||= VacmanLowLevel.kernel_property_names
-  end
-
-
-
-  # Get a kernel parameter, wich is a basically a setting for vacman controller
-  #
-  # == Parameters:
-  # name::
-  #   the param name. Most TKernelParms struct elements are accessible.
-  #
-  def get_kernel_param(name)
-    VacmanLowLevel.get_kernel_param(name)
-  end
-
-
-
-  # Change a kernel parameter, wich is a basically a setting for vacman controller
-  #
-  # == Parameters:
-  # name::
-  #   the param name. Most TKernelParms struct elements are accessible.
-  # val::
-  #   the fixnum value
-  #
-  def set_kernel_param(name, val)
-    VacmanLowLevel.set_kernel_param(name, val)
-  end
 
-
-
-  # Returns all configured kernel parameters
-  #
-  def get_kernel_all_parameters
-    kernel_property_names.inject({}) do |h, name|
-      h.update(name => (get_kernel_param(name) rescue "ERROR: #$!"))
+  VERSION = '0.5.0'
+
+  class << self
+    # Imports a .dpx file containing the token key material.
+    #
+    # == Parameters:
+    #
+    # filename::
+    #   The path of the .dpx file to load
+    #
+    # key::
+    #   The transport key to decrypt the dpx file
+    #
+    # == Returns:
+    # An Array of Ruby Hashes. Each Hash contains the following keys:
+    #
+    #   serial:   the serial number of the token
+    #   blob:     the blob containing some secret magic data
+    #   app_name: the application name (the security method)
+    #   flags1:   flags
+    #   flags2:   flags
+    #
+    # This is only for low-level usage. For a Ruby API, look at
+    # +VacmanController::Token.import+.
+    #
+    def import(filename, key)
+      VacmanController::LowLevel.import(filename, key)
+
+    rescue VacmanController::Error => e
+      # We handle two undocumented error codes here
+      case e.error_code
+      when -15
+        raise VacmanController::Error, "#{e.library_method} error #{e.error_code}: invalid transport key"
+
+      when -20
+        raise VacmanController::Error, "#{e.library_method} error #{e.error_code}: cannot open DPX file"
+
+      else
+        raise # Sorry, I did my best.
+
+      end
     end
-  end
-
-
-
-  # Gets the available token property names
-  #
-  def token_property_names
-    @_token_property_names ||= VacmanLowLevel.token_property_names
-  end
-
-
-
-  # Get a token single property
-  #
-  # == Parameters:
-  # hash::
-  #   the hash for a specific token (you get these in import)
-  # property::
-  #   the property name. See +token_property_names+
-  #
-  def get_token_property(hash, property)
-    VacmanLowLevel.get_token_property(hash, property)
-  end
 
-
-
-  # Set a token single property
-  #
-  # == Parameters:
-  # hash::
-  #   the hash for a specific token (you get these in import)
-  # property::
-  #   the property name. See +token_property_names+
-  # value::
-  #   the property value. Only values convertible to integer are supported.
-  #
-  # possible names:
-  #
-  #
-  def set_token_property(hash, property, value)
-    VacmanLowLevel.set_token_property(hash, property, value)
-  end
-
-
-
-  # Set a token PIN
-  #
-  # == Parameters:
-  # hash::
-  #   the hash for a specific token (you get these in import)
-  # pin::
-  #   the new PIN. must be a string.
-  #
-  # possible names:
-  #
-  #
-  def set_token_pin(hash, pin)
-    VacmanLowLevel.set_token_pin(hash, pin)
-  end
-
-
-
-  # Returns all properties configured for a token
-  #
-  def get_token_all_properties(hash)
-    token_property_names.inject({}) do |h, name|
-      h.update(name => (get_token_property(hash, name) rescue "ERROR: #$!"))
+    # Returns the +Kernel+ module
+    #
+    def kernel
+      VacmanController::Kernel
     end
   end
+
 end

data/lib/vacman_controller/error.rb

@@ -0,0 +1,16 @@
+module VacmanController
+
+  # Represents a Vacman Controller Library error.
+  #
+  class Error < StandardError
+    # The AAL2 library method that errored
+    attr_reader :library_method
+
+    # The error code returned by the AAL2 library
+    attr_reader :error_code
+
+    # The error message retrieved by the AAL2 library
+    attr_reader :error_message
+  end
+
+end

data/lib/vacman_controller/kernel.rb

@@ -0,0 +1,71 @@
+module VacmanController
+
+  module Kernel
+    class << self
+      # Returns the library version as an hash
+      #
+      def version
+        @_version = VacmanController::LowLevel.library_version
+      end
+
+
+      # Gets the available kernel property names
+      #
+      def property_names
+        @_property_names ||= VacmanController::LowLevel.kernel_property_names.freeze
+      end
+
+
+      # Shows the kernel version, bitness, type and parameters in your
+      # development console.
+      #
+      def inspect
+        "#<#{self.name} version=#{version['version'].inspect} bitness=#{version['bitness'].inspect} "\
+        "type=#{version['type'].inspect} parameters=#{all.inspect}>>"
+      end
+
+
+      # Returns all configured parameters
+      #
+      def all
+        property_names.inject({}) do |h, name|
+          h.update(name => (self[name] rescue "ERROR: #$!"))
+        end
+      end
+      alias to_h all
+
+
+      # Get a Kernel property, that is a runtime parameter of Vacman Controller,
+      # stored in the TKernelParms structure.
+      #
+      # == Parameters:
+      # name::
+      #   The param name. See +property_names+ for a list of available property
+      #   names.
+      #
+      def [](name)
+        VacmanController::LowLevel.get_kernel_param(name)
+      end
+
+
+      # Set a Kernel property.
+      #
+      # == Parameters:
+      # name::
+      #   the param name. See +property_names+ for a list of available property
+      #   names. The Kernel parameters are all int32 properties.
+      #
+      # val::
+      #   the integer value
+      #
+      def []=(name, val)
+        Mutex.synchronize do
+          VacmanController::LowLevel.set_kernel_param(name, val)
+        end
+      end
+
+      Mutex = Thread::Mutex.new
+    end
+  end
+
+end

data/lib/vacman_controller/token.rb

@@ -0,0 +1,182 @@
+require 'vacman_controller/token/properties'
+
+module VacmanController
+
+  class Token
+    # Opens the given dpx_filename with the given transport key and,
+    # if successful, returns Token instances for all tokens in the
+    # DPX file.
+    #
+    def self.import(dpx_filename, transport_key)
+      VacmanController.import(dpx_filename, transport_key).map do |hash|
+        Token.new(hash)
+      end
+    end
+
+
+    # Initialises a Token instance with the given token hash.
+    #
+    def initialize(token_hash)
+      @token_hash = token_hash
+    end
+
+
+    # Return the token serial number
+    #
+    def serial
+      @token_hash.fetch('serial').dup
+    end
+
+
+    # Returns the token Application Name
+    #
+    def app_name
+      @token_hash.fetch('app_name').dup
+    end
+
+
+    # Renders this token in your development console
+    # and in your logs (possibly)
+    #
+    def inspect
+      "#<#{self.class.name} serial=#{serial.inspect} app_name=#{app_name.inspect}>"
+    end
+
+
+    # Returns the token as an hash, that is suitable for passing to
+    # the low-level functions, or for persistance purposes.
+    #
+    def to_h
+      @token_hash
+    end
+
+
+    # Verify a password. This is the usecase a user sends you an OTP
+    # generated by their token and we have to verify it.
+    #
+    # == Parameters:
+    # otp::
+    #   The OTP provided by the user
+    #
+    # == Returns:
+    # true if the password is valid, false otherwise
+    #
+    # ATTENTION: it is very important to persist the token hash
+    # afterwards.
+    #
+    def verify(otp)
+      verify!(otp)
+    rescue VacmanController::Error
+      false
+    end
+
+
+    # Same as verify, but raises a VacmanController::Error if OTP verification
+    # fails.
+    #
+    def verify!(otp)
+      VacmanController::LowLevel.verify_password(@token_hash, otp.to_s)
+    end
+
+
+    # Generate an OTPfrom this token. This does the same as hitting the button
+    # on the hardware token.
+    #
+    # == Returns:
+    # The OTP as a String. The OTP is only valid for a limited time period.
+    #
+    # Not all tokens support OTP generation.
+    #
+    def generate
+      VacmanController::LowLevel.generate_password(@token_hash)
+    end
+
+
+    # Set this token's PIN
+    #
+    # == Parameters:
+    # pin::
+    #   the new PIN. Must be coercible to String.
+    #
+    def set_pin(pin)
+      VacmanController::LowLevel.set_token_pin(@token_hash, pin.to_s)
+    end
+
+
+    ####################################################################
+    ##### Properties Management
+    ####################################################################
+
+    # Enables the PIN on this token
+    #
+    def enable_pin!
+      properties[:pin_enabled] = 1
+      true
+    end
+
+
+    # Disables the PIN on this token
+    #
+    def disable_pin!
+      properties[:pin_enabled] = 2
+      true
+    end
+
+
+    # Forces PIN change on this token
+    #
+    def force_pin_change!
+      properties[:pin_change_forced] = 1
+      true
+    end
+
+
+    # Resets the token error count
+    #
+    def reset_error_count!
+      properties[:error_count] = 0
+      true
+    end
+
+
+    # Sets the "disabled" token status
+    #
+    def disable!
+      properties[:token_status] = 0
+      true
+    end
+
+
+    # Set the primary application enabled status
+    #
+    def enable_primary_only!
+      properties[:token_status] = 1
+      true
+    end
+
+
+    # Set the backup application enabled status
+    #
+    def enable_backup_only!
+      properties[:token_status] = 2
+      true
+    end
+
+
+    # Set both primary and backup application enabled status
+    #
+    def enable!
+      properties[:token_status] = 3
+      true
+    end
+
+
+    # Returns a +Token::Properties+ object giving low-level access to the
+    # token properties.
+    #
+    def properties
+      @_properties = VacmanController::Token::Properties.new(self)
+    end
+  end
+
+end

data/lib/vacman_controller/token/properties.rb

@@ -0,0 +1,193 @@
+module VacmanController
+  class Token
+
+    class Properties
+      class << self
+        # Gets the available token property names
+        #
+        def names
+          @_names ||= VacmanController::LowLevel.token_property_names.freeze
+        end
+      end
+
+
+      def initialize(token)
+        @token = token
+      end
+
+
+      def inspect
+        all.inspect
+      end
+
+
+      def all
+        self.class.names.inject({}) do |h, name|
+          h.update(name => (self[name] rescue "ERROR: #$!"))
+        end
+      end
+      alias to_h all
+
+
+      # Get a Token property
+      #
+      # == Parameters:
+      #
+      # property::
+      #   the property name. See +Token::Properties.names+
+      #
+      def [](name)
+        name  = name.to_s
+        value = VacmanController::LowLevel.get_token_property(@token.to_h, name)
+
+        cast(name, value)
+      end
+
+
+      # Set a Token property
+      #
+      # == Parameters:
+      #
+      # property::
+      #   the property name. See +Token.property_names+
+      #
+      # value::
+      #   the property value. Only values convertible to integer are
+      #   supported.
+      #
+      def []=(name, value)
+        name  = name.to_s
+        value = value.to_i
+
+        check_bounded_property!(name, value)
+
+        VacmanController::LowLevel.set_token_property(@token.to_h, name, value)
+      end
+
+
+      protected
+        def bounded_property?(name)
+          PROPERTY_BOUNDS.key?(name)
+        end
+
+        # The library also does these checks, but we want to present
+        # custom error message to the caller.
+        #
+        def check_bounded_property!(name, value)
+          return unless bounded_property?(name)
+
+          min, max = PROPERTY_BOUNDS.fetch(name)
+
+          if value < min || value > max
+            raise VacmanController::Error,
+              "Invalid #{name} value provided: #{value}. " \
+              "Must be between greater than #{min} and less than #{max}."
+          end
+
+          true
+        end
+
+        PROPERTY_BOUNDS = {
+          'last_time_used'             => [ 631152000, 2147483647 ],
+
+          'last_time_shift'            => [ -100_000, 100_000 ],
+
+          'pin_min_length'             => [ 3, 8 ],
+          'pin_minimum_length'         => [ 3, 8 ],
+
+          'virtual_token_grace_period' => [ 1, 364 ],
+
+          'virtual_token_remain_use'   => [ 0, 254 ],
+
+          'event_value'                => [ 0, 4_294_967_294 ],
+        }
+
+        def cast(property, value)
+
+          # Short-circuit on 'NA'
+          return nil if value == 'NA' or value == 'DISABLE'
+
+          case property
+          when # Integer values
+            'use_count',
+            'pin_len',
+            'pin_length',
+            'pin_min_len',
+            'pin_minimum_length',
+            'last_time_shift',
+            'virtual_token_remain_use',
+            'error_count',
+            'event_value',
+            'last_event_value',
+            'max_dtf_number',
+            'response_len',
+            'response_length',
+            'time_step'
+
+            value.to_i
+
+          when # Boolean values
+            'time_based_algo',
+            'event_based_algo',
+            'pin_supported',
+            'unlock_supported',
+            'pin_ch_on',
+            'pin_change_enabled',
+            'pin_enabled',
+            'pin_ch_forced',
+            'pin_change_forced',
+            'sync_windows',
+            'primary_token_enabled',
+            'virtual_token_supported',
+            'virtual_token_enabled',
+            'derivation_supported',
+            'response_chk',
+            'response_checksum',
+            'triple_des_used',
+            'use_3des'
+
+            case value
+            when 'YES' then true
+            when 'NO' then false
+            end
+
+          when # Date/time values
+            'last_time_used',
+            'virtual_token_grace_period'
+
+            # AAL2 returns UTC values, we add the timezone.
+            Time.strptime("#{value} UTC", '%a %b %d %H:%M:%S %Y %Z')
+
+          when
+            'auth_mode'
+
+            case value
+            when 'RO' then :response_only
+            when 'SG' then :signature_application
+            when 'CR' then :challenge_response
+            when 'MM' then :multi_mode
+            when 'UL' then :unlock_v2
+            else
+              value
+            end
+
+          else # String values
+
+            value
+          end
+        end
+
+      private
+        def method_missing(name, *args, &block)
+          prop, setter = name.to_s.match(/\A(.+?)(=)?\Z/).values_at(1, 2)
+
+          if setter
+            self[prop] = args.first
+          else
+            self[prop]
+          end
+        end
+    end
+
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vacman_controller
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Marcus Lankenau
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-01-07 00:00:00.000000000 Z
+date: 2019-04-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler
@@ -25,7 +25,36 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Authenticate user via vacman controller
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Expose the AAL2 SDK API via a set of Ruby classes optimised for developer
+  happiness
 email:
 - marcus.lankenau@gmail.com
 - marcello.barnaba@gmail.com
@@ -35,9 +64,13 @@ extensions:
 extra_rdoc_files: []
 files:
 - ext/vacman_controller/extconf.rb
-- ext/vacman_controller/vacman_controller.c
+- ext/vacman_controller/low_level.c
 - lib/vacman_controller.rb
-homepage: http://github.com/ifad/vacman_controller
+- lib/vacman_controller/error.rb
+- lib/vacman_controller/kernel.rb
+- lib/vacman_controller/token.rb
+- lib/vacman_controller/token/properties.rb
+homepage: https://github.com/ifad/vacman_controller
 licenses: []
 metadata: {}
 post_install_message: 
@@ -56,8 +89,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.2.1
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
-summary: Access to the vacman controller library
+summary: Ruby layer to access VASCO Vacman Controller functions
 test_files: []