NAME

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

DESCRIPTION

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

SYNOPSIS

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

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

  my $verifier = Authen::NZRealMe->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::NZRealMe->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.

sign_multiple_targets ( $xml, $target_ids )

Takes an XML document and an array of hashes representing the ID and InclusiveNamespaces of any DOM elements to sign, identified by an ID attribute value. The input array should resemble this example:

        [ {
            id          => 's23a05470f2ac691e7ebc19a90b8f04a6336dad2fe',
            namespaces  => ['soap'],
        },  {
            id          => 's254212e7245af1ee3a909a364273b0be7726e8808',
        } ]

The name of the attribute is determined by the id_attr method above. The document will have a signature block generated and inserted into it, and the method will return a string of the document and it's included signatures.

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::NZRealMe for documentation index.

LICENSE AND COPYRIGHT

Copyright (c) 2010-2014 Enrolment Services, New Zealand Electoral Commission

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.

cpanm Authen::NZRealMe

perl -MCPAN -e shell
install Authen::NZRealMe