NAME

XML::Sig - A toolkit to help sign and verify XML Digital Signatures.

DESCRIPTION

This perl module provides two primary capabilities: given an XML string, create and insert a digital signature, or if one is already present in the string verify it -- all in accordance with the W3C standard governing XML signatures.

ABOUT DIGITAL SIGNATURES

Just as one might want to send an email message that is cryptographically signed in order to give the recipient the means to independently verify who sent the email, one might also want to sign an XML document. This is especially true in the scenario where an XML document is received in an otherwise unauthenticated context, e.g. SAML.

However XML provides a challenge that email does not. In XML, two documents can be byte-wise inequivalent, and semanticaly equivalent at the same time. For example:

<?xml version="1.0"?>
<foo>
  <bar />
</foo>

And:

<?xml version="1.0"?>
<foo>
  <bar></bar>
</foo>

Each of these document express the same thing, or in other words they "mean" the same thing. However if you were to strictly sign the raw text of these documents, they would each produce different signatures.

XML Signatures on the other hand will produce the same signature for each of the documents above. Therefore an XML document can be written and rewritten by different parties and still be able to have someone at the end of the line verify a signature the document may contain.

There is a specially subscribed methodology for how this process should be executed and involves transforming the XML into its canonical form so a signature can be reliably inserted or extracted for verification. This module implements that process.

EXAMPLE SIGNATURE

Below is a sample XML signature to give you some sense of what they look like. First let's look at the original XML document, prior to being signed:

<?xml version="1.0"?>
<foo ID="abc">
  <bar>123</bar>
</foo>

Now, let's insert a signature:

<?xml version="1.0"?>
<foo ID="abc">
  <bar>123</bar>
  <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
    <SignedInfo xmlns="http://www.w3.org/2000/09/xmldsig#" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">
      <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments" />
      <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
      <Reference URI="#abc">
        <Transforms>
          <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
        </Transforms>
        <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
        <DigestValue>9kpmrvv3peVJpNSTRycrV+jeHVY=</DigestValue>
      </Reference>
    </SignedInfo>
    <SignatureValue>
      HXUBnMgPJf//j4ihaWnaylNwAR5AzDFY83HljFIlLmTqX1w1C72ZTuRObvYve8TNEbVsQlTQkj4R
      hiY0pgIMQUb75GLYFtc+f0YmBZf5rCWY3NWzo432D3ogAvpEzYXEQPmicWe2QozQhybaz9/wrYki
      XiXY+57fqCkf7aT8Bb6G+fn7Aj8gnZFLkmKxwCdyGsIZOIZdQ8MWpeQrifxBR0d8W1Zm6ix21WNv
      ONt575h7VxLKw8BDhNPS0p8CS3hOnSk29stpiDMCHFPxAwrbKVL1kGDLaLZn1q8nNRmH8oFxG15l
      UmS3JXDZAss8gZhU7g9T4XllCqjrAvzPLOFdeQ==
    </SignatureValue>
    <KeyInfo>
      <KeyValue>
        <RSAKeyValue>
          <Modulus>
            1b+m37u3Xyawh2ArV8txLei251p03CXbkVuWaJu9C8eHy1pu87bcthi+T5WdlCPKD7KGtkKn9vq
            i4BJBZcG/Y10e8KWVlXDLg9gibN5hb0Agae3i1cCJTqqnQ0Ka8w1XABtbxTimS1B0aO1zYW6d+U
            Yl0xIeAOPsGMfWeu1NgLChZQton1/NrJsKwzMaQy1VI8m4gUleit9Z8mbz9bNMshdgYEZ9oC4bH
            n/SnA4FvQl1fjWyTpzL/aWF/bEzS6Qd8IBk7yhcWRJAGdXTWtwiX4mXb4h/2sdrSNvyOsd/shCf
            OSMsf0TX+OdlbH079AsxOwoUjlzjuKdCiFPdU6yAJw==
          </Modulus>
          <Exponent>Iw==</Exponent>
        </RSAKeyValue>
      </KeyValue>
    </KeyInfo>
  </Signature>
</foo>

PREREQUISITES

Digest::SHA1

XML::XPath

MIME::Base64

Crypt::OpenSSL::X509

Crypt::OpenSSL::RSA

USAGE

SUPPORTED ALGORITHMS & TRANSFORMS

This module supports the following signature methods:

DSA

RSA

RSA encoded as x509

EXC-X14N#

EXC-X14#WithComments

Enveloped Signature

METHODS

sign($xml)

When given a string of XML, it will return the same string with a signature generated from the key provided when the XML::Sig object was initialized.

This method presumes that there is one and only one element in your XML document with an ID (case sensitive) attribute. This is the element that will be the basis for the signature. It will also correspond to the URI attribute in the Reference element that will be contained by the signature. If no ID attribute can be found on an element, the signature will not be created.

verify($xml)

Returns true or false based upon whether the signature is valid or not.

When using XML::Sig exclusively to verify a signature, no key needs to be specified during initialization given that the public key should be transmitted with the signature.

OPTIONS

Each of the following options are also accessors on the main File::Download object.

key

The path to a file containing the contents of a private key. This option is used only when generating signatures.

canonicalizer

The XML canonicalization library to use. Options currently are:

XML::CanonicalizerXML (default)

XML::Canonicalizer

x509

Takes a true (1) or false (0) value and indicates how you want the signature to be encoded. When true, an X509 certificate will be encoded in the signature. Otherwise the native encoding format for RSA and DSA will be used.

EXAMPLE

Fetch the newest and greatest perl version:

my $xml = '<foo ID="abc">123</foo>';
my $signer = XML::Sig->new({
  canonicalizer => 'XML-CanonizeXML',
  key => 'path/to/private.key',
});
my $signed = $signer->sign($xml);
print "Signed XML: $signed\n";
$signer->verify($signed) 
  or die "Signature Invalid.";
print "Signature valid.\n";

SEE ALSO

http://www.w3.org/TR/xmldsig-core/

AUTHORS and CREDITS

Author: Byrne Reese <byrne@majordojo.com>

Thanks to Manni Heumann who wrote Google::SAML::Response from which this module borrows heavily in order to create digital signatures.

cpanm XML::Sig

perl -MCPAN -e shell
install XML::Sig