Enrique Castilla Contreras > DBIx-PasswordIniFile-2.00 > DBIx::PasswordIniFile

Download:
DBIx-PasswordIniFile-2.00.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  2
Open  0
View/Report Bugs
Module Version: 2.00   Source  

NAME ^

DBIx::PasswordIniFile - Manages DBI connections with password and other params stored in a .ini style file.

SYNOPSIS ^

    use DBIx::PasswordIniFile;
    $conn = DBIx::PasswordIniFile->new( 
              -file    => 'path/to/config.ini',
              -section => 'database connection',
              -key     => 'encrypt and decrypt key',
              -cipher  => 'Blowfish'
    );

    $ary = $conn->getDBIConnectParams();
    $dbh = DBI->connect( @$ary ) or die $DBI::errstr;
    
    $encrypted_passw = $conn->changePassword('new_password');
    
    $encrypted = $conn->encryptPassword( 'clear_password' );
    $clear     = $conn->decryptPassword( $encrypted );
    
    
    # THIS METHODS ARE DEPRECATED:
    
    $conn->connect( \%attributes ); # or
    $conn->connect(); 

    $conn->connectCached( \%attributes ); # or
    $conn->connectCached();

    $conn = DBIx::PasswordIniFile->getCachedConnection( 'path/to/file.ini' );

    $hash_ref = DBIx::PasswordIniFile->getCache();

    $dbh = $conn->dbh();

DESCRIPTION ^

Manages DBI connection parameters stored in a .ini style configuration file (really a Config::IniFiles config file), with password stored encrypted.

This module allows you to store DBI connect params in a .ini style configuration file, with password encrypted. .ini configuration files are plain text files managed with Config::IniFiles module. Once written, there is a command line utility called encpassw.pl that re-writes the .ini file, encrypting the password. The same may be done programatically, calling changePassword .

This module is similar to DBIx::Password. The differences are that DBI connection parameters aren't stored as part of the module source code (but in an external .ini style file), and that this module lets you only one virtual user (i.e. one connection specification) per .ini file.

(THIS IS DEPRECATED) Like <DBIx::Password>, this is a subclass of DBI, so you may call DBI function objects using DBIx::PasswordIniFile objects.

FUNCTIONS ^

new

    $conn = DBIx::PasswordIniFile->new( -file=>'path/to/file.ini', ...);

Creates a DBIx::PasswordIniFile object from DBI connection parameters specified in path/to/file.ini file.

Apart from -file, other (optional) arguments are:

-section
    -section => 'db_config_section'

If specified, db_config_section is the section name of .ini file where DBI connection parameters live. If not specified, assumes that DBI connection parameters are in a section with one of these names:

    dsn
    connect
    connection
    database
    db
    virtual user

If specified, but the section name doesn't exist, returns undef.

!! IMPORTANT !! There are two alternate models for the content of this section, the old one being deprecated. See "CONTENT OF .ini file" for more info about what properties may be specified in this section of .ini file.

-key and -cipher
    -key    => 'encrypt_decrypt_key'
    -cipher => 'name_of_encryption_module'

If specified, -key and -cipher are the encryption/decription key used for storing/reading the password in .ini file, and the cipher algoritm.

If not specified -key, it's read from (with this order of preference):

  $HOME/.DEFAULT_KEY file 
  DBIx/DEFAULT_KEY file (from same dir as PasswordIniFile.pm)

(see FILES for more info)

Because default value for -key is stored in a file, it's a security break to not specify this argument.

If not specified -cipher, it's assumed Blowfish. Note at least one encription algorithm have to be installed (they live in Crypt:: spacename).

Usage sample:

    use DBI;
    use DBIx::PasswordIniFile;
    
    $conn = new DBIx::PasswordIniFile( -file => 'my.ini');
    $ary = $conn->getDBIConnectParams;
    
    $dbh = DBI->connect( @$ary ) or die $DBI::errstr;

(DEPRECATED SAMPLE) Once a DBIx::PasswordIniFile object is created, use it to call DBI object methods. For example:

    use DBIx::PasswordIniFile;
    $conn = new DBIx::PasswordIniFile( -file => 'my.ini');
    $conn->connect();
    ...
    $conn->disconnect(); # DBI object method.

