DBIx::PasswordIniFile - Manages DBI connections with password and other params stored in a .ini style file.
.ini
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();
Manages DBI connection parameters stored in a .ini style configuration file (really a Config::IniFiles config file), with password stored encrypted.
Config::IniFiles
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 .
connect
encpassw.pl
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.
DBIx::Password
(THIS IS DEPRECATED) Like <DBIx::Password>, this is a subclass of DBI, so you may call DBI function objects using DBIx::PasswordIniFile objects.
DBIx::PasswordIniFile
$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.
path/to/file.ini
Apart from -file, other (optional) arguments are:
-file
-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:
db_config_section
dsn connect connection database db virtual user
If specified, but the section name doesn't exist, returns undef.
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 => '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.
-key
-cipher
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).
Blowfish
Crypt::
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.
$ary = $conn->getDBIConnectParams();
Reads from .ini configuration file specified in new and returns an array ref like this:
new
[$dsn, $username, $password, $attributes]
Where $dsn, $username and $password are strings ($password in clear form), and $attributes is a hash ref with connect attributes.
$dsn
$username
$password
$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.
$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).
new_clear_password
Returns the new encrypted password saved in .ini file.
$encrypted_password = $conn->encryptPassword( $clear_password );
Encrypts a clear password.
$clear_password = $conn->decryptPassword( $encrypted_password );
Decrypts an encrypted password.
$conn->connect( [\%attributes] )
Calls DBI->connect with values stored in .ini file specified in new. \%attributes refers to last parameter of DBI->connect.
DBI->connect
\%attributes
If specified, \%attributes take precedence over any conflicting stored in ..._attributes section of .ini file.
..._attributes
$conn->connectCached( [\%attributes] )
Same as connect, but caches a copy of $conn object.
$conn
Cached objects may be retrieved with getCachedConnection.
getCachedConnection
$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.
connectCached
$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).
DBI
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):
Basically, this kind of file contains sections and parameter/value pairs. A parameter/value pair is specified as this:
parameter = value
And being a section a group of parameter/value pairs:
[section] parameter1 = value1 parameter2 = value2 ...
A section name is a string (including whitespaces) between [ and ].
[
]
Lines beginning with # are comments and are ignored. Also, blank lines are ignored. Use this with readability purposes.
#
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).
-section
Well, this module assumes two alternate content models for this section, being DEPRECATED one of both:
The section specify these params:
dsn (mandatory) user (optional) pass (optional)
Being values of dsn, user and pass the fist three params passed to DBI::connect .
dsn
user
pass
DBI::connect
And all other parameters specified within the section are taken as connection attributes (key/value pairs for $%attr param of DBI::connect) .
$%attr
Sample:
[database] dsn=dbi:mysql:database=suppliers;host=192.168.2.101;port=3306 user=ecastilla pass=52616e646f6d495621c18a03330fee46600ace348beeec28
(value of pass is encrypted with encpassw.pl utility see perldoc encpassw.pl for more info)
perldoc encpassw.pl
(DEPRECATED)
The section specify this parameters:
driver (mandatory) 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.
driver=ODBC
username
password
driver
database
Also, if attributes for connection have to be specified, specify them as parameters 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.
_attributes
connection_attributes
virtual user
virtual user_attributes
Properties/Values in ..._attributes section aren't predefined and are used as key/value pairs for \%attr argument when DBI connect method is called.
\%attr
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.
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 .
DEFAULT_KEY
PasswordIniFile.pm
You may override this file creating your own .DEFAULT_KEY (note dot prefixed) file at your home directory.
.DEFAULT_KEY
In either case, content of this files is ONE line with a string used as key for Crypt::CBC algorithm.
Crypt::CBC
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.
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).
Crypt::Blowfish
There is an utility called encpassw.pl that takes a .ini file and replaces the pass/password param value with its encrypted form.
pass/password
DBI, Config::IniFiles, DBIx::Password.
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.
Enrique Castilla <mailto:ecastillacontreras@yahoo.es|ecastillacontreras@yahoo.es>.
To install DBIx::PasswordIniFile, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DBIx::PasswordIniFile
CPAN shell
perl -MCPAN -e shell install DBIx::PasswordIniFile
For more information on module installation, please visit the detailed CPAN module installation guide.