password results from the CPAN

Advanced-Config

and B<]>.

B<variable_left> & B<variable_right> - This pair is used to anchor a variable
definition.  Any value between these anchors will be a variable name and it's
value will be used instead, unless you've disabled this expansion.  The defaults
are B<${> and B<}>.  If you override these anchors to both have the same value,
then the optional variable modifiers are not supported nor are nested variables.

B<quote_left> & B<quote_right> - This pair is used to define what balanced
quotes look like in your config file.  By default, it allows you to use either
B<"> or B<'> as a matching pair.  But if you override one of them you must
override both.  And in that case it can only be with literal values.  If the
quotes surrounding a tag's value are balanced, the quotes will be automatically
removed from the value.  If they are unbalanced the quotes will not be removed.

=cut

# B<backquote_left> & B<backquote_right> - This pair is used to surround a command
# you wish to run, just like in Perl itself.  What the command writes to STDOUT
# becomes the tag's value.  Assumes the command takes nothing from STDIN.  Due to
# security concerns you must explicitly set these values yourself before they are
# usable.  A good value is the backqoute itself (B<`>).  But use something else
# if you don't want to be so obvious about it.

=pod

=back

=head2 Modifiers in the trailing Comments for tag/value pairs.

In some cases we need to handle exceptions to the rule.  So we define labels
to tell this module that we need to apply special rules to this tag/value pair.
These labels may appear anywhere in the comment.  So when looking for "EXPORT",
it will match "B<# Please EXPORT me.>", but won't match "B<# EXPORTED>".  This
allows you to put multiple labels in a single comment if needed.

As long as the text is surrounded by white space or punctuation a match will
be found.  It is strongly recommended that you don't use punctuation in your
label when you override one with values of your own.

Here are the labels you may override.

=over 4

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.

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



# ==============================================================
# Get who you're currrently logged in as.
# Put here to avoid circular references between modules.
sub _get_user_id
{
   DBUG_ENTER_FUNC ( @_ );
   my $user = "??";
   eval {
      # Mostly used on unix like systms.
      $user = getpwuid ($<) || "??";
   };
   if ( $@ ) {
      # Can't use on unix due to sudo issue returns wrong user.
      $user = getlogin () || "??";
   }
   DBUG_RETURN ($user);
}

# ==============================================================
# A stub of the source callback function ...
sub _source_callback_stub
{
   DBUG_ENTER_FUNC ( @_ );
   my $file = shift;
   my $opts = shift;
   DBUG_RETURN ( undef, undef );
}


# ==============================================================
# A stub of the encryption/decryption callback function ...
sub _encryption_callback_stub
{
   DBUG_MASK_NEXT_FUNC_CALL (2);   # Mask $value!
   DBUG_ENTER_FUNC ( @_ );
   my $mode   = shift;
   my $tag    = shift;
   my $value  = shift;   # Clear text sensitive value ...
   my $file   = shift;
   my $cbOpts = shift;
   DBUG_MASK ( 0 );
   DBUG_RETURN ( $value );
}


