Authen-Prepare

 view release on metacpan or  search on metacpan

META.yml  view on Meta::CPAN

---
name: Authen-Prepare
version: 0.05
author:
  - 'David Narayan  C<< <dnarayan@cpan.org> >>'
abstract: Prepare a set of authentication credentials
license: perl
resources:
  license: http://dev.perl.org/licenses/
requires:
  Carp: 0
  Fcntl: 0
  File::Spec: 0.80
  IO::Prompt: 0
  Readonly: 0
  Text::Glob: 0

README  view on Meta::CPAN

Authen-Prepare version 0.05

DESCRIPTION

    Authen::Prepare sets up authentication credentials for a specific
    hostname, username, and password using a combination of stored
    information and user prompts. These credentials can be used in other
    scripts or modules that require authentication information. Using this
    module allows these other scripts to be flexible in their usage of
    authentication information without recoding user prompts or storing
    passwords in the code.

    The simplest use of this module is to create the initial object it with
    no arguments; the credentials will be built from a set of user prompts.

    A more full-featured use of this module is to specify all authentication
    information ahead of time using a password file and command-line
    arguments or environment variables. The initial object can then be
    created with three named arguments (hostname, username, and passfile)
    and the credentials for the specified hostname and username will be
    extracted from the password file. This allows the calling script to be
    used in an automated environment.

    Any combination of the named arguments can be provided; the user will be
    prompted for any missing information.

  Password File
    The password file must not have any group or world permissions in order
    to be usable by this module. Each line of the password file should
    contain the hostname, username, and password separated by a colon.

examples/authen_prompt_all.pl  view on Meta::CPAN

#!perl
use strict;
use warnings;
use Authen::Prepare 0.04;
use Smart::Comments;

# Prompt for everything
my %auth = Authen::Prepare->new->credentials();

### %auth

examples/authen_prompt_none.pl  view on Meta::CPAN

use Authen::Prepare 0.04;
use Smart::Comments;

# Prompt for nothing: read 'mypassfile' for the password
my %auth = Authen::Prepare->new(
    {
        hostname => 'myhost',
        username => 'myuser',
        passfile => 'mypassfile',
    }
)->credentials();

### %auth

lib/Authen/Prepare.pm  view on Meta::CPAN

# Constants

Readonly my $DEFAULT_TIMEOUT => 10;
Readonly my $EMPTY_STR       => q{};
Readonly my $FIELD_DELIMITER => q{:};
Readonly my $PASSWORD_CHAR   => q{*};

#------------------------------------------------------------------------------
# Methods

