Module: RSA::SecurID

Defined in:

lib/securid.rb,
ext/securid/securid.c

Defined Under Namespace

Classes: SecurIDError, Session

Class Method Summary

• .agent_status ⇒ Hash

  Fetches the status of the RSA agent.

• .authenticate(username, password) ⇒ Boolean deprecated Deprecated.

  Use Session#authenticate instead.

Class Method Details

.agent_status ⇒ Hash

Fetches the status of the RSA agent. This includes details about the RSA ACE server the agent is communicating with. NOTE: this method can not be called in test mode unless there is an actual RSA agent present. The returned status hash is a ruby version of the S_status_display struct populated by AceAgentStatusDisplay, and any questions about the meaning of its fields should be directed there.

Examples:

Returned Status Hash

{
  config_version: 15,
  max_servers: 1,
  max_replicas: 4,
  max_retries: 5,
  base_timeout: 5,
  use_des: 1,
  trusted: 0,
  port: 5500,
  service_protocol_version: 0,
  service_name: "securid",
  service_protocol: "udp",
  server_release_number: {
    major: 0,
    minor: 0,
    patch: 0,
    build: 0
  },
  servers: [
    {
      hostname: "rsa.example.com",
      address: "192.168.0.1",
      active_address: nil,
      aliases: [],
      display_status: {
        primary: true,
        master: true,
        slave: false,
        selectable: false,
        emergency: false,
        suspended: true
      }
    },
    {
      hostname: nil,
      address: "192.168.0.2",
      active_address: nil,
      aliases: [],
      display_status: {
        primary: false,
        master: false,
        slave: false,
        selectable: false,
        emergency: false,
        suspended: true
      }
    }
  ]
}

Returns:

• (Hash) —

  The status hash, keyed by symbols.

Raises:

• (SecurIDError) —

  if the RSA agent failed to initialize.

# File 'ext/securid/securid.c', line 667

