The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
XML-Compile-WSS-1.03
River stage one • 4 direct dependents • 5 total dependents
2 ++
/ XML::Compile::WSS::Signature

NAME

XML::Compile::WSS::Signature - WSS in CICS-TS style

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.

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
  digest_method                            DSIG_SHA1
  prefix_list                              [ds wsu xenc SOAP-ENV]
  private_key                              undef
  public_key                               <depends on sign_method>
  public_key_id                            'public-key'
  public_key_type                          <depends on sign_method>
  publish_pubkey                           'INCLUDE_BY_REF'
  remote_pubkey                            undef
  remote_pubkey_encoding                   undef
  remote_pubkey_type                       XTP10_X509
  remote_sign_method                       DSIG_RSA_SHA1
  schema                  XML::Compile::WSS  undef
  sign_method                              DSIG_RSA_SHA1
  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.

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 sign_method. Usually, you can specify an OBJECT which contains the key, or STRING or FILENAME to create such an object.

public_key => OBJECT|STRING|FILENAME

In some cases, the public key can be derived from the private key.

public_key_id => STRING
public_key_type => KEYTYPE

The KEYTYPE must be specified in the SignedInfo. It depends on the sign_method which default is taken.

publish_pubkey => 'INCLUDE_BY_REF'|CODE

How to publish the public key. The INCLUDE_BY_REF constant (currently the only one supported) will add the key as BinarySecurityToken in the message, plus a keyinfo structure with a reference to that token.

remote_pubkey => OBJECT|STRING|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_pubkey 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.

remote_pubkey_encoding => ENCODING

Used when remote_pubkey is a STRING or FILENAME. Usually WSM10_BASE64, to indicate that the key is in base64 encoding. When not defined, the key is in binary format.

remote_pubkey_type => KEYTYPE

Used when remote_pubkey is a STRING or FILENAME.

remote_sign_method => SIGNMETHOD

Used when the remote_pubkey is specified.

schema => an XML::Compile::Cache object
sign_method => SIGN

The choices here are explained below, in the "DETAILS" section of this manual page.

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

Attributes

$obj->schema()

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

$obj->version()

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

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

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.

Canonicalization

$obj->canon([CANON])

Returns information about canonicalization method CANON. By default the algoritm of defaultCanonMethod().

$obj->defaultCanonMethod()

Returns the default Canonicalization method as constant.

$obj->prefixList()

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

KeyInfo

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->signMethod()

Internals

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

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

DETAILS

Specifications

Signing, the generic part

The base of this whole security protocol is crypto-signing the messages, so you will always need to specify some parameters for new().

  my $wss  = XML::Compile::WSS::Signature->new
    ( sign_method => DSIG_$algo
    , ...parameters for $algo...
    );

When the algorithm is known (see the next sections of this chapter), then the parameters will be used to produce the CODE which will do the signing.

Defend against man-in-the-middle

The signature can easily be spoofed with a man-in-the-middle attack, unless you hard-code the remote's public key.

  my $wss  = XML::Compile::WSS::Signature->new
    ( ...
    , remote_sign_method     => DSIG_RSA_SHA1    # default
    , remote_pubkey_type     => XTP10_X509       # default
    , remote_pubkey_encoding => WSM10_BASE64
    , remote_pubkey          => $base64_enc_key_string
    );

  my $wss  = XML::Compile::WSS::Signature->new
    ( ...
    , remote_sign_method     => DSIG_RSA_SHA1    # default
    , remote_pubkey          => $key
      # $key is a Crypt::OpenSSL::RSA public key object
    );

Signing with RSA

Limitations

The signing algorithm uses Crypt::OpenSSL::RSA. According to its manual-page, the current implementation is limited to

  • sign_method

       DSIG_RSA_SHA1     DSIGM_RSA_MD5     DSIGM_RSA_SHA256
   DSIGM_RSA_SHA384  DSIGM_RSA_SHA512

    It could support some RSA_RIPEMD160, however there is no official constant for that in the standards.

  • public_key_type

      XTP10_X509         XTP10_X509PKI

Usages

Example:

  my $wss  = XML::Compile::WSS::Signature->new
     ( sign_method     => DSIG_RSA_SHA1
     , private_key     => $privkey
     , public_key_type => XTP10_X509       # default
     , public_key      => $pubkey          # default from $privkey
     , public_key_id   => 'public-key'     # default
     , publish_pubkey  => 'INCLUDE_BY_REF' # default
     );

Private key

You have to provide the private key. There are various ways to do that. Valid values for $privkey in above example:

a Crypt::OpenSSL::RSA object

containing the private key, for instance created via its new_private_key() method.

a filename

The private key is read from the FILENAME. Typically, the filename ends on ".pem".

a string

The private key is provided as string, formatted the same way as a PEM file looks.

Public key

With public_key_type, you specify the format of the public key. By default, the XTP10_X509 is taken. You may also specify other XTP10_* constants XML::Compile::WSS::Util tag-group :xtp10.

For the public_key, you have the same options as for the private_key option, although the object is created with new_public_key this time. If the $pubkey is not provided, the $privkey object is used.

The publish_pubkey can be a prefined constant or a CODE reference. This function will be called then the wsse:Security structure is being constructed. It puts the public key information in the right Perl structure to be translated into XML automatically. The only defined constant is INCLUDE_BY_REF.

SEE ALSO

This module is part of XML-Compile-WSS distribution version 1.03, built on October 26, 2012. 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::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 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 http://www.perl.com/perl/misc/Artistic.html