DBIx::PasswordIniFile - Manages DBI connections with password and other params stored in a
.ini style file.
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.
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
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
(THIS IS DEPRECATED) Like <DBIx::Password>, this is a subclass of DBI, so you may call DBI function objects using
$conn = DBIx::PasswordIniFile->new( -file=>'path/to/file.ini', ...);
DBIx::PasswordIniFile object from DBI connection parameters specified in
-file, other (optional) arguments are:
-section => 'db_config_section'
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
!! 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
-key => 'encrypt_decrypt_key' -cipher => 'name_of_encryption_module'
-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
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();
.ini configuration file specified in
new and returns an array ref like this:
[$dsn, $username, $password, $attributes]
$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
$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
$encrypted_password = $conn->encryptPassword( $clear_password );
Encrypts a clear password.
$clear_password = $conn->decryptPassword( $encrypted_password );
Decrypts an encrypted password.
DBI->connect with values stored in
.ini file specified in
\%attributes refers to last parameter of
\%attributes take precedence over any conflicting stored in
..._attributes section of
connect, but caches a copy of
Cached objects may be retrieved with
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.
Return a hash reference that is the cache. Keys are object references converted to strings and values are valid
Returns the DBI database handler object (a
DBIx::PasswordIniFile object is a composition of a
DBI object among others).
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):
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
#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).
Well, this module assumes two alternate content models for this section, being DEPRECATED one of both:
dsn (mandatory) user (optional) pass (optional)
Being values of
pass the fist three params passed to
And all other parameters specified within the section are taken as connection attributes (key/value pairs for
$%attr param of DBI::connect) .
[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)
The section specify this parameters:
driver (mandatory) database host port username password dsn
password are mandatory, and all other parameters are ignored. If
driver isn't ODBC, then all parameters except
password are optional.
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 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.
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
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
.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
There is an utility called encpassw.pl that takes a
.ini file and replaces the
pass/password param value with its encrypted form.
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:firstname.lastname@example.orgemail@example.com>.