view release on metacpan or  search on metacpan

lib/Advanced/Config/Options.pm  view on Meta::CPAN

B<export_lbl> - Defaults to "B<EXPORT>".  Tells this module to export this
particular tag/value pair to perl's B<%ENV> hash.  If the I<export> option
was also set, it inverts the meaning of this label to mean don't export it!
You can also gain the same functionality by doing one of the following
instead:

    export tag = value    # Optional unix type shell script prefix.

    set tag = value       # Optional windows type batch file prefix.

These prefixes allow you to easily use shell/batch files as config files if
they contain no logic.

B<hide_lbl> - Defaults to "B<HIDE>".  Tells this module that this tag's value
contains sensitive information.  So when fish logging is turned on, this module
will never write it to these logs.  If the parser thinks a tag's name suggests
it's a password, it will assume that you put this label in the comment.  This
is what triggers the sensitive/mask arguments and return values that some
methods use.

B<encrypt_lbl> - Defaults to "B<ENCRYPT>".  Tells this module that you are
waiting for this tag's value to be encrypted in the config file.  It assumes
the value is still in clear text.  When present it assumes the value is
sensitive as well.

B<decrypt_lbl> - Defaults to "B<DECRYPT>".  Tells this module that this value
has already been encrypted and needs to be decrypted before it is used.  When
present it assumes that the value is sensitive as well.

B<source_file_section_lbl> - Defaults to "B<DEFAULT>".  Tells this module to
use the current section as the default/unlabeled section in the file being
source in.  This new value will be inherited should the sourced in file source
in any further files.

=back

=head2 Encryption/Decryption options.  (or Encode/Decode options.)

The following options deal with the encryption/decryption of the contents of a
config file.  Only the encryption of a tag's value is supported.  And this is
triggered by the appropriate label in the comment on the same line after the
value.

Unless you use the B<encrypt_cb> option, this module isn't using true
encryption.  It's more a complex obscuring of the tag's value making it very
difficult to retrieve a tag's value without using this module to examine the
config file's contents.  It's main use is to prevent casual browsers of your
file system from being able to examine your config files using their favorite
editor to capture sensitive data from your config files.

By default, the I<basename> of the config file's name and the tag's name are the
keys used to encode each value in the config file.  This means that each tag's
value in the config file uses a different key to obscure it.  But by using just
the defaults, anyone using this module may automatically decode everything in
the config file just by writing a perl program that uses this module.

But by using the options below, you gain additional security even without using
true encryption.  Since if you don't know the options used, you can't easily
decode each tag's value even by examining the code.  Just be aware that using
too many keys with too similar values could cancel each other out and weaken
the results.

These options are ignored if you've disabled decryption.

When you source in another file in your config files, the current values
for B<alias>, B<pass_phrase> and B<encrypt_by_user> are not inherited.  But the
remaining options are.  See option B<source_cb> if you need to set them in this
case.

=over 4

B<alias> - Defaults to the empty string.  (Meaning no alias provided.)  This
option is used to override using the file's I<basename> as one of the
encryption/decryption keys with the I<basename> of the value you provide here.

If you encrypt a file with no I<alias>, and then rename the config file, you
must set the I<alias> to the original filename to be able to decrypt anything.
If you encrypt a file with an I<alias>, you must use the same I<alias> to
decrypt things again.

If your config file is a symbolic link to another name, it will auto set this
option for you using the file's real name as the alias if you don't override
it by setting the alias yourself.

B<pass_phrase> - Defaults to the empty string.  If you used a pass phrase to
encrypt the value, then you need to use the same pass phrase again when
decrypting each tag's value.

B<inherit_pass_phrase> - Defaults to 0 (no).  Set to 1 if you want to use the
same B<pass_pharase> when you source in a sub-file in your config files.

B<encrypt_by_user> - Defaults to 0 (no).  Set to 1 if you want use the user
name you are running the program under as part of the encryption key.  So only
the user who encrypted the file can decrypt it.

B<encrypt_cb_opts> - A work area for holding values between calls to the
callback function.  This is expected to be a hash reference to provide any
values needed by your encryption efforts.  So you can avoid global variables
and having to figure out the correct context of the call.  Defaults to an empty
hash reference.

B<encrypt_cb> - An optional callback function to provide hooks for B<true
encryption> or an additional layer of masking.  It defaults to no callback
function used.  This callback function is called in addition to any obscuring
work done by this module.

Here is the callback function's expected definition:

  my $new_value = encrypt_callback_func ($mode, $tag, $value, $file[, $cbOpts]);

     $mode  ==> 1 - Encrypt this value, 0 - Decrypt this value.

     $tag   ==> The name of the tag whose value is being encrypted/decrypted.

     $value ==> The value to encrypt/decrypt.

     $file  ==> The basename of the file the tag/value pair came from.  If the
                "alias" option was used, the basename of that "alias" is
                passed as "$file" instead.