static VALUE securid_agent_status(VALUE self) {
  VALUE status = Qfalse;
  VALUE server_release_number;
  VALUE server_details;
  VALUE servers;
  VALUE server_aliases;
  VALUE display_status;
  S_status_display agent_status;
  DISP_SRVR_INFO * server_info;
  int return_value, i, j, str_length;
  struct in_addr addr;

  // Initialize the library. Safe to call multiple times.
  if (AceInitialize() != SD_TRUE) {
    rb_raise(rb_eSecurIDError, "Failed to initialize authentication agent");
  }

  // Make sure we are zero'd
  memset(&agent_status, 0, sizeof(agent_status));
  // Set the struct size so the SDK can identify the version used
  agent_status.u32Size = (SD_U32) sizeof(agent_status);
  // Fetch the agent status
  return_value = AceAgentStatusDisplay(&agent_status);

  if (return_value == ACE_SUCCESS) {
    status = rb_hash_new();

    // Populate status hash
    rb_hash_aset(status, rb_symConfigVersion, INT2NUM(agent_status.config_version));
    rb_hash_aset(status, rb_symMaxServers, INT2NUM(agent_status.acmmaxservers));
    rb_hash_aset(status, rb_symMaxReplicas, INT2NUM(agent_status.acmmaxreplicas));
    rb_hash_aset(status, rb_symMaxRetries, INT2NUM(agent_status.acmmaxretries));
    rb_hash_aset(status, rb_symBaseTimeout, INT2NUM(agent_status.acmbasetimeout));
    rb_hash_aset(status, rb_symUseDES, INT2NUM(agent_status.use_des));
    rb_hash_aset(status, rb_symTrusted, INT2NUM(agent_status.trusted));
    rb_hash_aset(status, rb_symPort, INT2NUM(agent_status.acmport));
    rb_hash_aset(status, rb_symServiceProtocolVersion, INT2NUM(agent_status.server_hi_protocol));

    str_length = strnlen(agent_status.acmservice, sizeof(agent_status.acmservice) / sizeof(SD_CHAR));
    rb_hash_aset(status, rb_symServiceName, rb_str_new(agent_status.acmservice, str_length));

    str_length = strnlen(agent_status.acmprotocol, sizeof(agent_status.acmprotocol) / sizeof(SD_CHAR));
    rb_hash_aset(status, rb_symServiceProtocol, rb_str_new(agent_status.acmprotocol, str_length));

    // Populate release number hash
    server_release_number = rb_hash_new();
    rb_hash_aset(server_release_number, rb_symMajor, INT2NUM(agent_status.server_release_from_server[0]));
    rb_hash_aset(server_release_number, rb_symMinor, INT2NUM(agent_status.server_release_from_server[1]));
    rb_hash_aset(server_release_number, rb_symPatch, INT2NUM(agent_status.server_release_from_server[2]));
    rb_hash_aset(server_release_number, rb_symBuild, INT2NUM(agent_status.server_release_from_server[3]));
    rb_hash_aset(status, rb_symServerReleaseNumber, server_release_number);

    servers = rb_ary_new();

    // Populate server array
    for (i = 0; i < agent_status.acmmaxreplicas; ++i) {
      server_info = &agent_status.acm_servers[i];

      if (!(server_info->addr && server_info->hostname)) {
        continue;
      }

      server_details = rb_hash_new();

      str_length = strnlen(server_info->hostname, DISP_LENHOSTNAME);
      rb_hash_aset(server_details, rb_symHostname, str_length ? rb_str_new(server_info->hostname, str_length) : Qnil);

      addr.s_addr = server_info->addr;
      rb_hash_aset(server_details, rb_symAddress, server_info->addr ? rb_str_new2(inet_ntoa(addr)) : Qnil);

      addr.s_addr = server_info->active_addr;
      rb_hash_aset(server_details, rb_symActiveAddress, server_info->active_addr ? rb_str_new2(inet_ntoa(addr)) : Qnil);

      // build server aliases array
      server_aliases = rb_ary_new();
      for (j = 0; j < DISP_MAXALIASES; ++j) {
        if (!server_info->aliases[j]) {
          continue;
        }
        addr.s_addr = server_info->aliases[j];
        rb_ary_push(server_aliases, rb_str_new2(inet_ntoa(addr)));
      }
      rb_hash_aset(server_details, rb_symAliases, server_aliases);

      display_status = rb_hash_new();
      rb_hash_aset(display_status, rb_symPrimary, CTEST(server_info->display_status & DISP_STATUS_PRIMARY));
      rb_hash_aset(display_status, rb_symMaster, CTEST(server_info->display_status & DISP_MSTR_SLAVE && i == 0));
      rb_hash_aset(display_status, rb_symSlave, CTEST(server_info->display_status & DISP_MSTR_SLAVE && i > 0));
      rb_hash_aset(display_status, rb_symSelectable, CTEST(server_info->display_status & DISP_STATUS_SELECTABLE));
      rb_hash_aset(display_status, rb_symEmergency, CTEST(server_info->display_status & DISP_STATUS_EMERGENCY));
      rb_hash_aset(display_status, rb_symSuspended, CTEST(server_info->display_status & DISP_STATUS_SUSPENDED));
      rb_hash_aset(server_details, rb_symDisplayStatus, display_status);

      // Add server details to servers array
      rb_ary_push(servers, server_details);
    }

    // Add servers array to status hash
    rb_hash_aset(status, rb_symServers, servers);
  }

  return status;
}

.authenticate(username, password) ⇒ Boolean

Deprecated.

Use RSA::SecurID::Session#authenticate instead.

Performs a basic non-interactive authentication attempt.

Parameters:

• username (String) —

  The username to authenticate with.

• passcode (String) —

  The passcode to authenticate with. Passcodes are the user’s pin concatenated with the current token value.

Returns:

• (Boolean) —

  true on authentication succes, false on authentication denial.

Raises:

• (SecureIDError) —

  if anything beyond a basic rejection of the authentication happened such as a pin must be changed, the token needs resynchronization, the ACE server can’t be found, etc.

