In this post I’ll be looking at what an extension is, how it fits into the dradis framework and how to write your own extensions.

You are welcome to jump ahead to the How do I write my own extension? if that is the only part that you are interested in.

What is an extension?

In a nutshell – A dradis extension is an addition to the collection of functions offered by the dradis client side. The possibilities of what an extension can be are almost endless. From a logical perspective it will be a function that enhances the usability of the application within the context of the user.

Currently the functionality that is offered by an extension is triggered from the command line console on the client side. To see what are all the commands offered by your currently installed extensions type help in the command line console of the dradis client. You might see something similar to:

List of registered commands
---------------------------
help:	shows the help of all the commands available
reload:	reload the modules from the filesystem
quit:	exits the application
add:	add elements to the project
fact:	shows a random Chuck Norris fact
encode:	Encodes a string using various differnet encoding schemes
lookup:	Basically greps a file, useful for lookup tables
decode:	Decodes a string into the specified encoding type
export:	export the knowledge base to a local file
ls:	lists entries under the directory specified as argument
import:	import external resources to dradis

Some of those commands are hard coded into the console functionality but the majority are commands offered by your installed extensions. For example the fact command is offered to you by the chucknorris extension and the ls command is offered by the filesystem extension.

Extensions can also communicate to other parts of the application. In the majority of cases this will be communication to the data storage. For example the add command allows you to add data to the data storage and the export command allows you to export the data storage to a local file.

Where do extensions fit into the dradis framework?

Extension fact list:

• As mentioned previously, extensions are found on the client side of the dradis framework.
• When looking at the code they can be found in the client/extensions folder.
• An extension provides one or more commands that can be called from the client command line console.
• Executing one of these commands in the console triggers a call to a method in the extension code (Executing fact in the console triggers the fact method in the chucknorris.rb file).
• The return value of the extension method is printed to the console interface (The return value of the fact method is a Chuck Norris fact that is printed to the console interface).
• The extension communicates to the rest of the application through calls to service providers (I’ll define a service provider shortly).
• An extension can be one of two types: simple or namespace (Definition of these will follow).

