=head1 NAME

XML::Compile::WSS::BasicAuth - username/password security

=head1 INHERITANCE

 XML::Compile::WSS::BasicAuth
   is a XML::Compile::WSS

=head1 SYNOPSIS

 # you need a few constants
 use XML::Compile::WSS::Util  qw/:utp11/;

 # used in combination with any other XML schema
 my $auth = XML::Compile::WSS::BasicAuth->new
   ( schema   => $anything
   , username => $user
   , password => $password
   );

 # connects itself to a WSDL
 my $wss  = XML::Compile::SOAP::WSS->new;
 my $wsdl = XML::Compile::WSDL11->new($wsdlfn);
 my $auth = $wss->basicAuth
   ( ... same params, except 'schema'
   );

=head1 DESCRIPTION

The generic Web Service Security protocol is implemented by the super
class L<XML::Compile::WSS|XML::Compile::WSS>.  This extension implements "basic authentication",
i.e. username/password validation.

You can best use digested passwords (UTP11_PDIGEST)  In that case,
a timestamp, a nonce and SHA1 hashing will keep the password a secret.

=head1 METHODS

=head2 Constructors

=over 4

=item XML::Compile::WSS::BasicAuth-E<gt>B<new>(OPTIONS)

 -Option     --Defined in       --Default
  created                         undef
  nonce                           'RANDOM'
  password                        <required>
  pwformat                        UTP11_PTEXT
  schema       XML::Compile::WSS  undef
  username                        <required>
  version      XML::Compile::WSS  undef
  wss_version  XML::Compile::WSS  '1.1'
  wsu_Id                          undef

=over 2

=item created => DATETIME

See L<XML::Compile::WSS::dateTime()|XML::Compile::WSS/"Helpers"> for choices of DATETIME.

=item nonce => STRING|CODE|'RANDOM'

Only used then the password is passed as digest.  This will cause the
C<wsse:Nonce> element.

When you pass a CODE, it will get called for each message to produce a
STRING. The constant text 'RANDOM' will have a random nonce generator
being called at each message.

=item password => STRING

The password in plain text.  Use pwformat digest to send it encrypted
over the network.

=item pwformat => UTP11_PTEXT|UTP11_PDIGEST

With C<UTP11_PTEXT>, the plain-text version of the password is shown.
If PTWTYPE IS C<UTP11_PDIGEST>, the plain-text password will be
encrypted with SHA1.  The OPTIONS can be used to salt the digest
with "nonce" and/or "created" information before the encryption.

=item schema => an L<XML::Compile::Cache|XML::Compile::Cache> object

=item username => STRING

=item version => STRING

=item wss_version => '1.1'|MODULE

=item wsu_Id => STRING

Adds a C<wsu:Id> attribute to the created element.

=back

=back

=head2 Attributes

=over 4

=item $obj-E<gt>B<created>()

=item $obj-E<gt>B<nonce>()

=item $obj-E<gt>B<password>()

=item $obj-E<gt>B<schema>()

See L<XML::Compile::WSS/"Attributes">

=item $obj-E<gt>B<username>()

=item $obj-E<gt>B<wssVersion>()

See L<XML::Compile::WSS/"Attributes">

=item $obj-E<gt>B<wsuId>()

=back

=head2 Apply

=over 4

=item $obj-E<gt>B<check>(SECURITY)

See L<XML::Compile::WSS/"Apply">

=item $obj-E<gt>B<create>(DOC, SECURITY, DATA)

See L<XML::Compile::WSS/"Apply">

=back

=head2 Helpers

=over 4

=item $obj-E<gt>B<dateTime>(TIME|STRING|HASH)

See L<XML::Compile::WSS/"Helpers">

=back

=head2 Internals

=over 4

=item $obj-E<gt>B<loadSchemas>(SCHEMA, VERSION)

=item XML::Compile::WSS::BasicAuth-E<gt>B<loadSchemas>(SCHEMA, VERSION)

See L<XML::Compile::WSS/"Internals">

=item $obj-E<gt>B<writerHookWsuId>(TYPE)

See L<XML::Compile::WSS/"Internals">

=back

=head1 SEE ALSO

This module is part of XML-Compile-WSS distribution version 1.04,
built on November 01, 2012. Website: F<http://perl.overmeer.net/xml-compile/>

Other distributions in this suite:
L<XML::Compile>,
L<XML::Compile::SOAP>,
L<XML::Compile::SOAP12>,
L<XML::Compile::SOAP::Daemon>,
L<XML::Compile::SOAP::WSA>,
L<XML::Compile::C14N>,
L<XML::Compile::WSS>,
L<XML::Compile::WSS::Signature>,
L<XML::Compile::Tester>,
L<XML::Compile::Cache>,
L<XML::Compile::Dumper>,
L<XML::Compile::RPC>,
L<XML::Rewrite>,
L<XML::eXistDB>,
and
L<XML::LibXML::Simple>.

Please post questions or ideas to the mailinglist at
F<http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile>

For live contact with other developers, visit the C<#xml-compile> channel
on C<irc.perl.org>.

=head1 LICENSE

Copyrights 2011-2012 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>