What do I need to know about XML Signatures to get SAML working?

Question

At work we have a web app that we'll need to interface with another company's web app using Single Sign On validated by SAML. Our web apps are written in PHP, and it's obviously irrelevant what language choice the other company is using. Nonetheless, I've needed to write a simple API that this other company can send SOAP requests to with SAML requests, and generate back a SAML response. I've been writing it from scratch for three reasons: 1) there don't really seem to be many options for SAML interactions written in PHP even if I wanted one, 2) it limits the overhead that would be involved with adding another third-party component, and 3) creating things from scratch usually leaves me with a significantly better understanding and makes me much more capable to adapt the thing in the future if needed.

Anyways, I'm fairly new to SAML, SOAP, and XML standards in general, so I've kind of been teaching myself as I go. I've got the API pretty much complete for our purposes, with the one exception that the other company has specified that our response will be required to be digitally signed with a certificate (and the request we receive will similarly be digitally signed). So I've been trying to figure out how to process/generate the XML signatures, but honestly it's all a bit confusing as W3C specs aren't exactly light reading.

Section 5.4.8 of the Assertions and Protocol for the OASIS Security Markup Language (SAML) V1.1 document (the document I've been going off, as the other company said they'll be using v1.1) includes an example of a signed response containing a signed assertion, which I'm going to include here to reference:

<Response IssueInstant="2003-04-17T00:46:02Z" MajorVersion="1" MinorVersion="1"
 Recipient="www.opensaml.org" ResponseID="_c7055387-af61-4fce-8b98-e2927324b306"
 xmlns="urn:oasis:names:tc:SAML:1.0:protocol"
 xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
  <ds:SignedInfo>
   <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
   <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
   <ds:Reference URI="#_c7055387-af61-4fce-8b98-e2927324b306">
    <ds:Transforms>
     <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
     <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
      <InclusiveNamespaces PrefixList="#default saml samlp ds xsd xsi"
       xmlns="http://www.w3.org/2001/10/xml-exc-c14n#"/>
     </ds:Transform>
    </ds:Transforms>
    <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
    <ds:DigestValue>TCDVSuG6grhyHbzhQFWFzGrxIPE=</ds:DigestValue>
   </ds:Reference>
  </ds:SignedInfo>
  <ds:SignatureValue>x/GyPbzmFEe85pGD3c1aXG4Vspb9V9jGCjwcRCKrtwPS6vdVNCcY5rHaFPYWkf+5EIYcPzx+pX1h43SmwviCqXRjRtMANWbHLhWAptaK1ywS7gFgsD01qjyen3CP+m3Dw6vKhaq1ed10BYyrIzb4KkHO4ahNyBVXbJwqv5pUaE4=</ds:SignatureValue>
  <ds:KeyInfo>
   <ds:X509Data>
    <ds:X509Certificate>MIICyjCCAjOgAwIBAgICAnUwDQYJKoZIhvcNAQEEBQAwgakxCzAJBgNVBAYTA1VT ... 8I3bsbmRAUg4UP9hH6ABVq4KQKMknxu1xQxLhpR1y1GPdiowMNTrEG8cCx3w/w==</ds:X509Certificate>
   </ds:X509Data>
  </ds:KeyInfo>
 </ds:Signature>
 <Status><StatusCode Value="samlp:Success"/></Status>
 <Assertion AssertionID="_a75adf55-01d7-40cc-929f-dbd8372ebdfc"
  IssueInstant="2003-04-17T00:46:02Z" Issuer="www.opensaml.org"
  MajorVersion="1" MinorVersion="1" xmlns="urn:oasis:names:tc:SAML:1.0:assertion"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Conditions NotBefore="2003-04-17T00:46:02Z" NotOnOrAfter="2003-04-17T00:51:02Z">
   <AudienceRestrictionCondition>
    <Audience>http://www.opensaml.org</Audience>
   </AudienceRestrictionCondition>
  </Conditions>
  <AuthenticationStatement AuthenticationInstant="2003-04-17T00:46:00Z"
   AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password">
   <Subject>
    <NameIdentifier Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">[email protected]</NameIdentifier>
    <SubjectConfirmation>
     <ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:bearer</ConfirmationMethod>
    </SubjectConfirmation>
   </Subject>
   <SubjectLocality IPAddress="127.0.0.1"/>
  </AuthenticationStatement>
  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
   <ds:SignedInfo>
    <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
    <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
    <ds:Reference URI="#_a75adf55-01d7-40cc-929f-dbd8372ebdfc">
     <ds:Transforms>
      <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
      <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
       <InclusiveNamespaces PrefixList="#default saml samlp ds xsd xsi"
        xmlns="http://www.w3.org/2001/10/xml-exc-c14n#"/>
      </ds:Transform>
     </ds:Transforms>
     <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
     <ds:DigestValue>Kclet6XcaOgOWXM4gty6/UNdviI=</ds:DigestValue>
    </ds:Reference>
   </ds:SignedInfo>
   <ds:SignatureValue>hq4zk+ZknjggCQgZm7ea8fI79gJEsRy3E8LHDpYXWQIgZpkJN9CMLG8ENR4Nrw+n7iyzixBvKXX8P53BTCT4VghPBWhFTSt9tHWu/AtJfOTh6qaAsNdeCyG86jmtp3TDMWuL/cBUj2OtBZOQMFn7jQ9YB7k1Iz3RqVL+wNmeWI4=</ds:SignatureValue>
   <ds:KeyInfo>
    <ds:X509Data>
     <ds:X509Certificate>MIICyjCCAjOgAwIBAgICAnUwDQYJKoZIhvcNAQEEBQAwgakxCzAJBgNVBAYTA1VT ... 8I3bsbmRAUg4UP9hH6ABVq4KQKMknxu1xQxLhpR1y1GPdiowMNTrEG8cCx3w/w==</ds:X509Certificate>
    </ds:X509Data>
   </ds:KeyInfo>
  </ds:Signature>
 </Assertion>
