/ 
XML-Compile-WSS-Signature-1.06
River stage zero No dependents
/ XML::Compile::WSS::Signature

NAME

XML::Compile::WSS::Signature - WSS Signatures version 1

INHERITANCE

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

SYNOPSIS

WARNING: under development!

# You may need a few of these
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 => DSGIG_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 => ...);

DESCRIPTION

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

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

http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/
http://www.w3.org/TR/xmldsig-core2/

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

Limitations

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

  • digests

    Only digest algorithms which are provided via the Digest module are supported for the elements to be signed.

  • signatures

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

METHODS

Constructors

XML::Compile::WSS::Signature->new(OPTIONS)
-Option       --Defined in       --Default
 canon_method                      C14N_EXC_NO_COMM
 checker                           undef
 digest_method                     DSIG_SHA1
 prefix_list                       [ds wsu xenc SOAP-ENV]
 private_key                       undef
 publish_token                     'INCLUDE_BY_REF'
 remote_token                      undef
 schema         XML::Compile::WSS  undef
 signer                            DSIG_RSA_SHA1
 token                             <depends on sign_method>
 version        XML::Compile::WSS  undef
 wss_version    XML::Compile::WSS  '1.1'
canon_method => CANON

The algorithm to be used for canonicalization of some component. These constants are pre-defined with nice C14N_* names in XML::Compile::C14N::Util.

checker => OBJECT|HASH|TYPE

The signer object with server information, anything what is accepted by XML::Compile::WSS::Sign::fromConfig(). When provided, we do not need to collect the information from the incoming messages.

digest_method => DIGEST

The algorithm used to sign the body digest, when sending. The digest name is an ugly constant which has a nice DSIG_* alias defined in XML::Compile::WSS::Util.

prefix_list => ARRAY

Used for canonicalization.

private_key => OBJECT|STRING|FILENAME

The exact features of this option depend on the signing method. Usually, you can specify an OBJECT which contains the key, or STRING or FILENAME to create such an object.

publish_token => 'INCLUDE_BY_REF'|'NO'|CODE

How to publish the security token. The INCLUDE_BY_REF constant will add the token as BinarySecurityToken in the message, plus a keyinfo structure with a reference to that token. See publishToken()

remote_token => OBJECT|HASH|FILENAME

To defend against man-in-the-middle attacks, you need to specify the server's public key. When specified, that key will be used to verify the signature, not the one listed in the XML response.

Only when this remote_token is specified, we will require the signature. Otherwise, the check of the signature will only be performed when a Signature is available in the Security header.

schema => an XML::Compile::Cache object
signer => OBJECT|HASH|TYPE

The client-side signer object, anything what is accepted by XML::Compile::WSS::Sign::fromConfig().

token => OBJECT|HASH|FILENAME

The client's token, anything which is accepted by XML::Compile::WSS::SecToken::fromConfig().

version => STRING
wss_version => '1.1'|MODULE

Attributes

$obj->schema()

See "Attributes" in XML::Compile::WSS

$obj->wssVersion()

See "Attributes" in XML::Compile::WSS

Digest

$obj->defaultDigestMethod()

Returns the default DIGEST constant, as set with new(digest_method).

This must be a full constant name, as provided by XML::Compile::WSS::Util. They are listed under export tags :dsig and :dsigm.

$obj->digest(DIGEST, TEXTREF)

Digest the text (passed as TEXTREF for reasons of performance) into a binary string.

$obj->digester(DIGEST)

Canonicalization

With "canonicalization" you apply a set of rules to translate an XML structure into a standardized ("canonical") format.

XML offers freedom on where to put namespace declarations, blanks between elements, order of attributes, and so on. However, when you want to sign an element, meaningless changes do change the result. Canonical format enforces a set of rules, and produces bytes.

The "Digital Signature v1" supports c14n. DSIG version 2 uses c14n2... which is not yet supported.

$obj->applyCanon(ALGORITHM, ELEMENT, PREFIXLIST)

Returned is an canonicalized byte string of the ELEMENT. The ALGORITHM is one of the C14N* constants defined in XML::Compile::C14N::Util.

$obj->c14n()

Returns the XML::Compile::C14N object which handles canonicalization.

$obj->canonicalizer()

Returns the default canonicalizer, a CODE which is called with a NODE to return a normalized byte representation of the DOM tree.

$obj->defaultCanonMethod()

Returns the default Canonicalization method as constant.

$obj->defaultPrefixList()

Returns an ARRAY with the prefixes to be used in canonicalization.

Security Tokens

To prove the signature, there usually is some security token. This token may (or may not) be included in the SOAP message itself.

$obj->includeKeyInfo()

Returns a CODE, which is called with the XML::LibXML::Document and returns a HASH with KeyInfo data.

$obj->publishToken()

Returns a CODE, which is called with the XML::LibXML::Document and the HASH of the Security structure which is under construction. The CODE will put a (type,node) in that HASH.

$obj->remoteToken()

Returns the security token of the server, which is an XML::Compile::WSS::SecToken object. Either, this token is provided by new(remote_token), to taken from the first message.

$obj->token()

Returns the security token, which is an XML::Compile::WSS::SecToken object.

Signing

$obj->checkElement(ELEMENT)

Register the ELEMENT to be checked for correct signature.

$obj->checker()

When the remote public key is specified explicitly, this will return the code-reference to check it received SignedInfo.

$obj->createSignature(DOCUMENT)

Must be called after all elements-to-be-signed have been created, but before the SignedInfo object gets serialized.

$obj->elementsToCheck()

Returns a HASH with (wsu-id, node) pairs to be checked. The administration is reset with this action.

$obj->elementsToSign()

Returns an ARRAY of all NODES which need to be signed. This will also reset the administration.

$obj->signElement(NODE, OPTIONS)

Add an element to be the list of NODEs to be signed. For instance, the SOAP message will register the SOAP-ENV:Body here.

-Option--Default
 id      unique
id => UNIQUEID

Each element to be signed needs a wsu:Id to refer to. If the NODE does not have one, the specified UNIQUEID is taken. If there is none specified, one is generated.

$obj->signer()

Returns to XML::Compile::WSS::Sign which is used by the client to sign the messages to be sent.

Apply

$obj->check(SECURITY)

See "Apply" in XML::Compile::WSS

$obj->create(DOC, SECURITY, DATA)

See "Apply" in XML::Compile::WSS

Helpers

$obj->dateTime(TIME|STRING|HASH)

See "Helpers" in XML::Compile::WSS

Internals

$obj->loadSchemas(SCHEMA, VERSION)
XML::Compile::WSS::Signature->loadSchemas(SCHEMA, VERSION)

See "Internals" in XML::Compile::WSS

$obj->writerHookWsuId(TYPE)

See "Internals" in XML::Compile::WSS

SEE ALSO

This module is part of XML-Compile-WSS-Signature distribution version 1.06, built on January 10, 2013. Website: http://perl.overmeer.net/xml-compile/

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

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

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

LICENSE

Copyrights 2012-2013 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 http://www.perl.com/perl/misc/Artistic.html