getDBIConnectParams

  $ary = $conn->getDBIConnectParams();

Reads from .ini configuration file specified in new and returns an array ref like this:

  [$dsn, $username, $password, $attributes]

Where $dsn, $username and $password are strings ($password in clear form), and $attributes is a hash ref with connect attributes.

You may call a DBI connect as this:

  $ary = $conn->getDBIConnectParams();
  DBI->connect( @$ary );

!! IMPORTANT !!

This method assumes a different content in section of configuration .ini file specified in new, than deprecated methods. See "CONTENTS OF .ini file" for what parameters may be specified in .ini file.

changePassword

  $encrypted_passw = $conn->changePassword('new_clear_password')>

Replaces the encrypted password stored in .ini file with the result of encrypting new_clear_password password (so, new_clear_password is the new password in clear form).

Returns the new encrypted password saved in .ini file.

encryptPassword

    $encrypted_password = $conn->encryptPassword( $clear_password );

Encrypts a clear password.

decryptPassword

    $clear_password = $conn->decryptPassword( $encrypted_password );

Decrypts an encrypted password.

$conn->connect( [\%attributes] ) (DEPRECATED)

Calls DBI->connect with values stored in .ini file specified in new. \%attributes refers to last parameter of DBI->connect.

If specified, \%attributes take precedence over any conflicting stored in ..._attributes section of .ini file.

$conn->connectCached( [\%attributes] ) (DEPRECATED)

Same as connect, but caches a copy of $conn object.

Cached objects may be retrieved with getCachedConnection.

$conn = DBIx::PasswordIniFile->getCachedConnection( 'path/to/file.ini' ) (DEPRECATED)

Returns a valid DBIx::PasswordIniFile object corresponding to the .ini file argument, if its connectCached was launched. Or returns undef if argument doesn't correspond to a cached connection.

$cache = DBIx::PasswordIniFile->getCache() (DEPRECATED)

Return a hash reference that is the cache. Keys are object references converted to strings and values are valid DBIx::PasswordIniFile objects.

$dbh = $conn->dbh() (DEPRECATED)

Returns the DBI database handler object (a DBIx::PasswordIniFile object is a composition of a DBI object among others).

FILES ^

CONTENTS OF .ini FILE

As explained in documentation of new, the file specified with -file is a plain text file with a syntax compatible with Config::IniFiles. Briefly (for more info see Config::IniFiles documentation):

This module assumes the config file has a section whose name is specified as

    $c = DBIx::PasswordIniFile( ... -section => $name ... );

Or one of the default section names if -section argument is not specified (if more than one default section names exist and no -section is specified, the first default section, in order of appearance, is assumed).

Well, this module assumes two alternate content models for this section, being DEPRECATED one of both:

Other sections and properties of the .ini file are ignored, and do not cause any undesired effect. This lets you use non dedicated .ini files for storing DBI connection parameters.

DEFAULT_KEY file

When installed, a DEFAULT_KEY (NO dot prefixed) file is created at the same directory of PasswordIniFile.pm. It stores a default key used when no -key argument is specified in new .

You may override this file creating your own .DEFAULT_KEY (note dot prefixed) file at your home directory.

In either case, content of this files is ONE line with a string used as key for Crypt::CBC algorithm.

SECURITY CONSIDERATIONS ^

In .ini file, password is stored encrypted, and never in clear form. But note that the mechanism is not completely secured because passwords are stored clear in memory. A hack may do a memory dump and see the password.

Although with this limitation, I think the module is a good balance between security and simplicity.

REQUISITES ^

Perl v5.8.6 or above has to be installed. If not, an error

   Free to wrong pool XXX not YYY during global destruction

is displayed, and Perl crashes.

An encription module has to be installed. Default is to use Crypt::Blowfish for encription and decription. If not installed Blowfish, specify your preferred (without Crypt:: prefix).

SEE ALSO ^

There is an utility called encpassw.pl that takes a .ini file and replaces the pass/password param value with its encrypted form.

DBI, Config::IniFiles, DBIx::Password.

COPYRIGHT AND LICENSE ^

Copyright 2005-2008 Enrique Castilla.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR ^

Enrique Castilla <mailto:ecastillacontreras@yahoo.es|ecastillacontreras@yahoo.es>.

syntax highlighting: