The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Authen-NZigovt-1.08
++
/ Authen::NZigovt::XMLSig

NAME

Authen::NZigovt::XMLSig - XML digital signature generation/verification

DESCRIPTION

This module implements the subset of http://www.w3.org/TR/xmldsig-core/ required to interface to the New Zealand igovt logon service using SAML 2.0 messaging.

SYNOPSIS

  my $signer = Authen::NZigovt->class_for('xml_signer')->new(
      key_file => $path_to_private_key_file,
  );

  my $signed_xml = $signer->sign($xml, $target_id);

  my $verifier = Authen::NZigovt->class_for('xml_signer')->new(
      pub_cert_text => $self->signing_cert_pem_data(),
  );

  $verifier->verify($xml);

METHODS

new( )

Constructor. Should not be called directly. Instead, call:

  Authen::NZigovt->class_for('xml_signer')->new( options );

Options are passed in as key => value pairs.

When creating digital signatures, a private key must be passed to the constructor using either the key_text or the key_file option.

When verifying digital signatures, a public key is required. This may be passed in using the pub_key_text option or it will be extracted from the X509 certificate provided in the pub_cert_text or the pub_cert_file option.

id_attr( )

Returns the name of the attribute used to identify the element being signed. Defaults to 'ID'. Can be set by passing an id_attr option to the constructor.

sign( $xml, $target_id )

Takes an XML document and an optional element ID value and returns a string of XML with a digital signature added. The XML document can be provided either as a string or as an XML::LibXML DOM object.

default_target_id( )

When signing a document, if no target ID is provided, this method is used to find the first element with an 'ID' attribute.

rsa_signature( $plaintext, $eol )

Takes a plaintext string, calculates an RSA signature using the private key passed to the constructor and returns a base64-encoded string. The $eol parameter can be used to specify the line-ending character used in the base64 encoding process (default: \n).

verify( $xml )

Takes an XML string (or DOM object); searches for signature elements; verifies the provided signature and message digest for each; and returns true on success.

If the provided document does not contain any signatures, or if an invalid signature is found, an exception will be thrown.

key_text( )

Returns the private key text which will be used to initialise the Crypt::OpenSSL::RSA object used for generating signatures.

pub_key_text( )

Returns the public key text used to initialise the Crypt::OpenSSL::RSA object used for verifing signatures.

pub_cert_text( )

If the public key is being extracted from an X509 certificate, this method is used to retrieve the text which defines the certificate.

SEE ALSO

See Authen::NZigovt for documentation index.

LICENSE AND COPYRIGHT

Copyright (c) 2010-2011 the New Zealand Electoral Enrolment Centre

Written by Grant McLean <grant@catalyst.net.nz>

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.