# ==============================================================
# Initialize the global hashes with their default values ...
BEGIN
{
   DBUG_ENTER_FUNC ();

   # ---------------------------------------------------------------------
   # Make sure no hash value is undef !!!
   # ---------------------------------------------------------------------

   # You can only add to this list, you can't remove anything from it!
   # See should_we_hide_sensitive_data () on how this list is used.
   DBUG_PRINT ("INFO", "Initializing the tag patterns to hide from fish ...");
   push ( @hide_from_fish, "password" );
   push ( @hide_from_fish, "pass" );
   push ( @hide_from_fish, "pwd" );

   # ---------------------------------------------------------------------

   DBUG_PRINT ("INFO", "Initializing the READ options global hash ...");
   # Should always be set in the constructor ...
   $default_read_opts{tag_case}   = 0;         # Case sensitive tags.

   # The generic options ...
   my %src_empty;
   $default_read_opts{croak}      = 0;         # Don't croak by default.
   $default_read_opts{export}     = 0;         # Don't export any tag/val pairs.
   $default_read_opts{use_utf8}   = 0;         # Doesn't support utf8/Unicode/Wide Chars.
   $default_read_opts{disable_quotes}     = 0; # Don't disable balanced quotes.
   $default_read_opts{disable_variables}  = 0; # Don't disable variables!
   $default_read_opts{disable_variable_modifiers} = 0; # Don't disable variable modifiers!
   $default_read_opts{disable_decryption} = 0; # Don't disable decryption!
 # $default_read_opts{enable_backquotes}  = 0; # Don't allow random command execution.
   $default_read_opts{trap_recursion}     = 0; # Recursion is ignored, not fatal
   $default_read_opts{source_cb}  = __PACKAGE__->can ("_source_callback_stub");
   $default_read_opts{source_cb_opts} = \%src_empty;

   # The file parsing options ...
   $default_read_opts{assign}          = '=';   # The assignment operator
   $default_read_opts{comment}         = '#';   # The comment symbol
   $default_read_opts{source}          = '.';   # The file source symbol
   $default_read_opts{section_left}    = '[';   # The start section string
   $default_read_opts{section_right}   = ']';   # The end section string
   $default_read_opts{variable_left}   = '${';  # The start variable string
   $default_read_opts{variable_right}  = '}';   # The end variable string

   # Unlikely default values due to security concerns.
   # $default_read_opts{backquote_left}  = '`'x101;  # The start backquote string
   # $default_read_opts{backquote_right} = '`'x102;  # The end backquote string

   # The quote chars ... (Special case doesn't work for anything else.)
   # See  using_default_quotes()  if this changes ...
   $default_read_opts{quote_left} = $default_read_opts{quote_right} = "['\"]";

   # The tag/value modifiers.  These labels are found inside the comments!
   $default_read_opts{export_lbl}  = "EXPORT";    # Label for a single %ENV.
   $default_read_opts{hide_lbl}    = "HIDE";      # Mark as sensitive.
   $default_read_opts{encrypt_lbl} = "ENCRYPT";   # Pending encryption.
   $default_read_opts{decrypt_lbl} = "DECRYPT";   # Already encrypted.
   $default_read_opts{source_file_section_lbl} = "DEFAULT";  # Override default.

   # The Encrypt/Decrypt options ... (Encode/Decode)
   my %empty_encrypt;
   $default_read_opts{alias}               = "";
   $default_read_opts{pass_phrase}         = "";
   $default_read_opts{inherit_pass_phrase} = 0;
   $default_read_opts{encrypt_by_user}     = 0;
   $default_read_opts{encrypt_cb}      = __PACKAGE__->can ("_encryption_callback_stub");
   $default_read_opts{encrypt_cb_opts} = \%empty_encrypt;

   # Special undocumented test prog option for overriding fish in parse_line().
   $default_read_opts{dbug_test_use_case_parse_override} = 0;  # Always off.

   # Special undocumented test prog option for overriding fish in read_config().

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

   DBUG_ENTER_FUNC ( @_ );
   my $str     = shift;

   # The 6 problem chars with special meaning in a RegExp ...
   # Chars:  . + ^ | $ \    (Skips * ?)
   $str =~ s/([.+^|\$\\])/\\$1/g;  

   # As do these 2 of 3 types of brackets: () & {}, not []
   $str =~ s/([(){}])/\\$1/g;

   DBUG_RETURN ( $str );
}

# ==============================================================

=item $sensitive = should_we_hide_sensitive_data ( $tag )

Checks the tag against an internal list of patterns to see if there is a match.
This check is done in a case insensitive way.

If there is a match it will return true and the caller should take care about
writing anything about this tag to any log files.

If there is no match it will return false, and you can write what you please to
your logs.

See I<make_it_sensitive> to add additional patterns to the list.

=cut

sub should_we_hide_sensitive_data
{
   my $tag       = shift;
   my $skip_fish = shift;     # Undocumented ...

   my $sensitive = 0;    # Assume it's not to be hidden!

   foreach my $hide ( @hide_from_fish ) {
      if ( $tag =~ m/${hide}/i ) {
         $sensitive = 1;   # We found a match!  It's sensitive!
      }
   }

   unless ( $skip_fish ) {
      DBUG_ENTER_FUNC ( $tag, $skip_fish, @_ );
      return DBUG_RETURN ( $sensitive );
   }

   return ( $sensitive );
}

# ==============================================================

=item make_it_sensitive ( @patterns )

Add these pattern(s) to the internal list of patterns that this module considers
sensitive.  Should any tag contain this pattern, that tag's value will be
masked when written to this module's internal logs.  Leading/trailing spaces
will be ignored in the pattern.  Wild cards are not honored.

The 3 default patterns are password, pass, and pwd.

This pattern affects all L<Advanced::Config> objects loaded into memory.  Not
just the current one.

=cut

sub make_it_sensitive
{
   DBUG_ENTER_FUNC ( @_ );
   my @tags = @_;

   foreach my $tag ( @tags ) {
      if ( $tag ) {
         $tag =~ s/^\s+//;
         $tag =~ s/\s+$//;
         if ( $tag ) {
            $tag = convert_to_regexp_string ( $tag, 1 );
            push ( @hide_from_fish, $tag );
         }
      }
   }

   DBUG_VOID_RETURN ();
}

# ==============================================================

=item $cnt = sensitive_cnt ( )

Returns a count of how many sensitive patterns are being used.

=cut

sub sensitive_cnt
{
   DBUG_ENTER_FUNC ( @_ );
   DBUG_RETURN ( scalar (@hide_from_fish) );
}

# ==============================================================

=item @ret = croak_helper ($opts, $croak_message, @croak_return_vals)

This helper method helps standardizes what to do on fatal errors when reading
the config file or what to do if you can't find the tag on lookups.

It knows I<\%opts> is a "Read" option hash if B<croak> is a member and it's
a "Get" option hash if B<required> is a member.  Both options use the same
logic when called.

See B<croak> and B<required> on what these options do.

Returns whatever I<@croak_return_vals> references.  It may be a single value or
an array of values.

It calls B<warn> or B<die> with the message passed.

=cut

# ==============================================================

( run in 0.418 second using v1.01-cache-2.11-cpan-39bf76dae61 )