What is a service provider?
A service provider is an interface to a certain part of the application. It can be seen as a functionality presented through an API.
Lets look at an example: The dradis client side is modeled on a Model-View-Controller architecture. The extension code has access to an instance of the Controller (@controller). The extension does not have direct access to the Model (the Model is the access layer to the data storage). Calls to the Model is made through the data-storage service provider (client/core/service_providers/data_storage.rb. The data-storage service provider has a set of methods (an API) through which you can:

• add a node – @controller.request_service(:model_add_node, …)
• add a category – @controller.request_service(:model_add_category, …)
• get the contents of a node – @controller.request_service(:model_find_node, …)
• etc.

Have a look in the client/core/service_providers folder for all the currently available service providers.

What is a simple extension and a namespace extension?
A simple extension provides one or more commands that are grouped only by them being members of the extension. A command of a simple extension can be the only command in the current dradis client instance to have the name of that command. It is triggered in the command line console by: command parameters. The chucknorris extension is a simple extension and offers the fact command. No other simple extension can have a command called fact.

A namespace extension places its commands in a namespace. One namespace may contain commands with the same name as simple commands or commands in other namespaces. If we want to add a fact command that gives random Bruce Schneier facts then we can create the bruceschneier namespace and place a fact command in it that will not interfere with our Chuck Norris fact command. Namespace commands are called from the commandline in the format: namespace command parameter. The export extension is an example of a namespace extension.

How do I write my own extension?

Let’s have a look at the basic structure of a simple extension. Following is a simplified version of the chucknorris extension:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

module Extensions
  class Chucknorris < Extensions::Simple
    #----------------------------------------------------- Dispatcher implementation
    INFO = {
      :commands => {
        'fact' => {
          :desc => 'shows a random Chuck Norris fact',
          :syntax => [ ]
        }
      }
    }
 
    #----------------------------------------------------- commands implementation
    def fact(*args)
      # here we implement the magic that gets the new fact and returns it
    end
  end
end

• line 1 – To implement our extension we need to extend the Extensions module
• line 2 – We define our class to inherit from the Extensions::Simple class
• lines 4-11 – The INFO hash defines all the commands in our extension for the use of the command launcher. In the case of the example above it defines the presence of the fact command with its description and its syntax. In this case there is no syntax defined as the command does not take any parameters.
• lines 14-16 – This is the method implementation of the command that was defined in the INFO hash.

Now lets look at a slightly more complex namespace extension. The example is the add extension that hosts the node and category commands. The syntax for the two command are respectively:

add node  <parent id> <label>

and

add category <name>

This is the code for the extension:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

module Extensions
  class Add < Extensions::Namespace
    #----------------------------------------------------- private methods
    private
    #----------------------------------------------------- Dispatcher implementation
    INFO = {
      :namespace => 'add',
      :description => 'add elements to the project',
      :commands => {
        'node' => {
          :desc => 'Adds a node to the node tree.',
          :syntax => [
 
          {
            :required => true,
            :label => 'parent_id',
            :desc => 'The id of parent to the new node. Use 0 if it is to be a root node.',
            :regexp => /^\d*$/
          },
          {
            :required => true,
            :label => 'label',
            :desc => 'The label/name of the new node.',
            :regexp => /^\w[\w\s]*$/
          }
          ]
        },
        'category' => {
          :desc => 'Adds a note category.',
          :syntax => [
          {
            :required => true,
            :label => 'name',
            :desc => 'name of the new category',
            :regexp => /^\w[\w\s]*$/
          }
          ]
        }
      }
    }
 
    # Implements the add node fucntionality. See the above for allowed parameters
    def node(*args)
      # the parent_id needs to be an integer or a nil value
      args[1] = args[1] == '0' ? nil : args[1].to_i
      # call the service provider to add a node with the specified parameters
      @controller.request_service(:model_add_node, args[1], nil, args[2])
      return "Added node: #{args[2]}"
    end
 
    # Implements the add category fucntionality. See the above for allowed parameters
    def category(*args)
      # call the service provider to add a node with the specified parameters
      @controller.request_service(:model_add_category, args[1])
      return "Added category: #{args[1]}"
    end
  end
end

I’ll highlight the important and new bits of code:

• line 2 – Different that in the previous example we define this extension to inherit from the Extensions::Namespace class
• line 7 – In the INFO hash we define the namespace add. The contents associated with the add hash key defines the commands in the namespace.
• lines 9-38 – Here we define our commads in a very similar fashion as in the previous example. We have added the complexity of each command accepting some parameters. This is defined by the array assigned to the syntax key
• line 14 – States that the parameter is compulsary
• line 15 – This is the displayed name of the parameter
• line 16 – Defines the description of the command that will be printed in the help display of the command
• line 17 – Specifies the regular expression by which the parameter will be validated by the command launcher
• lines 42-55 – This is the implementation of the commands as defined in the INFO hash
• line 44 – The args array contains the parameters that was passed. args[0] is the command, node in this case. args[1] contains the parent_id and args[2] contains the label
• line 46 – This is an example of a call to a service provider in this case it calls a method in the data-storage service provider. (See the architecture section for a full discussion on this)
• line 47 – The return value will be displayed in the command line console.

As a last bit of advice:

• Name your extension file, class and if applicable namespace the same name
• If you add something new to the data storage you might find that you can not reference the newly added record immediately. The reason is that you have to wait for the local cache of the data storage to be refreshed. You can force a refresh with a @controller.request_service(:model_knowledge_refresh) call.

That should leave you with a good understanding of dradis extensions.

As always – Happy dradis coding!

• Make one of the components compulsory to install.
• We will look at a way to write our script in such a way that it can be reused for future releases of MyApplication.
• A few extra tips and tricks.

Making a component compulsory
At the end of Part 2 we added the components page to our installer. The component page gives the user the option to select which components he want to install. However, we want the installer not to give the user the option to not install MyApplication component but to make the installation of MyApplication when executing the script. We use the SectionSetFlags method to achieve this. SetSectionFlags allows you to set certain attributes of a section (component to be installed). We add the following code:

Function .onInit
  IntOp $0 ${SF_SELECTED} | ${SF_RO}
  SectionSetFlags ${SEC03} $0
FunctionEnd

• You will recall from Part 1 that the .onInit function is called on initiating the script.
• The SectionSetFlags method sets first 8 bits of the section’s flags. We are interested in the first bit (setting a sections and selected) and the fifth bit (setting a section as read only)
• To achieve this we use the SF_SELECTED and the SF_RO constants that are equal to 1 and 16 respectively.
• When we OR these to constants together we end up with a value of which the first and the fifth bit are set (line 2).
• In line 3 we use the SectionSetFlags method to apply the result of the OR to SEC03 which is our MyApplication component.
• The result is that the MyApplication component will be selected and read only on the components page of the installer.

Making our script usable for the future
I might happen that we want to release a new version of MyApplication that requires a new installer. The new version might have the same requirements but a few new files might be added that now needs to be added to the installer. If the install section of MyApplication gets very big (depending on the size of MyApplication) it can be a daunting task to review all the SetOutPath “$INSTDIR\my_folder” and File “application_files\myapplication.rb” type calls. It will be great if we can automate the creating of these calls.

I have created the following Ruby script that receives as commandline argument the folder in which MyApplication lives and the creates a text file that contains the instruction set that we need in the MyApplication section:

require 'fileutils'
include FileUtils::Verbose
 
def recursive_folder_dump(folder, install_file, uninstall_file, relative_path)
  cd(folder) {
    folders = []
    Dir.foreach('.\\') { |inner_file|
      if File.directory?(inner_file) && inner_file != '.' && inner_file != '..'
        folders << inner_file
      elsif inner_file != '.' && inner_file != '..'
        install_file.puts "File \"" + relative_path + inner_file + "\""
        uninstall_file.puts "Delete \"$INSTDIR\\" + relative_path + inner_file + "\""
      end
    }
    folders.each { |folder|
      install_file.puts "SetOutPath \"$INSTDIR\\" + relative_path + folder + "\""
      recursive_folder_dump(folder, install_file, uninstall_file, relative_path + folder + "\\")
      uninstall_file.puts "RMDir \"$INSTDIR\\" + relative_path + folder + "\""
    }
  }
end
 
if ARGV[1] == nil
  puts 'usage: ruby nsis_folder_dump.rb  '
  puts 'where:'
  puts ' - is the folder/file structure to be dumped'
  puts ' - will be used to create the output file names: _install.nsi and _uninstall.nsi'
  exit
end
 
if !File.exists?(ARGV[0])
  puts ARGV[0] + " is not an existing folder"
  exit
end
 
install_file = File.new(ARGV[1]+"_install.nsh",'w')
uninstall_file = File.new(ARGV[1]+"_uninstall.nsh",'w')
 
install_file.puts "SetOutPath \"$INSTDIR\\" + ARGV[0] + "\""
recursive_folder_dump(ARGV[0], install_file, uninstall_file, ARGV[0] + "\\")
uninstall_file.puts "RMDir \"$INSTDIR\\" + ARGV[0] + "\""
 
install_file.close

The above script will create two files. Depending on the commandline parameters they might be myapplication_install.nsh and myapplication_uninstall.nsh.

NSIS allows us to include these files in our script with the !include. We change the MyApplication install section to look like this:

Section "MyApplication" SEC03
  !include "myapplication_install.nsh"
SectionEnd

And we add the following to the top of our Uninstall section:

!include "myapplication_uninstall.nsh"

We can now keep our NSIS install script the same for all future releases of MyApplication and just generate new myapplication_install.nsh and myapplication_uninstall.nsh files.

A few more tips and tricks
MyApplication has a database the can be initialised by a rake task. We can run this rake task at the end of a successful installation. We achieve that with the following code:

!define MUI_FINISHPAGE_RUN_TEXT "Initialise the database"
!define MUI_FINISHPAGE_RUN "$0\bin\rake.bat"
!define MUI_FINISHPAGE_RUN_PARAMETERS "-f $\"$INSTDIR\server\Rakefile$\" db:migrate"

On uninstall files and folders can be removed by the Delete and RMDir methods. If you want to delete a whole folder recursively its contents you can use the /r directive:

RMDir /r "$INSTDIR\my_application"

And that brings us to the end of Part 3.

• Ruby (the target machine that our application is installed on requires Ruby)
• MyGem (our application is dependent on this fictitious gem)
• MyApplication (this is our application to be installed)

In this part we will look at how we will let the installer take care of the Ruby and MyGem components.

To start off, place the following at the top of your code:

!include LogicLib.nsh

This includes the LogicLib library and allow us to write more readable code by providing us some macros to write traditional logical structures for example IF and CASE structures

Ruby

Our application needs Ruby to be installed on the target machine. In the case that Ruby is not installed on the machine we want to relieve the user from having to install Ruby separately. Instead we want to install it for him.

In the example in Part one we replace the code:

Section "Ruby" SEC01
SectionEnd

with (we will go through this in detail):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

Section "ruby" SEC01
  ; read the registry to check if there is not already a local installation of ruby
  readRegStr $0 HKLM "SOFTWARE\RubyInstaller" Path
  ${If} $0 != ''
    ; ruby installed
    MessageBox MB_OK 'Ruby is already installed on the system. The automated installation of Ruby will not proceed'
  ${Else}
    ; no ruby installer
    MessageBox MB_OK 'The ruby installer will now be downloaded and executed. This might take a few moments.'
    ; download and install ruby
    NSISdl::download /NOIEPROXY "http://rubyforge.org/frs/download.php/29263/ruby186-26.exe" "ruby186-26.exe"
    Pop $R0
    ${If} $R0 == 'success'
      ; ruby download successful
      StrCpy $0 ''
      ; rum the one click installer
      ExecWait '"ruby186-26.exe"' $0
      ${If} $0 == ''
        ; execution of one click installer failed
        MessageBox MB_OK "Ruby install failed. Please install Ruby manually"
      ${EndIf}
      ; delete the ruby one click installer
    ${Else}
      ; ruby download not successfull
      MessageBox MB_OK "Ruby download failed. Please download and install Ruby manually"
    ${EndIf}
    Delete "ruby186-26.exe"
  ${EndIf}
SectionEnd

Lets go through the code in detail

• We make the assumption that if Ruby is installed on the system that there will be a registry entry for the installation. We check for this registry entry with the readRegStr command (line 3).
• If we find an entry in the registry we prompt (MessageBox) this to the user and we do not proceed with the Ruby installation (line 6).
• If Ruby is not installed we notify the user that the installer will download the Ruby one-click installer and then proceed with the download (NSISdl::download, line 11)
• A successful download will place the success string on the stack. We Pop the top value from the stack and store in $0 (line 12).
• The installer inspects $0 and is the download was successful it proceeds to running the Ruby one-click installer (ExecWait, line 17)
• The return value of the one-click installer is inspected to determine a successful install. In the case of failure this is prompted to the user (lines 18-20).
• Towards the end of the script we handle the case of a failed download (lines 23-25).
• Finally the installer deletes the downloaded one-click installer (Delete, line 27)

MyGem

The installer needs to take care of the installation of our required gem, MyGem. To minimize the insteraction between the user and the installation process the installer installs the gem from a file in the installation package. This file contains the gem for local install.

Once again refering to the example in Part 1 one, we replace the code:

Section "MyGem" SEC02
SectionEnd

with:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Section "MyGem" SEC02
  SetOutPath "$INSTDIR\client"
  File "my_gem-x86-mswin32-60.gem"
  # check if ruby is installed and install the mygem gem locally if so
  readRegStr $0 HKLM "SOFTWARE\RubyInstaller" Path
  ${If} $0 != ''
    ; ruby installed
    StrCpy $1 ''
    ; install the mygem locally
    ExecWait '"$0\bin\gem.bat" install my_gem-x86-mswin32-60.gem' $1
    ${If} $1 == ''
      MessageBox MB_OK "Gem install failed. Please install the MyGem gem manually"
    ${EndIf}
  ${Else}
    ; ruby not installed
    MessageBox MB_OK "Ruby is not installed. Please install ruby and then run the installer again or install the MyGem gem manually"
  ${EndIf}
  Delete "my_gem-x86-mswin32-60.gem"
SectionEnd

By now you should be able to follow the code quite easily. I will just highlight to things:

• Yet again we have to check if Ruby is installed on the target machine (line 5).
• Note that you have to give the full path to the gem batch file when triggering the gem installation (line 10).

Choosing Components

You might what to give you users the option to choose the components that they want to install. The modern user interface makes it really easy for you.

Add the following to your script below !insertmacro MUI_PAGE_COMPONENTS:

!insertmacro MUI_PAGE_COMPONENTS

And at the end of all your section code add:

!insertmacro MUI_FUNCTION_DESCRIPTION_BEGIN
  !insertmacro MUI_DESCRIPTION_TEXT ${SEC01} "Installs ruby. The installer will download the ruby one click installer and execute. Alternatively you can install ruby manually."
  !insertmacro MUI_DESCRIPTION_TEXT ${SEC02} "Installs the MyGem gem. The gem requires ruby to be installed."
  !insertmacro MUI_DESCRIPTION_TEXT ${SEC03} "Installs the MyApplication."
!insertmacro MUI_FUNCTION_DESCRIPTION_END

I am going to leave it at that. In Part 3 we will look at you can make certain components compulsory, how we can write our script so that we can also use it for future releases of MyApplication and a few extra tips and tricks to clean up the script.

Happy coding!

I am using HM NIS editor and IDE for NSIS to make the task a little easier. To get out of the blocks a little quicker I used the HM NIS wizard to create a simple framework from where I will progress.

The wizard allows you to install different components (groups). These are typically different parts of your application and dependencies that needs to be installed. I created the following components:

• Ruby (this will download and install the Ruby one-click installer if ruby is not installed)
• MyGem (this will install the the required gems)
• MyApplication (this will install my application)

The wizard also lets you pick a GUI type. I picked modern. You can choose between modern, classic or none.

The script generated by the wizard will look something like the following (do not bother to read it all right now, I will go into detail for some parts of it):

; Script generated by the HM NIS Edit Script Wizard.
 
; HM NIS Edit Wizard helper defines
!define PRODUCT_NAME "My application"
!define PRODUCT_VERSION "1.0"
!define PRODUCT_PUBLISHER "My company, Inc."
!define PRODUCT_WEB_SITE "http://www.mycompany.com"
!define PRODUCT_UNINST_KEY "SoftwareMicrosoftWindowsCurrentVersionUninstall${PRODUCT_NAME}"
!define PRODUCT_UNINST_ROOT_KEY "HKLM"
 
; MUI 1.67 compatible ------
!include "MUI.nsh"
 
; MUI Settings
!define MUI_ABORTWARNING
!define MUI_ICON "${NSISDIR}ContribGraphicsIconsmodern-install.ico"
!define MUI_UNICON "${NSISDIR}ContribGraphicsIconsmodern-uninstall.ico"
 
; Welcome page
!insertmacro MUI_PAGE_WELCOME
; License page
!insertmacro MUI_PAGE_LICENSE "c:pathtolicenceYourSoftwareLicence.txt"
; Directory page
!insertmacro MUI_PAGE_DIRECTORY
; Instfiles page
!insertmacro MUI_PAGE_INSTFILES
; Finish page
!insertmacro MUI_PAGE_FINISH
 
; Uninstaller pages
!insertmacro MUI_UNPAGE_INSTFILES
 
; Language files
!insertmacro MUI_LANGUAGE "English"
 
; MUI end ------
 
Name "${PRODUCT_NAME} ${PRODUCT_VERSION}"
OutFile "Setup.exe"
InstallDir "$PROGRAMFILESMy application"
ShowInstDetails show
ShowUnInstDetails show
 
Section "Ruby" SEC01
SectionEnd
 
Section "MyGem" SEC02
SectionEnd
 
Section "MyApplication" SEC03
SectionEnd
 
Section -AdditionalIcons
  SetOutPath $INSTDIR 
  WriteIniStr "$INSTDIR${PRODUCT_NAME}.url" "InternetShortcut" "URL" "${PRODUCT_WEB_SITE}"
  CreateDirectory "$SMPROGRAMSMy application"
  CreateShortCut "$SMPROGRAMSMy applicationWebsite.lnk" "$INSTDIR${PRODUCT_NAME}.url"
  CreateShortCut "$SMPROGRAMSMy applicationUninstall.lnk" "$INSTDIRuninst.exe"
SectionEnd
 
Section -Post
  WriteUninstaller "$INSTDIRuninst.exe"
  WriteRegStr ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}" "DisplayName" "$(^Name)"
  WriteRegStr ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}" "UninstallString" "$INSTDIRuninst.exe"
  WriteRegStr ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}" "DisplayVersion" "${PRODUCT_VERSION}"
  WriteRegStr ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}" "URLInfoAbout" "${PRODUCT_WEB_SITE}"
  WriteRegStr ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}" "Publisher" "${PRODUCT_PUBLISHER}"
