aMail::Sec

Developer's arena

NAME

TRex::Sec - provides security functions (including safe options for mkdir, open, etc.)

SYNOPSIS

    use TRex::Sec;

DESCRIPTION

The first goal for TRex is security, so let's start programming safe. The base for this guidelines is the perlsec page. Some additions are being made, from different sources, while we continue to advance in securing TRex.

This modules provides the common security subroutines for TRex operation (this helps us to achieve the ``Security'' goal).

Are you sure about that data ?

Perl has a very clever way to deal with data from ``unchecked'' sources. Essentially it treat it as ``tainted'' (dirty) data and is tagged as such. The way to laundering it is to pass it through a filter, and decide what data (or part of it) will be used (sorry, but for a detailed explanation of this method take a look at perlsec, it's very carefully explained). The default is not to check for tainted data, but for TRex it is selected to check for it (the -T switch activates the checking).

In perlsec is specified to use a subroutine to check fot tainted data, or use Taint.pm (not shipped as a standard distributed module) to check for tainted data and to insert tainted data (mainly). There's another module (Untaint.pm) that is a complement for the first one and it untaints vectors, arrays, and scalars.

After a few tests was seen that those modules very not very suitable for TRex (despite its clear and well done code), because specifics TRex desired internal usage and it should be installed as extra modules (a little burden added to the installation process).

What to filter and how

Then the point is to check each piece of data to be used, mainly against metacharacters that could subvert the operating system. So each data from outside the program, or data generated inside TRex but using external data, must be checked for correctness. Now the subject is to define how each data should look like, then accepting the one that match this p attern and reject otherwise.

In this implementation each subroutine checks for proper conditions to be satisfied. If these don't conform to it then there's no safe environment for them to run, then it dies. This mainly helps the subverted use of the system and, in a lateral way, keeps the code cleaner and simple (if the subroutine returns is because its execution was sucessful, dies otherwise).

The subrotines that enhance Perl functions (such as open, unlink, etc.) mimic the syntax of its original counterparts. If the extra customization needs to be used for these functions then some extra parameters can be passed as an anonymous hash (take a look at the examples for further information).

    ##########################################################
    ###
    ###  NOTICE for all SAFE operations
    ###  
    ###  Basically the checks made are on:
    ###  - complete filename 
    ###  - file existence or inexistence (depending on read, 
    ###    write, creation, etc.)
    ###  - permissions checking for the intended operation
    ###
    ##########################################################

METHODS

Common usage

All the methods in these package share common usage characteristics, that will be shown here for simplicity, clarity and space considerations.

All methods inherited a standard use with mandatory parameters that have no common characteristics, but all the extensions made share the usage and format: must be passed as an anonymous hash, are not mandatory and have similar name for each of them.

The first one is 'die_text' which let us specify the text added to the standard die text when the function fails to perform (the original die text is also added an can't be avoided).

The second one is 'die_sub' which let us specify a reference to a subroutine that will be performed instead of die; after the execution of this routine the script will end (instead of die). This was implemented because some impossibility to access a file, or inability to execute some statement doesn't means a violation, simply a coding error or some in the style, and dieing is not the best option (a graceful ending is better suited).

Usage:

    use TRex::Sec;

    $file = "/home/bit-man/.profile";

    safe_open_read( *FH{IO}, \$file,
                    {'die_sub' => \&bye }
                  );

    sub bye() {
        print "I didn't want to read it, anyway\n";
    }

NOTICE: If 'die_sub' is specified the 'die_text' parameter is not used (either dies with the 'die_text' or executes 'die_sub')

`check_path($%)`

Checks a filename or a path against proper format. It expects reference to a scalar, which contains a path to a file (the filename also can be included). It only checks for the correct structure of a path and filename, it doesn't check for its existence, access permissions or whatever extra conditions could be checked.

Note: an empty path is allowed and will pass the test.

Usage:

    use TRex::Sec;

    $file = "/home/bit-man/.profile";

    check_path( \$file );        ## Standard use
    check_path( \$file,          ## Enhanced use
            {'die_text' => "This file should pass"} ); ## Die text to be used

`check_lang($%)`

Checks for proper formaed language name. It expects a reference to the scalar containing the language name to be checked.

Usage:

    use TRex::Sec;

    $lang = "es";

    check_lang( \$lang );        ## Standard use
    check_lang( \$lang,          ## Enhanced use
               {'die_text' => "This language is admitted"} ); ## Die text to be used

`safe_unlink($%)`

Unlinks (deletes) a file. Expects a scalar containing the path for the file to be deleted.

Usage:

    use TRex::Sec;

    $file = "/home/bit-man/.profile";

    safe_unlink( $file );        ## Standard use
    safe_unlink( $file,          ## Enhanced use
            {'die_text' => "This file should be deleted"} ); ## Die text to be used

`safe_open_read($$%)`

Opens a file for reading. Expects a reference to the file handler and a scalar containing the path for the file to be opened.

Usage:

    use TRex::Sec;

    $file = "/home/bit-man/.profile";

    safe_open_read( *FH{IO}, $file );        ## Standard use
    safe_open_read( *FH{IO}, $file,          ## Enhanced use
                {'die_text' => "This file should be read"} ); ## Die text to be used

`safe_open_create($$%)`

Creates a file. Expects a reference to the file handler and a scalar containing the path for the file to be created.

Usage:

    use TRex::Sec;

    $file = "/home/bit-man/.profile";

    safe_open_create( *FH{IO}, $file );        ## Standard use
    safe_open_create( *FH{IO}, $file,          ## Enhanced use
                {'die_text' => "This file should be created"} );  ## Die text to be used

`safe_open_write($$%)`

Opens a file for writing. Expects a reference to the file handler and a scalar containing the path for the file to be written.

Usage:

    use TRex::Sec;

    $file = "/home/bit-man/.profile";

    safe_open_write( *FH{IO}, $file );        ## Standard use
    safe_open_write( *FH{IO}, $file,          ## Enhanced use
                {'die_text' => "This file should be written"} ); ## Die text to be used

`safe_open_update($$%)`

Opens a file for updating. Expects a reference to the file handler and a scalar containing the path for the file to be updated.

Usage:

    use TRex::Sec;

    $file = "/home/bit-man/.profile";

    safe_open_update( *FH{IO}, $file );        ## Standard use
    safe_open_update( *FH{IO}, $file,          ## Enhanced use
                {'die_text' => "This file should be updated"}  );## Die text to be used

`safe_rename($$%)`

Renames a file. Expects a scalar containing the path for the file to be renamed and the path for its new name.

Usage:

    use TRex::Sec;

    $old = "/home/bit-man/.profile";
    $new = "/home/bit-man/.profile.backup";

    safe_rename( $old, $new );        ## Standard use
    safe_rename( $old, $new,          ## Enhanced use
             {'die_text' => "This file should be renamed"} );  ## Die text to be used

`safe_opendir($$%)`

Opens a directory. Expects a reference to a file handler and a scalar containing the directory to be opened.

Usage:

    use TRex::Sec;

    $dir = "/home/bit-man";

    safe_opendir( *FH{IO}, $dir );        ## Standard use
    safe_opendir( *FH{IO}, $dir,          ## Enhanced use
             {'die_text' => "This directory should open"} ); ## Die text to be used

`safe_mkdir($$%)`

Creates a directory. Expects a scalar containing the path for the directory to be created.

Usage:

    use TRex::Sec;

    $dir = "/home/bit-man/test_TRex_Sec";

    safe_mkdir( $dir );        ## Standard use
    safe_mkdir( $dir,          ## Enhanced use
             {'die_text' => "This directory should be created"} ); ## Die text to be used

`safe_chmod($$%)`

Changes the mode for the list of files to be passed. Expects a scalar containing the mode and an array with the paths of the files to be modified.

Usage:

    use TRex::Sec;

    $mode = '700';
    $file = "/home/bit-man/.profile";

    safe_chmod( $mode, $file );        ## Standard use
    safe_mkdir( $mode, $file,          ## Enhanced use
             {'die_text' => "This SHOULD work"} ); ## Die text to be used

`safe_dbmopen($$%)`

Opens a DBM database. Expects : - a hash reference - DBM file path - open mode

As can be seen it's the same as using dbmopen with the hash reference passing instead of the hash.

Usage:

    use TRex::Sec;

    $dbmData = "/home/bit-man/DBMfile";

    safe_dbmopen( \%hash, $dbmData, 0660 );        ## Standard use
    safe_dbmopen( \%hash, $dbmData, 0660,          ## Enhanced use
                  {'die_text' => "Can't open $dbmData database",  ## Die text to be used
                   'DBMtries' => 10,
                   'DBMsleep' => 2  } );

This one has two extra parameters that can be passed :

DBMtries : the number of times that will try to open the DBM database (defaults to TRex::Sec::DBMtries)
DBMsleep : the seconds that it will sleep between tries (defaults to TRex::Sec::DBMsleep)