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.

Other recognised options are:

c14n_method

The canonicalisation method to use when creating a signature block. Default is 'ec14n'.

include_x509_cert

A boolean flag indicating whether the generated signature should include an X509 representation of the certificate with public key required to verify the signature.

signature_algorithm

The signature algorithm to use when creating a signature block. Default is 'rsa_sha1'.

reference_digest_method

The digest method to use when creating a reference element in a signature block. Default is 'sha1'.

reference_transforms

The list of transforms to usewhen creating a reference element in a signature block. Must be specified as an arrayref. Default is [ 'env_sig', 'ec14n' ].

id_attr( )

Returns the name of the attribute used to identify the element being signed. By default the attribute name is not used at all and the element references are resolved by matching the URI to any attribute value. Can be set by passing an id_attr option to the constructor.

sign( $xml, $target_id, options ... )

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.

Named options can be provided to customise the transforms and algorithms used when generating the signature block. In particular, the references option can be used to supply a list of multiple references. In which case, a value of undef should be provided for the $target_id parameter:

  my $refs = [
      { ref_uri => $first_uri_value },
      { ref_uri => $second_uri_value },
  ];
  $signer->sign($xml, undef, references => $ref);

Each reference can include a list of namespace prefixes to be included in the canonicalisation transform.

create_detached_signature( $plaintext, $eol )

Takes a plaintext string, calculates a signature using the private key (and optionally the signarture algorithm) 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_detached_signature( $plaintext, $base64_sig )

Takes a plaintext string, and a base64-encoded signature. Verifies the signature using the public key or certificate supplied to the constructor. Returns true if the signature is valid, and false otherwise.

verify( $xml, $selector_xpath, @namespaces )

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. The caller would then typically use find_verified_element() to ensure that subsequent queries target element which were covered by a verified signature.

The $selector_xpath can be used to identify which <Signature> element should be checked. This is particularly useful with documents containing multiple signatures where each was creaated using a different key (since the API only provides for a single cert/public key). If not provided, a default selector of '//ds:Signature' will be used.

If provided, the value for $selector_xpath may use 'ds' as a namespace prefix for digital signature elements. If any other namespaces are required, the following arguments are assumed to be prefix => uri pairs. For example this code might be used to verify signatures in the SOAP envelope while ignoring signatures in the payload withing the SOAP body:

    my $selector = '//ds:Signature[not(ancestor::soap12:Body)]';
    $verifier->verify($xml, $selector, NS_PAIR('soap12'));

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

find_verified_element( $xc, $xpath )

This method is a wrapper around the standard XML::LibXML findnodes() method, which also confirms that the matching node is within one of the signed fragments which were identified by the earlier call to the verify() method.

The caller must provide an XML::LibXML::XPathContext object with registered URIs for all namespace prefixes required by the supplied XPath expression.

ignore_bad_signatures( )

Calling this method after verify() will tag the root element as a verified fragment. This is used in cases where signature verification failed (perhaps because the other party has just replaced their signing key) but you wish to proceed with calling find_verified_element() anyway.

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.

register_transform_method( $name, $uri )

Used internally to register methods for implementing transformation algorithms so that they can be looked by by URI. May be called by a subclass to add support for additional algorithms.

register_signature_methods( $name, $uri )

Used internally to register methods for implementing creation and verification of signatures using specific algorithms so that they can be looked by by URI. May be called by a subclass to add support for additional algorithms.

SUPPORTED SIGNATURE ALGORITHMS

rsa_sha1

rsa_sha256

SEE ALSO

See Authen::NZRealMe for documentation index.

LICENSE AND COPYRIGHT

Copyright (c) 2010-2022 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