sub credentials {
    my ($self) = @_;
    my $prefix = $self->prefix || $EMPTY_STR;

    my %cred = (
        hostname => $self->_prompt_while_empty(
            $self->hostname, qq|${prefix}Hostname: |
        ),
        username => $self->_prompt_while_empty(
            $self->username, qq|${prefix}Username: |
        ),

lib/Authen/Prepare.pm  view on Meta::CPAN

    return ( defined $response ) ? qq{$response} : $EMPTY_STR;
}

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

1;    # Magic true value required at end of module
__END__

=head1 NAME

Authen::Prepare - Prepare a set of authentication credentials


=head1 VERSION

This document describes Authen::Prepare version 0.05


=head1 SYNOPSIS

    use Authen::Prepare;

    # Prompt for the hostname, username, and password
    my $authen = Authen::Prepare->new();

    # The '%cred' hash now has the keys 'hostname', 'username', 
    # and 'password'
    my %cred = $authen->credentials();

    # Specify hostname as 'localhost'. Prompt for username and password
    my $authen = Authen::Prepare->new( { hostname => 'localhost' } );
    my %cred = $authen->credentials();

    # Specify a hostname as 'localhost', username as 'testuser', and a 
    # password file as '~/.authrc'. No prompting will occur if the 
    # hostname and username are found in the password file.
    my $authen = Authen::Prepare->new( 
        { 
            hostname => 'localhost',
            username => 'testuser',
            passfile => '~/.authrc',
        } 
    );

    my %cred = $authen->credentials();

    # Assuming %opt contains the set of command-line arguments, specify 
    # the hostname, username, and password file with the command-line 
    # arguments or with environment variables as a fallback.  
    my $authen = Authen::Prepare->new( 
        { 
            hostname => $opt{hostname} || $ENV{MY_HOSTNAME},
            username => $opt{username} || $ENV{MY_USERNAME},
            passfile => $opt{passfile} || $ENV{MY_PASSFILE},
        } 
    );

    my %cred = $authen->credentials();
  
    # The '%cred' hash can be used to authenticate in scripts or modules with
    # the stored hostname, username, and password
    $foo->authenticate(%cred);
  

=head1 DESCRIPTION

Authen::Prepare sets up authentication credentials for a specific hostname,
username, and password using a combination of stored information and user
prompts. These credentials can be used in other scripts or modules that
require authentication information. Using this module allows these other
scripts to be flexible in their usage of authentication information without
recoding user prompts or storing passwords in the code.

The simplest use of this module is to create the initial object it with no
arguments; the credentials will be built from a set of user prompts.

A more full-featured use of this module is to specify all authentication
information ahead of time using a password file and command-line arguments or
environment variables. The initial object can then be created with three named
arguments (hostname, username, and passfile) and the credentials for the
specified hostname and username will be extracted from the password file. This
allows the calling script to be used in an automated environment.

Any combination of the named arguments can be provided; the user will be
prompted for any missing information.

=head2 Password File

The password file must not have any group or world permissions in order to be
usable by this module. Each line of the password file should contain the

lib/Authen/Prepare.pm  view on Meta::CPAN

=head1 INTERFACE 

=over

=item new()

=item new(\%options)

The constructor 'new' creates the initial object and sets up the cached
credentials for a hostname, username, and password file. If the hostname,
username, or passfile accessors are not specified, the user will be prompted.

Any of the accessors (see below) can be used as named arguments.

  Example:
  # Prompt for everything
  my $authen = Authen::Prepare->new();

  # Prompt for hostname. Use specified username and passfile
  my $authen = Authen::Prepare->new(
    { username => $username, passfile => $passfile });

  # Prompt for username. Use specified hostname and passfile
  my $authen = Authen::Prepare->new(
    { hostname => $hostname, passfile => $passfile });

  # Prompt for password. Use specified hostname and username
  my $authen = Authen::Prepare->new(
    { hostname => $hostname, username => $username });

=item credentials()

The 'credentials' method returns the cached credentials in the form of a hash
with the following keys:

  * hostname
  * username
  * password

Note: This method is context sensitive: in scalar context, it will return a
hash reference.

=back

lib/Authen/Prepare.pm  view on Meta::CPAN

The password file doesn't exist or invalid permissions. Make sure the password
file has no 'group' or 'other' permissions and is formatted correctly.

=back


=head1 CONFIGURATION AND ENVIRONMENT

Authen::Prepare requires no configuration files or environment variables.

An optional password file may be used to store authentication credentials.
Environment variables from calling scripts may be used to specify one or more
of the named arguments to the constructor (e.g. $ENV{MY_HOSTNAME} or
$ENV{MY_PASSFILE}).

=head1 DEPENDENCIES

=over

=item IO::Prompt

t/01.passfile.t  view on Meta::CPAN

#------------------------------------------------------------------------------
# Tests

test_check_passfile();

test_get_password_default();
test_get_password_nomatch_hostname();
test_get_password_handle_comment();

test_credentials();
test_credentials_with_prefix();

#------------------------------------------------------------------------------
# Subroutines

sub create_passfile {
    my ( $arg_ref, $callback ) = @_;
    my ( $fh,      $filename ) = tempfile();
    my $entry = join( q{:}, @$arg_ref{qw(hostname username)} ) . q{:testpass};

    open $fh, '>', $filename or die $!;

t/01.passfile.t  view on Meta::CPAN

    return;
}

sub add_passfile_default {
    my ($fh) = @_;
    print $fh qq{*:defaultuser:defaultpass\n};

    return;
}

sub test_credentials {
    my $passfile = create_passfile( \%arg );
    my $authen   = Authen::Prepare->new( { %arg, passfile => $passfile } );
    my %cred     = $authen->credentials();

    is( $cred{hostname}, 'localhost', 'Hostname is correct' );
    is( $cred{username}, 'testuser',  'Username is correct' );
    is( $cred{password}, 'testpass',  'Password is correct' );
}

sub test_credentials_with_prefix {
    my $passfile = create_passfile( \%arg );
    my $authen   = Authen::Prepare->new(
        { %arg, passfile => $passfile, prefix => 'p ' } );

    warning_is { $authen->credentials(); } undef,
        'No warnings when using prefix';

    $authen->prefix(q{});
    warning_is { $authen->credentials(); } undef,
        'No warnings when using empty prefix';
}

sub test_get_password_handle_comment {
    my $passfile = create_passfile( \%arg, \&add_passfile_comment );
    my $authen = Authen::Prepare->new( { passfile => $passfile } );
    my $password = $authen->_get_password_for( '# commentedhost', 'user' );

    is( $password, 'rightpass', 'Handled comments' );