SectionEnd
 
Function un.onUninstSuccess
  HideWindow
  MessageBox MB_ICONINFORMATION|MB_OK "$(^Name) was successfully removed from your computer."
FunctionEnd
 
Function un.onInit
  MessageBox MB_ICONQUESTION|MB_YESNO|MB_DEFBUTTON2 "Are you sure you want to completely remove $(^Name) and all of its components?" IDYES +2
  Abort
FunctionEnd
 
Section Uninstall
  Delete "$INSTDIR${PRODUCT_NAME}.url"
  Delete "$INSTDIRuninst.exe"
 
  Delete "$SMPROGRAMSMy applicationUninstall.lnk"
  Delete "$SMPROGRAMSMy applicationWebsite.lnk"
 
  RMDir "$SMPROGRAMSMy application"
 
 
 
  DeleteRegKey ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}"
  SetAutoClose true
SectionEnd

The first thing to get you head around here is the general layout of a NSIS script and how this maps to the final installer. For a thorough read on this refer to section 2.3 Scripting structure in the NSIS User Manual. As a brief overview:

• Compiler commands
  The instructions that start with ! (exclamation mark) are compiler commands. These commands are executed on compile time.
• Installer attributes
  Close to the top of your script you will note a few installer attributes that are defined. For example:

  Name "${PRODUCT_NAME} ${PRODUCT_VERSION}"
  OutFile "Setup.exe"
  InstallDir "$PROGRAMFILESMy application"

  These attributes are used and referenced later in the installation process

