<?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_assertion: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) {
			SAML2_Utils::addString($root, SAML2_Const::NS_SAML, 'saml:Issuer', $this->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);
		case 'ArtifactResponse':
			return new SAML2_ArtifactResponse($xml);
		case 'ArtifactResolve':
			return new SAML2_ArtifactResolve($xml);
		default:
			throw new Exception('Unknown SAML message: ' . var_export($xml->localName, TRUE));
		}

	}

}

?>