view release on metacpan or  search on metacpan

lib/XML/Compile/WSS/Signature.pod  view on Meta::CPAN

=encoding utf8

=head1 NAME

XML::Compile::WSS::Signature - WSS Signatures

=head1 INHERITANCE

 XML::Compile::WSS::Signature
   is a XML::Compile::WSS

=head1 SYNOPSIS

 # You may need a few constants
 use XML::Compile::WSS::Util  qw/:dsig/;
 use XML::Compile::C14N::Util qw/:c14n/;

 # This modules van be used "stand-alone" ...
 my $schema = XML::Compile::Cache->new(...);
 my $sig    = XML::Compile::WSS::Signature->new
   (sign_method => DSIG_RSA_SHA1, ...);

 # ... or as SOAP slave (strict order of object creation!)
 my $wss    = XML::Compile::SOAP::WSS->new;
 my $wsdl   = XML::Compile::WSDL11->new($wsdlfn);
 my $sig    = $wss->signature(sign_method => ...);

=head1 DESCRIPTION

B<WARNING: Only limited real-life experience.>  Many optional
extensions have never been tried.

B<WARNING: RedHat derivates> like RedHat, Fedora, and AlmaLinux recently
actively disable SHA1 support.  You may set their systemwide cryptopolicy
to 'LEGACY', but better use SHA256 or higher.  Defaults of this module
still use SHA1, which might change in the future.

The generic Web Service Security protocol is implemented by the super
class L<XML::Compile::WSS|XML::Compile::WSS>.  This extension implements cypto signatures.

On this moment, there are two versions of this standard:

=over 4

=item * F<http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/>

=item * F<http://www.w3.org/TR/xmldsig-core2/>

=back

One or more elements of a (SOAP) document can be selected to be signed. They
are canonalized (serialized in a well-described way) and then digested
(usually via SHA1).  The digest is put in a C<SignedInfo> component of
the C<Signature> element in the C<Security> header.  When all digests
are in place, the whole SignedInfo structure gets signed.

Extends L<"DESCRIPTION" in XML::Compile::WSS|XML::Compile::WSS/"DESCRIPTION">.
 
=head2 Limitations

Many companies use their own selection from a large the pile of standards
for this feature.  Some of the resulting limitations are known by the author:

=over 4

=item * digests

Only digest algorithms which are provided via the Digest module are
supported for the elements to be signed.  (But that's quite a lot)

=item * signatures

Only a limited subset of signing (algorithm, hash) combinations are
supported.  Lower on this page, you find details about each of the
provided signing implementations.

=back

=head1 METHODS

Extends L<"METHODS" in XML::Compile::WSS|XML::Compile::WSS/"METHODS">.
 
=head2 Constructors

Extends L<"Constructors" in XML::Compile::WSS|XML::Compile::WSS/"Constructors">.
 
=over 4

=item XML::Compile::WSS::Signature-E<gt>B<new>(%options)

The %options you provide here, will will passed to various objects
which are created automatially.  But you may also give pre-instantiated
objects, for instance when you decide to use your own extension on a
certain spot.

 -Option      --Defined in       --Default
  checker                          undef
  key_info                         {}
  prepare       XML::Compile::WSS  'ALL'
  remote_token                     undef
  schema        XML::Compile::WSS  undef
  sign_types                       <required>
  signed_info                      {}
  signer                           DSIG_RSA_SHA1
  token                            <depends on sign_method>
  version       XML::Compile::WSS  undef
  wss_version   XML::Compile::WSS  '1.1'