The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
DBIx-PasswordIniFile-1.1
River stage zero No dependents
++
/ DBIx::PasswordIniFile

NAME

DBIx::PasswordIniFile - Create DBI connections with password and other params stored in .ini files.

SYNOPSIS

    use DBIx::PasswordIniFile;
    $conn = DBIx::PasswordIniFile->new( 
              -file    => 'path/to/file.ini',
              -section => 'db_config_section',
              -key     => 'encrypt_decrypt_key',
              -cipher  => 'name_of_encryption_module'
    );

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

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

    $encrypted_passw = $conn->changePassword('new_password');

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

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

    $dbh = $conn->dbh();

DESCRIPTION

Lets you create a DBI connection with parameters stored in a .ini style file. The password is stored encrypted.

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) per .ini file.

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

FUNCTIONS

Note:

[ and ] around words in syntax of functions below mean optional, and not array reference.

$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 => 'db_config_section'

If specified, db_config_section is the section of the .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

Also, if attributes have to be specified, specify them as properties of another section with same name and _attributes at the end. For example, if your .ini file has a connect section, connection attributes (if specified) are assumed to be in connection_attributes section. If has a virtual user section, attributes are assumed to be in virtual user_attributes, and so on.

Note:

Connection attributes are those you specify as last argument of DBI connect method. See DBI for more details.

Allowed properties as DBI connection parameters are:

    driver
    database
    host
    port
    username
    password
    dsn

If driver=ODBC then dsn, username and password are mandatory, and all other parameters are ignored. If driver isn't ODBC, then all parameters except database, username and password are optional.

Properties/Values in ..._attributes section aren't predefined and are used as key/value pairs for \%attr argument when DBI connect method is called.

All propertie values are stored as plain text in .ini file, except password value, that is stored encrypted using an encription algorithm (default is Blowfish_PP).

Below is an example of .ini file content:

    [db_config_section]
    driver=mysql
    database=suppliers
    host=www.freesql.org
    port=3306
    username=ecastilla
    password=52616e646f6d495621c18a03330fee46600ace348beeec28
  
    [db_config_section_attributes]
    PrintError=1
    RaiseError=0
    AutoCommit=1

This is an example owith ODBC:

    [db_config_section]
    driver=ODBC
    dsn=FreeSQL

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.

The specified .ini file must be a compatible Config::IniFiles config file (with default syntax, see Config::IniFiles for detailed syntax). Briefly:

  • Lines beginning with # are comments and are ignored. Also, blank lines are ignored. Use this for readability purposes.

  • A section name is a string (including whitespaces) between [ and ].

  • Each section has one or more property/value pairs. Each property/value pair is specified with the syntax

        property=value

    One property/value pair per line.

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

If specified, -key and -cipher are the encryption/decription key used for storing/eading the password in .ini file and the cipher algoritm (default is 'Blowfish_PP'). Note that at least one encription algorithm have to be installed (they live in Crypt:: spacename).

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.

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

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] )

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

Cached objects may be retrieved with getCachedConnection.

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

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

Returns the new encrypted password saved in .ini file.

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

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()

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()

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

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_PP for encription and decription. If not installed, specify your preferred (without Crypt:: prefix).

SEE ALSO

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

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

COPYRIGHT

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>.