NAME

Authen::Credential - abstraction of a credential

SYNOPSIS

use Authen::Credential;
use Authen::Credential::plain;
use Getopt::Long qw(GetOptions);
use Config::General qw(ParseConfig);
use HTTP::Request;

# creation
$cred = Authen::Credential->new(
    scheme => "plain",
    name   => "system",
    pass   => "manager",
);
# idem directly using the sub-class
$cred = Authen::Credential::plain->new(
    name   => "system",
    pass   => "manager",
);

# get credential from command line option
GetOptions(\%Option,
    "auth=s",
    ...
);
$cred = Authen::Credential->parse($Option{auth});

# get credential from configuration file
%Option = ParseConfig(-ConfigFile => "...");
$cred = Authen::Credential->new($Option{auth});

# access the credential attributes
if ($cred->scheme() eq "plain") {
    printf("user name is %s\n", $cred->name());
}

# use the prepare() method to get ready-to-use data
$req = HTTP::Request->new(GET => $url);
$req->header(Authorization => $cred->prepare("HTTP.Basic"));

DESCRIPTION

This module offers abstractions of credentials, i.e. something that can be used to authenticate. It allows the creation and manipulation of credentials. In particular, it defines a standard string representation (so that credentials can be given to external programs as command line options), a standard structured representation (so that credentials can be stored in structured configuration files or using JSON) and "preparators" that can transform credentials into ready-to-use data for well known targets.

Different authentication schemes (aka credential types) are supported. This package currently supports none, plain and x509 but others can be added by providing the supporting code in a separate module.

A Python implementation of the same credential abstractions is available at http://pypi.python.org/pypi/auth.credential so credentials can be shared between different programming languages.

For a given scheme, a credential is represented by an object with a fixed set of string attributes. For instance, the plain scheme has two attributes: name and pass. More information is provided by the scheme specific module, for instance Authen::Credential::plain.

STRING REPRESENTATION

The string representation of a credential is made of its scheme followed by its attributes as key=value pairs, seperated by space.

For instance, for the none scheme with no attributes:

none

And the the plain scheme with a name and password:

plain name=system pass=manager

If needed, the characters can be URI-escaped, see URI::Escape. All non-alphanumerical characters should be escaped to avoid parsing ambiguities.

The string representation is useful to give a program through its command line options. For instance:

myprog --uri http://foo:80 --auth "plain name=system pass=manager"

STRUCTURED REPRESENTATION

The structured representation of a credential is made of its scheme and all its attributes as a string table.

Here is for instance how it could end up using JSON:

{"scheme":"plain","name":"system","pass":"manager"}

The same information could be stored in a configuration file. Here is an example using the Apache syntax, which is for instance supported by Config::General:

<auth>
  scheme = plain
  name   = system
  pass   = manager
</auth>

METHODS

This module supports the following methods:

new([OPTIONS])

return a new credential object (class method); the OPTIONS are its attributes

parse(STRING)

return a new credential object from its string representation (class method)

hash()

return its structured representation as a reference to a hash

string()

return its string representation

check()

check that the credential contains the expected attributes

prepare(TARGET)

use the credential to prepare data for a given target (this is scheme specific)

scheme()

return the authentication scheme of the credential

In addition, the attributes can be accessed using eponymous methods. See the example in the "SYNOPSIS" section.

SEE ALSO

Authen::Credential::none, Authen::Credential::plain, Authen::Credential::x509, URI::Escape,

AUTHOR

Lionel Cons http://cern.ch/lionel.cons

Copyright (C) CERN 2011-2013

cpanm Authen::Credential

perl -MCPAN -e shell
install Authen::Credential