<?php
/**
* Base class for all SAML 2 messages.
*
* Implements what is common between the samlp:RequestAbstractType and
* samlp:StatusResponseType element types.
*
* @package simpleSAMLphp
* @version $Id$
*/
abstract class SAML2_Message implements SAML2_SignedElement {
/**
* The name of the root element of the DOM tree for the message.
*
* Used when creating a DOM tree from the message.
*
* @var string
*/
private $tagName;
/**
* The identifier of this message.
*
* @var string
*/
private $id;
/**
* The issue timestamp of this message, as an UNIX timestamp.
*
* @var int
*/
private $issueInstant;
/**
* The destination URL of this message if it is known.
*
* @var string|NULL
*/
private $destination;
/**
* The entity id of the issuer of this message, or NULL if unknown.
*
* @var string|NULL
*/
private $issuer;
/**
* The RelayState associated with this message.
*
* @var string|NULL
*/
private $relayState;
/**
* The DOMDocument we are currently building.
*
* This variable is used while generating XML from this message. It holds the
* DOMDocument of the XML we are generating.
*
* @var DOMDocument
*/
protected $document;
/**
* The private key we should use to sign the message.
*
* The private key can be NULL, in which case the message is sent unsigned.
*
* @var XMLSecurityKey|NULL
*/
private $signatureKey;
/**
* List of certificates that should be included in the message.
*
* @var array
*/
private $certificates;
/**
* Available methods for validating this message.
*
* @var array
*/
private $validators;
/**
* Initialize a message.
*
* This constructor takes an optional parameter with a DOMElement. If this
* parameter is given, the message will be initialized with data from that
* XML element.
*
* If no XML element is given, the message is initialized with suitable
* default values.
*
* @param string $tagName The tag name of the root element.
* @param DOMElement|NULL $xml The input message.
*/
protected function __construct($tagName, DOMElement $xml = NULL) {
assert('is_string($tagName)');
$this->tagName = $tagName;
$this->id = SimpleSAML_Utilities::generateID();
$this->issueInstant = time();
$this->certificates = array();
$this->validators = array();
if ($xml === NULL) {
return;
}
if (!$xml->hasAttribute('ID')) {
throw new Exception('Missing ID attribute on SAML message.');
}
$this->id = $xml->getAttribute('ID');
if ($xml->getAttribute('Version') !== '2.0') {
/* Currently a very strict check. */
throw new Exception('Unsupported version: ' . $xml->getAttribute('Version'));
}
$this->issueInstant = SimpleSAML_Utilities::parseSAML2Time($xml->getAttribute('IssueInstant'));
if ($xml->hasAttribute('Destination')) {
$this->destination = $xml->getAttribute('Destination');
}
$issuer = SAML2_Utils::xpQuery($xml, './saml:Issuer');
if (!empty($issuer)) {
$this->issuer = trim($issuer[0]->textContent);
}
/* Validate the signature element of the message. */
try {
$sig = SAML2_Utils::validateElement($xml);
if ($sig !== FALSE) {
$this->certificates = $sig['Certificates'];
$this->validators[] = array(
'Function' => array('SAML2_Utils', 'validateSignature'),
'Data' => $sig,
);
}
} catch (Exception $e) {
/* Ignore signature validation errors. */
}
}
/**
* Add a method for validating this message.
*
* This function is used by the HTTP-Redirect binding, to make it possible to
* check the signature against the one included in the query string.
*
* @param callback $function The function which should be called.
* @param mixed $data The data that should be included as the first parameter to the function.
*/
public function addValidator($function, $data) {
assert('is_callable($function)');
$this->validators[] = array(
'Function' => $function,
'Data' => $data,
);
}
/**
* Validate this message against a public key.
*
* TRUE is returned on success, FALSE is returned if we don't have any
* signature we can validate. An exception is thrown if the signature
* validation fails.
*
* @param XMLSecurityKey $key The key we should check against.
* @return boolean TRUE on success, FALSE when we don't have a signature.
*/
public function validate(XMLSecurityKey $key) {
if (count($this->validators) === 0) {
return FALSE;
}
$exceptions = array();
foreach ($this->validators as $validator) {
$function = $validator['Function'];
$data = $validator['Data'];
try {
call_user_func($function, $data, $key);
/* We were able to validate the message with this validator. */
return TRUE;
} catch (Exception $e) {
$exceptions[] = $e;
}
}
/* No validators were able to validate the message. */
throw $exceptions[0];
}
/**
* Retrieve the identifier of this message.
*
* @return string The identifier of this message.
*/
public function getId() {
return $this->id;
}
/**
* Set the identifier of this message.
*
* @param string $id The new identifier of this message.
*/
public function setId($id) {
assert('is_string($id)');
$this->id = $id;
}
/**
* Retrieve the issue timestamp of this message.
*
* @return int The issue timestamp of this message, as an UNIX timestamp.
*/
public function getIssueInstant() {
return $this->issueInstant;
}
/**
* Set the issue timestamp of this message.
*
* @param int $issueInstant The new issue timestamp of this message, as an UNIX timestamp.
*/
public function setIssueInstant($issueInstant) {
assert('is_int($issueInstant)');
$this->issueInstant = $issueInstant;
}
/**
* Retrieve the destination of this message.
*
* @return string|NULL The destination of this message, or NULL if no destination is given.
*/
public function getDestination() {
return $this->destination;
}
/**
* Set the destination of this message.
*
* @param string|NULL $destination The new destination of this message.
*/
public function setDestination($destination) {
assert('is_string($destination) || is_null($destination)');
$this->destination = $destination;
}
/**
* Retrieve the issuer if this message.
*
* @return string|NULL The issuer of this message, or NULL if no issuer is given.
*/
public function getIssuer() {
return $this->issuer;
}
/**
* Set the issuer of this message.
*
* @param string|NULL $issuer The new issuer of this message.
*/
public function setIssuer($issuer) {
assert('is_string($issuer) || is_null($issuer)');
$this->issuer = $issuer;
}
/**
* Retrieve the RelayState associated with this message.
*
* @return string|NULL The RelayState, or NULL if no RelayState is given.
*/
public function getRelayState() {
return $this->relayState;
}
/**
* Set the RelayState associated with this message.
*
* @param string|NULL $relayState The new RelayState.
*/
public function setRelayState($relayState) {
assert('is_string($relayState) || is_null($relayState)');
$this->relayState = $relayState;
}
/**
* Convert this message to an unsigned XML document.
*
* This method does not sign the resulting XML document.
*
* @return DOMElement The root element of the DOM tree.
*/
public function toUnsignedXML() {
$this->document = new DOMDocument();
$root = $this->document->createElementNS(SAML2_Const::NS_SAMLP, 'samlp:' . $this->tagName);
$this->document->appendChild($root);
/* Ugly hack to add another namespace declaration to the root element. */
$root->setAttributeNS(SAML2_Const::NS_SAML, 'saml:tmp', 'tmp');
$root->removeAttributeNS(SAML2_Const::NS_SAML, 'tmp');
$root->setAttribute('ID', $this->id);
$root->setAttribute('Version', '2.0');
$root->setAttribute('IssueInstant', gmdate('Y-m-d\TH:i:s\Z', $this->issueInstant));
if ($this->destination !== NULL) {
$root->setAttribute('Destination', $this->destination);
}
if ($this->issuer !== NULL) {
$issuer = $this->document->createElementNS(SAML2_Const::NS_SAML, 'saml:Issuer');
$issuer->appendChild($this->document->createTextNode($this->issuer));
$root->appendChild($issuer);
}
return $root;
}
/**
* Convert this message to a signed XML document.
*
* This method sign the resulting XML document if the private key for
* the signature is set.
*
* @return DOMElement The root element of the DOM tree.
*/
public function toSignedXML() {
$root = $this->toUnsignedXML();
if ($this->signatureKey === NULL) {
/* We don't have a key to sign it with. */
return $root;
}
/* Find the position we should insert the signature node at. */
if ($this->issuer !== NULL) {
/*
* We have an issuer node. The signature node should come
* after the issuer node.
*/
$issuerNode = $root->firstChild;
$insertBefore = $issuerNode->nextSibling;
} else {
/* No issuer node - the signature element should be the first element. */
$insertBefore = $root->firstChild;
}
SAML2_Utils::insertSignature($this->signatureKey, $this->certificates, $root, $insertBefore);
return $root;
}
/**
* Retrieve the private key we should use to sign the message.
*
* @return XMLSecurityKey|NULL The key, or NULL if no key is specified.
*/
public function getSignatureKey() {
return $this->signatureKey;
}
/**
* Set the private key we should use to sign the message.
*
* If the key is NULL, the message will be sent unsigned.
*
* @param XMLSecurityKey|NULL $key
*/
public function setSignatureKey(XMLsecurityKey $signatureKey = NULL) {
$this->signatureKey = $signatureKey;
}
/**
* Set the certificates that should be included in the message.
*
* The certificates should be strings with the PEM encoded data.
*
* @param array $certificates An array of certificates.
*/
public function setCertificates(array $certificates) {
$this->certificates = $certificates;
}
/**
* Retrieve the certificates that are included in the message.
*
* @return array An array of certificates.
*/
public function getCertificates() {
return $this->certificates;
}
/**
* Convert an XML element into a message.
*
* @param DOMElement $xml The root XML element.
* @return SAML2_Message The message.
*/
public static function fromXML(DOMElement $xml) {
if ($xml->namespaceURI !== SAML2_Const::NS_SAMLP) {
throw new Exception('Unknown namespace of SAML message: ' . var_export($xml->namespaceURI, TRUE));
}
switch ($xml->localName) {
case 'AttributeQuery':
return new SAML2_AttributeQuery($xml);
case 'AuthnRequest':
return new SAML2_AuthnRequest($xml);
case 'LogoutResponse':
return new SAML2_LogoutResponse($xml);
case 'LogoutRequest':
return new SAML2_LogoutRequest($xml);
case 'Response':
return new SAML2_Response($xml);
default:
throw new Exception('Unknown SAML message: ' . var_export($xml->localName, TRUE));
}
}
}
?>