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

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

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 .

And all other parameters specified within the section are taken as connection attributes (key/value pairs for $%attr param of DBI::connect) .

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

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.

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.

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

COPYRIGHT AND LICENSE

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

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)