• Installer pages
  A non silent installer consist of different pages. These pages will mostly be taken care of by the GUI interface that you picked. The predefined GUI pages that are used are specified by the !insertmacro directives. For example:

  !insertmacro MUI_PAGE_WELCOME

  specifies that the modern GUI’s welcome page should be inserted.

• Sections
  You will note that chunks of the script are wrapped by the Section and SectionEnd directives. These mostly correspond to different components of your application to be installed.
  In my example you will note sections for Ruby, MyGem and MyApplication. You will also notice some sections that start with un. These sections are called during uninstall.
  The code inside a section are executed on the machine that the installer is being run on. Sections are executed in the order as they appear in the code.
• Functions
  Functions are pieces of script code that are called either from within sections by using Call functionName or they are called at different points in the script execution as Callback functions. For example .onInit will be called when the installer is initiated.

When you defined your application’s different components in the wizard you were allowed to specify the different files that should be installed. These files are referenced in the install and uninstall sections. In the install sections you will note something similar to:

SetOutPath "$INSTDIRmy_folder"
File "application_filesmyapplication.rb"

The first line specifies that what follows after that line (File “application_files\myapplication.rb”) should be applied to the $INSTDIR\my_folder directory. It effectively changes the current directory path. The second line instructs the installer to copy the file located at application_files\myapplication.rb to the current path.

In the uninstall section you will note code that is similar to:

Delete "$INSTDIRmy_foldermyapplication.rb"
RMDir "$INSTDIRmy_folder"

It instructs the uninstaller to delete the file at $INSTDIR\my_folder\myapplication.rb and remove the folder $INSTDIR\my_folder.

I am going to leave it at that. In the next post I’ll describe how I install Ruby and the required gem on running the installer.

In the plugin test folder I created a lib and a fixtures folder. In the lib folder I created two files activerecord_connector.rb and activerecord_test.rb.

acticerecord_connector.rb:

require "rubygems"
require "active_record"
require 'active_record/fixtures'

conf = YAML::load(File.open(File.dirname(__FILE__) + '/../database.yml'))
ActiveRecord::Base.establish_connection(conf['sqlite3'])

This file is required to make a connection to the database that is configured by database.yml that I placed in the test folder.

database.yml:

sqlite3:
  database: ":memory:"
  adapter: sqlite3
  timeout: 500

This specifies a connection to a Sqlite database that is to be kept in memory. It means the database is just alive for the duration of our test – perfect.

activerecord_test.rb

require 'test/lib/activerecord_connector'
require 'test/fixtures/schema.rb'

class ActiverecordTest < Test::Unit::TestCase
  FIXTURES_PTH = File.join(File.dirname(__FILE__), '/../fixtures')
  dep = defined?(ActiveSupport::Dependencies) ? ActiveSupport::Dependencies : ::Dependencies
  dep.load_paths.unshift FIXTURES_PTH
end

The code in this file does the following:

• It requires activerecord_connector.
• Requires a schema.rb file for populating the database.
• Defines the ActiverecordTest class that define and store the path to your fixtures folder.

schema.rb:

ActiveRecord::Schema.define do
  create_table "users", :force => true do |t|
    t.string   "first_name"
    t.string   "last_name"
    t.integer "id"
  end
end

As you can see, this creates the users table in the database.

I created a User model that is stored in the fixtures folder.

user.rb

class User < ActiveRecord::Base
  #this class might be extended by your plugin
end

Also in the fixtures folder is a users.yml file to serve as test content in our database.

users.yml

david:
  id: 1
  first_name: Thomas
  last_name: Black

jamis:
  id: 2
  first_name: Peter
  last_name: Martin

Lastly we have our test file.

hot_plugin_test.rb

require 'test/unit'
require 'test/lib/activerecord_test'

class HotPluginTest < ActiverecordTest

  def setup
    Fixtures.create_fixtures(FIXTURES_PTH, 'users')
  end

  def test_users
    user = User.find(:first)
    assert_equal "Thomas", user.login, "not working!!"
  end
end

• HotPluginTest inherits from ActiveRecordTest.
• The setup method creates the content in our database from the users.yml file.

Now you can extend models that you place in the fixtures folder with your plugin and run tests against them in HotPluginTest.

As I said at the start, this is just a method of doing it – you might have some other ideas. I’ll be happy to hear about them. For another approach you might want to look at Plugin Test Helper.

Happy testing!

My credit to the following posts and plugin for leading to this solution:

• Rails Plugin Testing Guide
• Using ActiveRecord outside Rails
• will_paginate plugin that has a great test example

This is the first of a series of posts with small tips and tricks of ExtJS that will also address its integration with Ruby on Rails.

In this release we are going to create a ComboBox that loads its items from a remote location (potentially a rails REST endpoint).

I wanted to create this series when I started using ExtJS so it could be used as a step-by-step howto of ExtJS and rails, but as sometimes happens, I got carried away with the coding side of things leaving the post writing abandoned . That is the main reason why some core concepts of ExtJS development are not included here. The project site, documentation and samples can help with that. Here we are dealing with the real stuff, so lets get it on.