</Response>

So how do I generate something like this? And if I receive something like this, how do I validate it? Also, can anyone offer just a basic conceptual overview of what the <ds:Signature> tags are here? It seems there are two <ds:Signature> tags, one in the main <Response> and one in the <Assertion>, each containing their own <ds:DigestValue>, <ds:SignatureValue>, and <ds:X509Certificate> (and each distinct). How are these generated? Any light you can shed on this will be much appreciated. Tutorials or code examples would be even more appreciated! But at this point, if you can just get me on the right track, that's all I'm really asking for. Right now it all still seems like a big black box to me.

By the way, if this helps, it says elsewhere in the SAML 1.1 spec that SAML implementations should use the "Exclusive Canonicalization" method only (Excl-C14N) and should use the "enveloped transform" only. I'm still not completely sure what that means.

Answer 1

Processing XML signatures is not really too difficult, if you are very familiar with XML, but there are a lot of details that have to be absolutely right or things don't work, so I probably wouldn't try writing my own implementation in this situation (I did implement it partially once, but that was for a different and special purpose, and anyway it wasn't a complete implementation).

Anyway, I don't know much about SAML, but I do know about XML and XML Signatures, so maybe I can get you some of the way by trying to answer your questions.

A Signature element refers to a specific piece of an XML document that has been digitally signed, in its SignedInfo child element. The Reference child element of that (I think there can be many Reference elements that get concatenated when forming the bytes to be signed but I don't remember for sure anymore) points to the content through the URI attribute. The Transform elements describe transformations performed on the referred-to content prior to hashing it; you will need to look at the specifications to figure out how the transformation algorithms are defined. The DigestMethod element gives the hash algorithm to apply to the bytes that are the result of these transformation algorithms (note that one of them is always canonicalization that converts XML into bytes), and the DigestValue gives the result of that digest algorithm.

The actual signature is in the SignatureValue element, and is produced by applying the CanonicalizationMethod element's canonicalization to produce the bytes and then signing these bytes with the SignatureMethod. The KeyInfo element tells you how to find the key to use.

Canonicalization, which appears a couple of times above, is simply a way to convert an XML document into bytes so that "equivalent" XML documents produce the same sequence of bytes. This is required in a digital signature because the algorithms work on bytes and XML can pass through a number of intermediaries that probably will disrupt the original bytes but will retain the equivalence. And different canonicalization methods are needed for different situations: if elements are extracted from documents and placed into others, you need exclusive canonicalization that strips away unneeded namespace definitions, but in other cases that might not work correctly, so you need inclusive canonicalization instead, which preserves all in-scope namespaces.

This is just the basics. There are a number of different options in how to produce an XML signature, and if you want to implement a working verifier, you need to consider all of them. Since you are new to XML in general, I'll just repeat my advice of using something that already exists. It's an interesting learning experience to implement a specification, but often it's a waste of time if implementations are already available.

There is the W3C's documentation about signatures.