# File 'ext/securid/securid.c', line 133

static VALUE securid_authenticate(VALUE self, VALUE username, VALUE passcode)
{
  // the authentication handle representing a single authentication
  // context, i.e. a multi-step authentication attempt
  SDI_HANDLE aceHdl;

  // a string containing the username
  SD_CHAR *userID = StringValuePtr(username);

  // a string containing the passcode
  SD_CHAR *pass   = StringValuePtr(passcode);

  // a hint to the developer about how long to display the next
  // prompt string for the user
  SD_I32  respTimeout;

  // an indicator of the maximum number of bytes of data expected
  // in the next developer-supplied response
  SD_I32  nextRespLen;

  // a developer-supplied character array to be filled in by the
  // API with the string that the caller uses as the next message
  // displayed to the user
  SD_CHAR promptStr[512];

  // the size of the developer-supplied storage for the prompt
  // string
  SD_I32  promptStrLen;

  // a flag that is set by the API to indicate whether more data
  // is needed by the authentication context
  SD_BOOL moreData;

  // a flag that guides the developer as to whether the next
  // expected response is echoed to the screen
  SD_BOOL echoFlag;

  // the final authentication status
  SD_I32  authStatus;

  // initialize the authentication library. even though it will only do anything
  // the first time it is called, subsequent calls should still return true if the
  // initialization previously succeeded.
  if (!AceInitialize())
  {
    // the authentication library failed to initialize.
    rb_raise(rb_eSecurIDError, "Failed to initialize authentication library");
  }

  int retVal;

  // reset size of prompt string
  promptStrLen = sizeof(promptStr);

  // start our authentication attempt by first sending the username to
  // the authentication manager.
  retVal = AceStartAuth(&aceHdl, userID, strlen(userID), &moreData, &echoFlag, &respTimeout, &nextRespLen, promptStr, &promptStrLen);

  if (retVal != ACM_OK)
  {
    // the authentication attempt could not be started for some reason.
    rb_raise(rb_eSecurIDError, "Failed to start authentication attempt - Code %d", retVal);
  }

  if (!moreData)
  {
    // the authentication manager should have asked for a passcode
    AceCloseAuth(aceHdl);
    rb_raise(rb_eSecurIDError, "Authentication manager did not ask for a passcode");
  }

  // reset size of prompt string
  promptStrLen = sizeof(promptStr);

  // the authentication manager wants us to prompt the user for more data. because
  // this function is non-interactive, we assume the manager wants the passcode. since
  // we already have it, we'll pass it along without prompting the user.
  retVal = AceContinueAuth(aceHdl, pass, strlen(pass), &moreData, &echoFlag, &respTimeout, &nextRespLen, promptStr, &promptStrLen);

  if (retVal != ACM_OK)
  {
    // the authentication attempt could not be continued for some reason.
    AceCloseAuth(aceHdl);
    rb_raise(rb_eSecurIDError, "Failed to continue authentication attempt - Code %d", retVal);
  }

  if (moreData)
  {
    // either our assumption that the authentication manager wanted the passcode was
    // incorrect, or something else went wrong.
    AceCloseAuth(aceHdl);
    rb_raise(rb_eSecurIDError, "Authentication manager asked for more than a passcode");
  }

  // ask the authentication manager for the status of this authentication attempt.
  retVal = AceGetAuthenticationStatus(aceHdl, &authStatus);

  // finalize this authentication attempt by closing our handle.
  AceCloseAuth(aceHdl);

  if (retVal != ACE_SUCCESS)
  {
    // the authentication status could not be retrieved for some reason.
    rb_raise(rb_eSecurIDError, "Failed to retrieve authentication status - Code %d", retVal);
  }

  // check the status of the authentication attempt and return true or false.
  if (authStatus == ACM_OK)
    return Qtrue;
  else if (authStatus == ACM_ACCESS_DENIED)
    return Qfalse;

  rb_raise(rb_eSecurIDError, "Unexpected authentication status - Code %d", authStatus);
}