First the code: extjs-comboxml.tar.bz2. I have a local apache for debuging purposes and I uncompressed the ExtJS package in /var/www/ext-2.2/, then I created a test folder inside it. This code should work fine if you uncompress its contents in the test folder. If you have a different environment, adjust the locations of the script tags in the header of combo.html.

This is how it should look like:

So with ExtJS there are two ways of loading combo items from a remote location, it is a bit confusing because these two are called local and remote modes. The difference is that in local mode, the combo is relying on someone else to grab the information and in remote mode the combo itself will make the Ajax call.

No matter what mode we choose, we will need a data store for our items. Here is the code used in the example:

var categories = new Ext.data.Store({
        url: 'categories.xml',
        autoLoad: true, // required for the combo that does not use Ajax
        reader: new Ext.data.XmlReader(
                { record: 'category', id: 'id'},
                [ { name: 'name', type: 'string' } ]
              ),
        listeners: {
          load: function(records, options) {
            console.log( 'loaded ' + records.totalLength + ' records');
          },
          loadexception: function(proxy, options, response, error) {
            console.log('error loading records from server:');
            console.log("\tfile: "+error.fileName);
            console.log("\tline: "+error.lineNumber);
          }
        }
      });

The listeners in the code above are just for debuging purposes and can be removed safely. The only interesting bit is the autoLoad option, but we will come back to that later. For now it is enough to say that the Store above will read an XML document with this structure:

<?xml version="1.0" encoding="UTF-8"?>
<categories type="array">
<category>
<id type="integer">1</id>
<name>default category</name>
</category>
<category>
<id type="integer">2</id>
<name>security risk</name>
</category>
</categories>


The autoLoad config options determines if the data store will try to load the values from the provided url upon creation or if it will be necessary to call the load(). This is useful when we are working in local mode, let’s see the code for the first combo:

var comboLocal = new Ext.form.ComboBox({
  fieldLabel: 'Select a category',
  store: categories,
  mode: 'local',
  displayField: 'name',
  selectOnFocus: true,
  emptyText: 'No Ajax in the combo...'
});

Above we specified local this means that options for this combo will be loaded from the categories store. The data store is expected to be populated already, this can be done either by specifying the autoLoad option as described above or by calling the load().

If you rather have you combo performing the Ajax request, then the code you need to use is:

var comboRemote = new Ext.form.ComboBox({
  fieldLabel: 'Select a category',
  store: categories,
  displayField: 'name',
  triggerAction: 'all',
  selectOnFocus: true,
  emptyText: 'Options loaded using Ajax...'
});

There is no need to include mode: 'remote' because is the default behaviour, here the trick is to include the triggerAction: 'all', otherwise the Ajax request will never be executed.

So that was it, short and simple, stay tuned for the next one

Key note – David Heinemeier Hansson

David is the creator of the Rails framework and obviously a bit of a celebrity. Interestingly enough I get the idea that he is not the highest contributor to the Rails code base – I appears to be Jeremy Kemper which is his colleague at 37signals (the company behind Ruby on Rails).

David delivered the keynote on Wednesday morning. The key note was on legacy code. Initially I thought – “What a boring subject” and then later I caught myself thinking – “Now you are talking a load of nonsense” and two thirds into it I was happy to admit – “Hey, you really have been thinking about this a lot”.

Maybe it is a sentiment that only or mostly developers can associate with but very often you look back onto code and refer to it very cynically as “Legacy” code. He’s argument was that “legacy” code is a result of progress in environment and personal growth (Sounds like a psychiatry session – I know – It did get better). He carried on by making suggestions as to how legacy code should be dealt with and then showed a few examples in Rails. Some thoughts suggestion:

• The worst mistake that a company can make is to decide to simply rewrite legacy code on impulse.
• Legacy code should be put through iterations to improve it – They have a rule in their company that you should always leave code in a better state than what you found it in.
• Be careful of judging code as legacy due to a change in personal taste.
• Keep in mind that the code you write today will become legacy – face the facts.

Rails developers make a big deal out of DRY (Do Not Repeat Yourself). It implies that functionality should not unnecessarily be repeated in your code. The rule of thumb is that if you have found yourself copy and pasting for the 3rd time then its time to DRY-up your code. His point was that very DRY code makes it sometimes difficult to extend the code and this can make the improvement of legacy code difficult. A bit of repetition in your code is thus not a bad thing.

A thought that came to my mind was – “How should the IT security consultant look at (or judge) legacy code. Firstly, code tested 2 years ago and stamped as secure might not be secure anymore (new techniques, new vulnerabilities). What, or rather, is there a recommendation on re-testing or frequency on re-testing? Secondly, what is the recommendation on finding holes in legacy code? As mentioned rewriting code is not always (very seldom) the viable solution. How should a client maintain a legacy code base from a security point of view?

When to tell your kids about presentation caching – Matthew Deiters

You have all heard about the 20/80 rule. You wear 20% of your clothes 80% of the time. 20% of the world’s population own 80% of the wealth. And so it turns out that 20% of an application resources are being requested 80% of the time and 80% of the http request time are being spent on the wire – thus the argument for caching and a few other tricks to speed things up.

From my notes and memory the following are the major points:

• Rails supports ETags. The application responds with an ETag in the HTTP header when a request has been made for specific resource. The browser caches the ETag and the contents. When requesting the same resource in future it sends the ETag back the server. This allows the server to check if anything on the resource has changed since the last request associated with the ETag. If it is still the same it responds with “not modified” (that take is quicker to process and send) and the browser just displays the old version.
• Rails also supports static asset time stamping. This allows browser caching to be done based on a timestamp in the static asset request string.
• Rails has setting “perform_caching true” that combines .js files into a single file and makes the download time quicker.
• You can also configure your web server to gzip certain assets.
• Because most web browsers only allows for 2 connections to run simultaneously to a single server there are advantages in distributing you static assets across multiple servers.

All of the above have their little tricks and limitations that are worth investigating on implementation.

Intellectual Scalability – Solving a Large Problem With Multiple Cooperating Rails Apps – Frederick Cheung (Texperts), Paul Butcher (Texperts)

This was one of two presentations on serving multiple applications through a single front-end. In this case the developers designed a JavaScript heavy UI framework that presents the multiple allocations through a single front-end interface. Each application is presented in the front-end through what they call a widget. The power of the framework is in the code and a full (even partial) understanding requires a demonstration. I am making contact with the guy to see if they are willing to share the code. He did mention that they will release it publicly if there is interest.

Slides at http://assets.en.oreilly.com/1/event/13/Intellectual Scalability – Solving a Large Problem With Multiple Cooperating Rails Apps Presentation.ppt

Offline Rails Applications with Google Gears and Adobe AIR – Till Vollmer (MindMeister/Codemart GmbH)

(My notes are becoming increasingly less and I am not going to write a lot about this)
This was more a Google Gears talk than a Rails talk. I have never bothered to actually have a look at Google Gears but this guy had a good talk on how they implemented it from an architectural point of view.

You basically design your web application to be able to operate when you are offline. You have a local SQLite database that you use when going offline and this is synchronised back to the server when you go back online. There is obviously at lot to manage:

• Detect on-line/off-line status
• Clashes when local db and server are not compatible on synchronisation.

My biggest thought during this talk was the amount of havoc that you can cause when the contents of the SQLite db is not validated before the automated synchronisation to the server db takes place. I think it is worth looking at.

Security on Rails – Jonathan Weiss (Peritor GmbH)

This is a German chap that is (amongst others) an IT security consultant. It had nothing too new about the web application security stuff – XSS, SQL injection and XSRF. He discussed in each case how this should be prevented in Rails. It was reassuring to note that our Rails development is up to his standards.

The interesting part of his talk was on how to finger print a Rails application. I will leave you with his slides to have a look at that: http://assets.en.oreilly.com/1/event/13/Security%20on%20Rails%20Presentation.pdf

Few other important things:

• Rails 2 and greater by default uses the cookie to store the session state (you can change this). This cookie is just Base64 encoded and should thus not be used to store sensitive data. A hash of the data and a secret key (you can configure this) is also stored in the cookie and this is used to check the authenticity of a cookie when send back to the server.
• Some plugins to look at: saveERB, XSS shield and tidy_library.
• Often times (and this is the case in some trusted plugins) the user session is not reset on logout – check for this.
• Rails 2.1 and smaller – Despite the parameterise ability of the ActiveRecord class the limit and offset parameters in the find method where not typecased. This leaves the door open for SQL injections. This was fixed but the MySQL adapter still appears vulnerable.
• Mass assignment (user = User.create(params) can allow for great havoc if the malicious user send extra parameters in the post request that relates for example to the user level. Use attr_protected and attr_accessible
• DOS attacks can be launched against file upload functionalities by sending very big files. Use the web server to handle file uploads or use the web server direct the request to another application to deal with file uploads.

I spoke to the guy afterwards to get an idea on what his opinion is on Rails’ maturity in terms of security. I mentioned a certain ‘trust’ in PHP due to the time it has had to mature. His reply was that Rails has been developed from a much better security perspective than Rails and is more mature to his standards.

Functional Testing Lessons Learned – Jay Fields (DRW Trading)

Jay mainly looked at the following three points:

• The place and role of writing tests
• Comparing different test suites
• Different types of tests

He stressed the importance of testing and the purpose thereof. It is especially applicable in environments where code improvements, refactoring and growth is a constant occurrence. Testing plays a central role in making sure that the result of these actions does not break the code and that breaks in the code can be indentified as soon as possible. From a certain perspective testing is a way to document the functionality and purpose of code.

I picked up on the following statements two statements that I felt creates a great perspective:

• Testing code is just as important as application code.
• Tests should be created that provides a positive return on investment

An important point is that testing does not replace the need for manual testing – it does not replace a QA team or a testing team. Automated tests might test the intended functionality but the perspective from a person that is not involved in the development is needed.

The Rails framework encourages two testing approaches – Unit testing and Functional testing. Unit testing has to do with testing classes in isolation by simulating the functionality of dependencies to the outside of the class. Functional testing has to do with testing functionalities that is presented by the integration of different units. Have a look at his blog entry http://blog.jayfields.com/2007/09/rails-how-we-test.html for more thoughts on this.

Other test types include integration tests, smoke tests, use case tests and automated browsers tests. I’ll leave it up to the reader to investigate these further.

Three testing suites were discussed:

• RSpec
• test/unit
• Selenium

The factors to take into account when choosing a test suite are:

• Ease and simplicity of implementation
• Flexibility to support the different types of tests
• Ability to present the test code to non-technical project members – QA team, senior management etc.

With these factors taken into account RSpec was considered the best option with test/unit in second and Selenium very unfavourable.

To bring the security aspect into this topic – I wonder if there is a case for security consultants to assist client developers in writing test cases for there applications that will also assist the developers in keeping a security perspective on there code.

Small Things, Loosely Joined and Written Fast – Justin Gehtland (Relevance, Inc.)

I think this was the best talk that I attended. Unfortunately for the reader of this article it was really one of those talks that you have had to been there. The slides was mainly a few photos to support his comical metaphors, my notes practically non-existent and an excellent demo that you’ll have to go though the code in your own time.

The main argument was – Big problems do not require big solutions bundled in one big fat application. Proper solutions consist of a number of small independent applications that can be developed, configured, tested and managed independently. These smaller solutions then be integrated together to tackle the big problem.

To use his terms – This approach will improve your productivity by improving:

• Testability
• Compose-ability
• Security
• Scalability

And, to quote him “Make small things, join them loosely, write them fast, scale them independently”

He had a wonderful demonstration on three Rails applications that are delivered through a single entry point using a central authentication point and a message queue for some of the communication between the independent parts.

Have a look at his blog entry – http://blog.thinkrelevance.com/2008/9/3/small-things-loosely-joined-written-fast

From Rails Security to Application Security – Carsten Bormann (Universität Bremen, TZI), Steffen Bartsch (TZI, Universität Bremen)

I am not going to attempt to cover this talk in too much depth. They touched on the topics of:

• Data confidentiality, integrity and authentication
• Threat matrixes
• Attack trees

There is loads of information out there on this that makes covering the topics in this write-up irrelevant.

The one thing to take note of in this talk is an authorisation plugin that Steffen developed. It offers a very clean way to manage authorisation of access for different level users to all the levels of the MVC architecture. Despite offering great flexibility and full management of authorisation it has very clean way of presenting the authorisation rules to the developer, making the auditing of the rules a very easy process.

See the presentation slides on Steffen’s blog – http://steffenbartsch.com/blog/2008/09/from-rails-security-to-application-security/

Writing resources_controller: Discovering REST Patterns in Rails – Ian White (Argument from Design)

REST is getting great attention in the Rails community, in fact I will dare to say – I think the RAILS community are leaders in the RESTful approach. If I may quote Ralf Wirdemann and Thomas Baustert from RESTful Rails Development (http://media.quilime.com/files/pdf/restful_rails_en.pdf) “REST describes an architecture paradigm for web applications that request and manipulate web resources using the standard HTTP methods GET, POST, PUT and DELETE.”. In other words – A resource (data object/model) is mapped to a URL and is managed by the standard HTTP methods.

Also and as mention earlier, Ruby programmers support DRY (Don’t Repeat Yourself) code.

Ian developed a plugin (seems like if you want to talk at Rails conference then you have to write a plugin) that provides a central Resource Controller that can manage the REST functionalities of all your other controllers. For a very thorough explanation of this see the blog – http://blog.ardes.com/resources_controller

Intro

On a recent project I was challenged with the task to create a Windows installer for Dradis, an application that I have been contributing to. After a bit of research it seemed like our answer was in using NSIS (Nullsoft Scriptable Install System) to assist us in this task.

NSIS in an open source platform for creating Windows installers. It has its own scripting language that you program all your installer logic in and then compiles to a Windows installer executable.

In this series of articles I will introduce you to:

• HM NIS IDE and it’s wizard (Part 1)
• Customising the wizard code (Part 2)
• Challenges with installing to user accounts without administrator rights (Part 3)

The goal

The goal is to create an installer for Acme application. I will customise the installer code as we go along but the main components for installation are:

• Copying our acme_app.rb file to a location on the target machine
• Check if Ruby is installed on the target machine. Install it if it is not the case
• Our application uses SQLite. We need to check if the required files are installed on the target machine and install it if it is not the case.

On the NSIS website you will find plenty of examples and tutorials to get you started. I am however going to jump in a little further ahead and tell you about HM NIS Edit. HM NIS Edit is an Editor/IDE to create your NSIS installers in. I came across it after a little web search and it proved itself to be a very handy tool to use on top of NSIS.

To create a nice installer with options, components, license etc. there is a lot of code that is generic and can fit into a framework followed by a bit of customisation. HM NSIS Edit assists you in this task by providing a wizard. It is from the wizard I’ll start my explanation.

The HM NIS Edit wizard

In the HM NSIS Edit application you have the typical wand and stars icon to start the wizard with. The first couple of screens is pretty straight forward and asks you a number of things about your app. The fun starts at the “Application Files” screen. It is here where you specify the different components (groups) for your application and the files associated.

The application components

For the purpose of my Acme application I create the following components: Ruby, SQLite and Acme app.

1. Ruby

For the Ruby component I do not see the point of wrapping the Ruby one click installer file in our Acme app installer. I decided I’ll make Ruby an install component but picking it for installation will download the Ruby one click installer and execute it. I create the Ruby group in the wizard and do not pick any files, we will add the meat of the download and install later.

2. SQLite

Now we get to the SQLite component. So we create the SQLite group in our wizard. This group consists of two parts: the dll and the Ruby gem.

sqlite3.dll

The dll is easy; it is one file that we need to copy to the system32 folder. So to the right hand side of the wizard window we click the add file icon, browse for the dll that we have ready on our machine and select the destination directory. The destination directory is the directory on the target machine where the file will be copied to. We need it in the system32 folder so we choose $SYSDIR from the drop down box.

SQLite gem

The most common way to install Ruby gem is with the command line command:

gem install GEMNAME --remote

In older GEM versions you could not however state the platform that you are installing the gem to from the command line, it is an option that is given to you just after running the “gem install GEMNAME –remote” command.

The above will not work very nice with our installer as we want the installer to deal with this and not require input from the user on gem installation. However you can use --local instead of --remote and just specify the local file from which the gem should be installed. In this case the installation does not require from you to supply the platform.

So I downloaded the sqlite3-ruby-1.2.1-mswin32.gem file from RubyForge and added it to the files to be installed as we did with the dll, however in this case just copy it to the $INSTDIR. We will add the meat to run the gem install GEMNAME --remote command later.

3. Acme app

Now we get to our acme_app.rb source file. As for the previous components we create a new component group called Acme app. After the component has been created be associate ou acme_app.rb source file with it as we did with the SQLite files. We set the $INSTDIR to be our target folder on the target machine.

Note – If your application code is more than one file you can select a directory tree to be associated with the component instead of just a single file at a time.

At this point you component list should look something similar to what you see in the figure below.

Completing the rest of the wizard is quite straight forward. Remember that if you want to execute an executable (for instance if you want to call notepad to open a file at the end of installation) you have to give the full path to the executable (for example “$SYSDIR\notepad.exe some-text-file”).

Finishing the wizard will give you a code file that you can compile in HM NIS Edit and it will supply you with the install executable.

That’s it for now

- but there is more

I have left a few things out that the wizard could not do to customise our installer. I will have to do some tweaking to the code for this purpose. This will be covered in Part 2.

Things that will be covered include:

• remove the need of a login
• the use of an activation email, the application will require it’s users to activate their accounts upong sign up.
• howto get rid of the remember me functionality (just in case you don’t need it).
• howto strengthen a bit the default security of the framework.

If you started a blank application with the first series, you can seamlessly continue with the instructions of this post from were we left it on the first part of this howto. Otherwise, you can grab the code of restauthz application, a small rails application that I have created and that can be used as a proof of concept out of the box. Let’s get this thing going.

Before we start, just a gentle reminder, be sure to include AuthenticationSystem in ApplicationController:-

include AuthenticatedSystem
# Filter the password and password_confirmation
# fields from the log files
filter_parameter_logging :password, :password_confirmation

no login, just email

The first step is to remove the login field from the User migration, this will ensure that we do not use it in the code

We also need to remove the revelant validatiors in the User model. In addition to this, some changes to the authenticate are required:-

def self.authenticate(email, password)
  u = find_in_state :first, :active, :conditions => {:email => email} # need to get the salt
  u && u.authenticated?(password) ? u : nil
end

We also need to update the call to this function in the SessionsController (line 9):-

self.current_user = User.authenticate(params[:email], params[:password])

And that’s it. It wasn’t that difficult, was it?

email activation

The only thing that we are going to tweak is the templates provided by restful_authentication.

In ./app/model/user_mailer.rb you can modify the email headers such as the subject and from address. The body of the emails is located under ./app/views/user_mailer/.

The system sends to the users two emails, one after signup (this one contains the activation link) and one once the user has activated the account.

By default the templates contain the newly created user’s password, which is something that is controversial to say the least. I decided to get rid of the password, but this depends on your needs more than anything else.

remember me

Another feature that is application dependant is the use of a remember me functionality: a check box in the login form that would cause the application to store an authentication token in the user’s cookie so the next time the user visits the site does not have to authenticate again. I decided to nail down this example to the very basics, so no remember me functionality in this instance.

This can be accomplished by making some modifications to the AuthenticatedSystem#current_user function:

def current_user
  #@current_user ||= (login_from_session || login_from_basic_auth || login_from_cookie) unless @current_user == false
  # only session based login for the time being
  @current_user ||= login_from_session unless @current_user == false
end

In the previous code, the @current_user variable is only set through the session, no HTTP Basic (careful if you have ActiveResource clients) or remember me cookie.

security tweaks

password policy
A strong password policy is enforced by means of rails’ validate_format_of. In the User model:-

class User  /^(?=.*\d)(?=.*([a-z]|[A-Z]))([\x20-\x7E]){8,40}$/,
    :message => 'chosen is not complex enough!'
  validates_format_of :email, 
    :with => /^([a-zA-Z0-9_'+*$%\^&!\.\-])+\@(([a-zA-Z0-9\-])+\.)+([a-zA-Z0-9:]{2,4})+$/, 
    :message => 'field does not look like an email.'
  [...]
end

In the code above we match both the email and the password against regular expressions to verify the syntax.

The regular expression for the password was taken from Using Regular Expression in Ruby on Rails — Regexp for Password Validation:-

Lets say we have to implement the following validations to validate a password:

• Password should contain atleast one integer.
• Password should contain atleast one alphabet(either in downcase or upcase).
• Password can have special characters from 20 to 7E ascii values.
• Password should be minimum of 8 and maximum of 40 cahracters long.

password with salt & pepper

Storing a password in plaintext may result in a system compromise (OWASP).

Conveniently enough, restful_authentication uses a hash function to protect user passwords: the SHA-1. It also uses a salt. Here are however two tricks to increase the security of the default setup:

First we are going to hash the password with salt and pepper. The salt is specific to each user and will be stored in the database along with the user’s hashed password. If an attacker can compromise the database, they would have access to both the salt and the hash and brute force attacks could be mounted by using custom scripts or rainbow tables. The trick here is to add a second component, the pepper. The pepper is another random string that will be used to add some extra entropy to the password hashing process. In our implementation the same pepper will be used for all the users and it will be stored in the code. If an attacker gains access to the database, no successful brute force attack can be mounted without knowing the pepper. If an attacker gains access to both the database and the code…

You can easily generate your pepper using something like this in code in irb:-

require 'digest/sha2'
s = ''
chars = ("a".."z").to_a + ("A".."Z").to_a + ("0".."9").to_a
1.upto(4) { |i| s << chars[rand(chars.size-1)] }
s += Time.now.to_s
1.upto(4) { |i| s << chars[rand(chars.size-1)] }
Digest::SHA256.hexdigest(s)
=> "9fa4c6519da9d2121bc42be1d63813f591bba8ece5b753e6ceefed00f15e5342"

The random character generation was taken from generate a random password.

And second, we can upgrade the system to use the more secure SHA-256 both for the hashed password and the salt. We will keep SHA-1 for the sake of variety

In order to accomplish this, some modifications are needed to the ./app/model/user.rb. First we need to include the required files:-

# sha1 for activation code. sha2 for the passwords
require 'digest/sha1'
require 'digest/sha2'

Then the password encryption function:-

# We are using both, salt and peper to hash the
# password. The new password hash uses
# SHA2.hexdigest
def self.encrypt(password, salt)
  pepper = '9fa4c6519da9d2121bc42be1d63813f591bba8ece5b753e6ceefed00f15e5342'
  Digest::SHA256.hexdigest("--#{salt}--#{password}--#{pepper}--")
end

And the salt generation function:-

# The salt is also created using SHA256
def encrypt_password
  return if password.blank?
  self.salt = Digest::SHA256.hexdigest("--#{Time.now.to_s}--#{email}--") if new_record?
  self.crypted_password = encrypt(password)
end

In order to store the new hash, we need to increase the length of the salt and crypted password fields in the database. This can be done in the migrations file:-

t.column :crypted_password, :string, :limit => 64
t.column :salt, :string, :limit => 64

summary

So that was it, the restauthz application should cover all the needs to get you started with restful_authentication. There is still room for improvement, think the I forgot my password functionality, or a facility for your users to change their passwords, but that is definitely another story

• A no non-sense authentication: just email and password. No bells, no wistles.
• The system should send an activation email after the user signs up.

Let’s explore the alternatives

The haystack…

As stated elsewhere acts_as_authenticated is a neat solution that just gets out of the way. It is nice and easy to integrate. However, it is a bit too simple. loginsugar seemed to be a suitable alternative with ActionMailer integration out of the box.

I decided to give it a try. It has a good documentation that walks you through the process of integrating it in your app, but it did not seem to be a goal too easy to accomplish

What I finally decided was to take specific bits and pieces of the loginsugar and integrate them with plain old acts_as_authenticated.

First step of the process: I created a brand new project and installed the acts_as_authenticated plugin. It was surprising to find the following line in the README file:

DEPRECATED: Use restful_authentication instead. Or, ask me for commit rights if you wish to maintain this plugin.

… So I was right back at the begining, everybody recommended acts_as_authenticated but acts_as_authenticated recommended restuful_authentication… I thought that if acts_as_authenticated is recommending something, it has to be good And I decided to give restuful_authentication a try.

… and the needle

Lets get out hands dirty, create a new project and install the plugin with:-

<br />
$ ./script/plugin  install http://svn.techno-weenie.net/projects/plugins/restful_authentication/<br />

It turns out that the plugin has the activation email functionality out of the box, the only requirement is the use of a few command line options:-

<br />
$ ./script/generate authenticated<br />
Usage: ./script/generate authenticated ModelName [ControllerName]</p>
<p>Options:<br />
        --skip-migration             Don't generate a migration file for this model<br />
        --include-activation         Generate signup 'activation code' confirmation via email<br />
        --stateful                   Use acts_as_state_machine.  Assumes --include-activation<br />
        --rspec                      Force rspec mode (checks for RAILS_ROOT/spec by default)<br />

We need to include the --include-activation for the email, which in turn requires --stateful. The idea is that you are going to associate a small state machine to each user. From signed up, to pending; after the user actives the account, the status changes to active, etc.

It is quite neat. However it has the drawback that requires another plugin: acts_as_state_machine, but more on that later.

In order to generate your user model and your session controller, you need to issue the following:-

<br />
$ ./script/generate authenticated user sessions \<br />
                --include-activation \<br />
                --stateful<br />

This generates the required files. It also creates the routes to the user and session resources in ./conf/routes.rb:-

<br />
#[...]<br />
map.resources :users<br />
map.resource :session<br />
#[...]<br />

However, as the README file suggests we need to modify the :users resource as follows:-

<br />
map.resources :users, :member => { :suspend => :put, :unsuspend => :put, :purge => :delete }<br />

An extra line in ./config/environment.rb is also required (make sure you include it inside the Rails::Initializer.run block):-

<br />
config.active_record.observers = :user_observer<br />

The next step is to install the acts_as_state_machine plugin and to run rake db:migrate to initialize the database:-

<br />
$ ./script/plugin install http://elitists.textdriven.com/svn/plugins/acts_as_state_machine/trunk<br />
[...]<br />
$ rake db:migrate<br />

Now you are set. Feel free to run rake that all the tests will pass without warnings. Only one tip from the restful_authentication railscast: to get short urls for signup, login and logout add the following to your ./config/routes.rb:

<br />
map.signup '/signup', :controller => 'users', :action => 'new'<br />
map.connect '/activate/:activation_code', :controller => 'users', :action => 'activate'<br />
map.login '/login', :controller => 'sessions', :action => 'new'<br />
map.logout '/logout', :controller => 'sessions', :action => 'destroy'<br />

Fine tune

So here we are all set with the authentication framework in place. From here on it is about customization and fine tunning. Note that the activation email feature requires an either an email server running on the same box or some ActionMailer configuration in order for it to work.

In the second part of this series we will go back to our basic need: get rid of the login field (we only need an email). This and other tweaks will be demonstrated in a tiny app that fully implements the concepts explained here. Part 2 is here! restful_authentication howto, step-by-step (part 2).