Pro PHP XML and Web Services phần 6 docx

Using the algorithm from the DigestMethod element, the canonical form of the data erates the digest.. Generating a SignatureSignature generation involves using the key, which in this cas

Element Node

An element node is processed through the creation of a start tag using the QName of the ment, the processing of any namespace and attributes nodes, and the processing of any childnodes and an end tag for the element I will not explain the semantics of this generationbecause the PHP extensions actually handle the actual generation of the serialized form

ele-■ Tip In canonical form, element nodes must always have a starting and ending tag Empty tags are notallowed You must write <element />as <element></element>

One point I would like to mention, though, concerns using empty namespace declarations.Within a document, you can use them to indicate that an element is not in any namespace Typi-cally, however, this is used only when within a default namespace and indicates that nodeswithin the current scope are not within a default namespace For example:

<! The following is invalid >

name-<element1 xmlns:a="http://www.example.com/a" xmlns:b="http://www.example.com/b">

<element2 xmlns:a="http://www.example.com/a" xmlns:b="http://www.example.com/Z">

<element3></element3>

</element2>

</element1>

The canonical form of this document looks like this:

<element1 xmlns:a="http://www.example.com/a" xmlns:b="http://www.example.com/b">

with prefix b on element2 was included because the namespaceURI for that prefix changed and

is no longer the same namespace

Attribute Node

The PHP extensions already handle the processing of attribute nodes when being

serial-ized The only possible issue may deal with the values of attributes The serialized value of

the node is modified by replacing the characters &, <, and " with their entity references and

the whitespace characters #x9 (tab), #xA (line feed), and #xD (carriage return) with their

character references Notice that the > character is not modified Basically, you will modify

the attribute values when serialized if using any special characters If this is the case, then

XSL may be helpful because you can use a template to match attributes, which in turn calls

a PHP function to process the attribute value and return a modified string For the sake of

this chapter and because of having to build all this manually, I will use simplified attribute

values that need no special handling

Text Node

Text nodes are processed by converting the characters &, <, and > to their entity references The

whitespace character #xD is also replaced by &#xD;

Processing Instruction Node

PI nodes will already have been taken care for you during serialization, unless the value is empty

They consist of the <? characters followed by the target, a space, the value, and the closing ?>

characters An empty value would not place a space after the target Do not confuse an empty

value with a value consisting of whitespaces Consider the following:

<?php?>

<?php?>

Each of these has no value, so no additional space was added

■ Caution PIs that have empty values will need to be handled like attributes when creating the canonicalform The suggested method is to use XSL to create the values properly This, of course, is needed only if thedocument can have PI nodes with empty values In all other cases, serialization using the PHP extensionswill work correctly

Comment Node

Comment nodes are a little special Canonical form can be generated without commentnodes If this is the case, comment nodes have no bearing during serialization In this case,you need to remove all comments in the document Again, you could do this using XSL orusing the DOM API This is an example of doing this with DOM in combination with XPath:

$xPath = new DOMXPath($dom);

$cnodes = $xPath->query('//comment()');

foreach ($cnodes AS $cnode) {

$cnode->parentNode->removeChild($cnode);

}

Introducing Exclusive XML Canonicalization

An issue faced earlier in the chapter when working with canonical XML dealt with extracting

a document subset and inserting it into a different context This caused many problemsbecause canonical XML includes the document subset’s ancestor namespace declarationsand attributes within the XML namespace For instance, a wrapper node encapsulates a sub-set and might be used for something like transport If you are familiar with SOAP, you knowthis would be equivalent to its envelope The following document is in canonical form:

<subdoc>

<element>content</element>

</subdoc>

The document subset is then encapsulated within an envelope:

<envelope xmlns="http://www.example.com" xml:lang="en">

<subdoc>

<element>content</element>

<subdoc>

</envelope>

When canonical XML is applied to the subset in this case, the serialized version is muchdifferent:

<subdoc xmlns="http://www.example.com" xml:lang="en">

<element>content</element>

</subdoc>

Dealing with something like digital signatures becomes a nightmare The original ment no longer has the same canonical form as the latter one even though it is the same

docu-document/subset Trying to extract the subset and place it within a different context, such

as within another document, becomes impossible This is why you might also hear canonical

XML referred to as inclusive canonical XML It includes the context of a subset’s ancestors.

To deal with this issue, exclusive XML canonicalization was devised It excludes, rather

than includes, the context of a subset’s ancestors This means namespace declarations and

attributes in the XML namespace from a subset’s ancestors are not part of the

canonicaliza-tion process when performing exclusive XML canonicalizacanonicaliza-tion Taking the enveloped subdoc

and using exclusive XML canonicalization, the results are probably more of what you had

The data model for exclusive XML canonicalization is the same as that for canonical XML with

a few exceptions These exceptions, as previously noted, fall into the area of namespace

decla-ration handling You have already seen that a search of ancestor nodes not within the node set

for namespace declarations and attributes from the XML namespace is not performed under

exclusive XML canonicalization Serialization of namespace declarations themselves also

dif-fers and depends upon a few factors

You can use an InclusiveNamespaces PrefixList parameter with exclusive XML calization It is a list containing prefixes and/or a token that indicates a default namespace

canoni-This parameter plays a role in how namespaced nodes are rendered in canonical form

■ Note For the sections dealing with prefixes not in the InclusiveNamespace PrefixList, assume the

list is NULL, meaning it does not contain any prefixes or tokens This will help you understand the process

Prefixed Namespace Nodes

Namespaced nodes with a prefix not in the InclusiveNamespaces PrefixList, if used, are

rendered if they meet the following criteria:

• The parent element is in the node set.

• The namespace is visibly utilized by the element, which includes its attributes

• The prefix has not already been rendered by an ancestor within the output, or theprefix has been rendered by an ancestor yet refers to a different namespace

The term visibly utilize means that either the element or one of its attributes uses the

prefix of the namespace within its qualified name The following document will be serializedusing exclusive XML canonicalization It is assumed that all nodes are within the node set

is added because it meets all the criteria Its parent element, n2:element2, is in the node set,

it is visibly utilized by the element (notice the n2 prefix for the element name), and the prefixhas not yet been rendered The n3 namespace was not rendered because it is not visibly uti-lized The n2:element2 element is not in the n3 namespace and does not contain any

attributes within the n3 namespace

Default Namespace Nodes

The rules for processing tokens that represent default namespace nodes not in the

InclusiveNamespaces PrefixList are different from those for canonical XML for emptynamespaces, xmlns="" The empty namespace is output only if the element visibly utilizesthe default namespace, the element does not define a default namespace that is in the nodeset, and the nearest ancestor that is output and that visibly utilizes the default namespacehas a default namespace in the node set This may sound a little confusing, so take a look atthe following document:

The InclusiveNamespaces PrefixList throws a little curve to the rules already defined for

han-dling namespace nodes A namespace node matching a prefix or token in the list is rendered

according to the rules of canonical XML rather than those of exclusive XML canonicalization

Namespace nodes in the node set that match a prefix or token in the list, unlike those not in

the list, do not need to have parent elements in the node set This can make your output look

a little strange because it can result in non-well-formed XML, which is perfectly acceptable

when generating a canonical form for a document subset For the sake of sanity (because this

leads to much greater complexity than you are already dealing with), the discussion of

name-space nodes without an element in the node set is out of the scope of this chapter Documents

and document subsets used within this chapter will conform to those described in the next

section

Constrained Implementation (Non-Normative)

Section 3.1 of the Exclusive XML Canonicalization specification deals with a non-normative

way to implement exclusive XML canonicalization It assumes that subsets are well-formed

and that when an element is in a node set, so is its namespace axis When an element is not

in a node set, neither is its namespace axis These are the types of documents and document

subsets that will be used within this chapter when working with the XML extensions in PHP

The following steps come directly from the specifications for section 3.1:

1. Recursively process the entire tree (from which the XPath node set was selected) indocument order starting with the root (The operation of copying ancestor xml:

namespace attributes into output apex element nodes is not done.)

2. If the node is not in the XPath subset, continue to process its children element nodesrecursively

3. If the element node is in the XPath subset, then output the node in accordance withcanonical XML except for namespace nodes, which are rendered as follows:

a. ns_rendered is a copy of a dictionary, off the top of the state stack, of prefixes andtheir values that have already been rendered by an output ancestor of the name-space node’s parent element

b. Render each namespace node if and only if it is visibly utilized by the immediateparent element or one of its attributes or if it is present in InclusiveNamespaces

PrefixList and if its prefix and value do not appear in ns_rendered.

c. Render xmlns="" if and only if the default namespace is visibly utilized by theimmediate parent element node or the default prefix token is present in

InclusiveNamespaces PrefixList and the element does not have a namespace node in the node set declaring a value for the default namespace and the default

namespace prefix is present in the dictionary ns_rendered

4. Insert all the rendered namespace nodes (including xmlns="") into the ns_rendereddictionary, replacing any existing entries Push ns_rendered onto the state stack, andrecurse

5. After the recursion returns, pop the state stack

This list contains generalized instructions on how exclusive XML canonicalization could

be implemented As you get into the “Introducing XML Signatures” and “Introducing XMLEncryption” sections, you will see examples using PHP that demonstrate this generalization

■ Note The canonical forms used with digital signatures and encryption are generated using exclusiveXML canonicalization

Introducing XML Signatures

XML signatures can verify the integrity and source of data and that the data has not beenaltered from its original state It does this by using keys One of the most commonly usedmethods involves public and private keys An author of a document would use a private key

to sign the data This would create a digital signature, which is then added to an XML ment The receiver, who must have a copy of the author’s public key, would then use that key

docu-to verify the signed data Upon a successful verification, the receiver knows three things:

• The author is the genuine originator of the document, which is known as signer

authentication.

• The data has not been altered from its original form, which is called integrity.

• Neither the data nor the checksum has been tampered with, which may occur ifsomeone is trying to alter data while keeping the integrity of the data in order to

deceive the receiver of the data This is commonly known as message authentication.

The XML-Signature Syntax and Processing specification (http://www.w3.org/TR/

xmldsig-core/) specifies the syntax and processing rules for creating and representing digital

signatures It is named such because it uses XML syntax for the signature You can apply XML

signatures to virtually any type of digital data including data within an XML document as well

as remote resources accessible from a URI

Understanding the Types of Signatures

Three types of XML signatures exist: enveloped signatures, enveloping signatures, and

detached signatures

Enveloped Signatures

Enveloped signatures are signatures that are contained within the XML content that is being

signed In simple terms, an enveloped signature is an XML signature structure that is a child

of a signed document For example:

element and all of its content but exclude the actual XML signature structure, which begins

with the Signature element

been introduced to the structure and because it illustrates how an enveloping signature can

be encapsulated within another document, for which the encapsulating document has no

bearing on the signature In this case, the signature would include a reference to the Object

element The data within the Object element is the data being signed I will explain how toreference data later in the “Introducing the XML Signature Structure” section.

Detached Signatures

Enveloped signatures means the signature is encapsulated within a document being signed

It is not necessary that the entire document be signed, and it is quite possible you have only

a single element in the document that is signed In fact, it is also quite possible that the databeing signed does not even live within the document and resides remotely and is accessible

through a URI Detached signatures are used just for these purposes:

Introducing the XML Signature Structure

The structure of XML signatures can get quite complex An entire book could be written onthis subject alone For this reason, I will keep things simple and cover only the core syntax.This chapter will introduce how to create and verify basic XML signatures using PHP Afteryou understand this, you should be able to implement more advanced signatures based onthe specifications

The document in Listing 12-2 illustrates a valid enveloping signature

■ Note The XML signature in Listing 12-2, as well as all other examples in this chapter, uses the string

"secret"for the HMAC key Attributes named Idare ID attributes No DTDs are being used in this section,

although you could use a DTD to automatically define these as IDs within the document Refer to the

speci-fications for the schemas for each element and attribute list

Listing 12-2.Example of Enveloping Signature

<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">

<SignedInfo>

<CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />

The Signature element is the root of an XML signature and is bound to the http://www.w3.org/

2000/09/xmldsig# namespace This element contains all the information needed to verify an

XML signature

SignatureValue Element

The SignatureValue element contains the Base64-encoded value of the actual digital signature,

which in Listing 12-2 is the value OUubDO2l6XUIODuLSjKAtjYlaTk= I’ll explain how to compute

this value later in the “Generating a Signature” section as well as when you get into actually

generating an XML signature

SignedInfo Element

The SignedInfo element is a container element that provides information regarding how

a signature is processed, the location of the data that is signed, and the value for data integrity

This element also accepts an optional Id attribute Using this attribute allows the element to

be referenced by other signatures or objects

CanonicalizationMethod Element

The CanonicalizationMethod element defines the type of canonicalization that must be applied

to the SignedInfo element when processing a digital signature Implementations must at leastsupport canonical XML without comments, as noted by the value http://www.w3.org/TR/2001/REC-xml-c14n-20010315 Other possible values include, but are not limited to, http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments, which is canonical XML with comments, andhttp://www.w3.org/TR/xml-exc-c14n/, which is exclusive canonical XML As shown in Listing 12-2,the value for this element is http://www.w3.org/TR/2001/REC-xml-c14n-20010315, so canonicalXML will process the SignedInfo element

SignatureMethod Element

The SignatureMethod element specified the algorithm used to create and verify the digital nature Depending upon the algorithm used, this element can have child elements, such asHMACOutputLength, to provide additional information for the algorithm You specify the actualalgorithm to be used in the Algorithm attribute The algorithms are specified by URI and definethe role You can find a few of the possible values at http://www.w3.org/TR/xmldsig-core/

sig-#sec-AlgID within the specification The value used in Listing 12-2 is http://www.w3.org/2000/09/xmldsig#hmac-sha1, which corresponds to HMAC-SHA1 So, it is now safe to assume thatHMAC-SHA1 is the algorithm used in this chapter for digital signatures

Reference Element

Reference elements specify what data is signed You can use more than one Reference element.For the sake of this chapter, however, the digital signatures used here will contain only a singleReference element This element can take any of three optional attributes You can use an Idattribute so that the element can be easily referenced from other places The Type attribute is

a URI that specifies the type of data For instance, the attribute can be Type="http://www.w3.org/2000/09/xmldsig#Object" or Type="http://www.w3.org/2000/09/xmldsig#Manifest" The valuehas no bearing on how the signature is generated It can, however, be used by an application forits own purpose The last optional attribute is URI This has much more bearing on data thanthe other attributes

The URI attribute identifies the location of the data object, using a URI as its value Theattribute is considered optional, because it is possible that an application already knows wherethe data resides For instance, if the same XML structure is always used, it may be agreed upon

by both the author and the receiver of the document that a certain element within the ment will always be signed Typically, though, it is safest to always include a URI The example inListing 12-2 is using data that is located within the document The URI attribute has the value

docu-#object This identifies the node set containing the element with an ID, defined by the Id ute, of object

attrib-■ Note The Transformselement, which is an optional child of a Referenceelement, will be omitted fromthis chapter Its use is out of scope because it is a bit advanced at this point to attempt to use the currentXML functionality in PHP

DigestMethod Element

The DigestMethod element defines the algorithm that is applied to the data being signed You

specify the actual algorithm using a URI for the value of the Algorithm attribute This attribute

works in the same manner as the one located on the SignatureMethod element The example

in Listing 12-2 used the value http://www.w3.org/2000/09/xmldsig#sha1 The digest will be

computed using an SHA1 hash

DigestValue Element

The DigestValue element contains the Base64-encoded value of the digest Using the

signa-ture from Listing 12-2, the digest is simply the SHA1 hash of the canonical form of the data

being signed Do not worry if you do not fully understand this at this point This will be made

extremely clear when I cover how to create and verify the signatures in the “Creating a

Signa-ture” and “Verifying a SignaSigna-ture” sections

KeyInfo Element

The KeyInfo element is an optional element that can allow the recipients to obtain the needed

keys, certificates, or public key management information The XML signature in this chapter

uses the string "secret", which is private and known only to the author and recipient because

of the algorithm specified in the SignatureMethod element Other algorithms use public/private

key pairs, making it perfectly viable to include public keys, certificates, or information about

accessing a public key within the XML signature

This element serves as a container to provide the needed information, which may be tained in any number of possible child elements The content of a KeyName element is a string

con-containing a key identifier for the recipient It indicates to the recipient information what key

to use for the document A KeyValue element defines a single public key, such as DSA or RSA

public keys, which can verify and validate the signature You can use a Retrieval element to

reference KeyInfo information stored in another location It has a URI and Type attribute and

works in the same manner as a Reference element The remaining possible elements, X509Data,

PGPData, SPKIData, and MgmtData, are used depending upon the type of algorithm being used

For example, you can use X509 certificates, and an X509Data element could contain certificate

chains, revocation lists, or a SubjectKeyIdentifier Again, these elements are out of the scope

of this chapter but are covered in more detail within the specification at http://www.w3.org/

TR/xmldsig-core/#sec-KeyInfo

Object Element

An Object element is a container to hold any type of data It has three optional attributes

TheId attribute is an ID used to reference the element The XML signature in Listing 12-2

uses the name object for the Id attribute, which is then referenced by the Reference element

through its URI attribute A MimeType attribute specifies the MIME type of the data The value

must be a valid MIME type as defined in RFC 2045 (http://www.ietf.org/rfc/rfc2045.txt)

The last attribute is Encoding The value defines the encoding used within the object The

MimeType and Encoding attributes are purely informational It is completely up to the

appli-cation whether they need to be used

Creating a Signature

Creating a signature involves generating the Reference and SignatureValue elements The rest

of the information within a Signature element defines how the values are generated or, whenusing an enveloping signature, could be data that is being signed The first steps are determin-ing the type of encryption algorithm that will be used and are determining what rules are to beused when the signature is created; they also determine the rules an application must follow

to verify the signature

In this case, the XML signature being created is the one in Listing 12-2 The following is

a list of rules that will be used to create the signature:

• The signature will be enveloping The Reference element will refer to an Object elementwith the Id object within the document Specifically, the Object element will be a child

of the Signature element

• XML canonicalization will be used This determines the value for the Algorithm ute on the CanonicalizationMethod element

attrib-• HMAC SHA1, using the string "secret" for the key, will be used for the signature Thisdetermines the value of the Algorithm attribute on the SignatureMethod element

• SHA1 will be used for message integrity This determines the value of the Algorithmattribute on the DigestMethod element

Based on this list, you can create a skeleton Signature, as shown in Listing 12-3

Listing 12-3.Skeleton Enveloping Signature Document

<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">

<SignedInfo>

<CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />

The only piece of information within the skeleton not mentioned in the list is the textHello World!; that text, as well as the encompassing Object element, is the message to besigned The last steps here are to generate the DigestValue and generate the actual signature

Generating the Reference

According to the specification, DigestValues are created while Reference elements are created

The reason for this is that multiple objects can be used within a single XML signature In this case,

the data is simple, and the Reference element pointing to the data has already been created

No transforms are being used, so you can move directly to the DigestValue calculation

This is calculated by performing the following steps:

1. Obtain the raw data specified by the Reference element In this case, it is the Objectelement

2. Apply any Transforms This example does not use any

3. If the transforms (or the raw data in the event there are no Transforms defined) result in anode set, then use canonical XML to serialize the node set In this example, there are notransforms, and the raw data is the Object element Canonicalization performed in thisstep is true canonical XML, meaning inclusive The value from the CanonicalizationMethodelement has no bearing on this step because that element pertains to Signature gener-ation and not Reference generation

4. Using the algorithm specified by the DigestMethod element, calculate the DigestValueusing the resulting data from step 3

5. Add the DigestValue to the tree Again, the specifications build the Reference elementduring these steps, so if you decide to follow that method or have a complex signaturerequiring the steps to be performed in that manner, then create the Reference elementand its children at this point and append it as a child to the SignedInfo element

From step 1, the raw data is the Object element For this example, I will use the variable

$doc, which represents the skeleton signature from Listing 12-3 This can either be loaded

from a file or be built manually using the DOM methods from Chapter 6

■ Caution When creating the signature document manually using the DOM API, the Signatureelement

defines the default namespace http://www.w3.org/2000/09/xmldsig# Elements within its scope must

be created using namespace-aware methods, such as createElementNS, in order for this to work properly

For example:

$xPath = new DOMXpath($doc);

/* Following line split into two lines because of length */

$query = '//*[local-name()="Reference" and '

manually You can use the following code to perform this operation Note that it assumes theURI value contains an ID and not a URL to external data:

$ID = substr ($dataURI, 1);

<Object Id="object">Hello World!</Object>

There are no Transforms, and the result of the first step is a node set containing the Objectelement This node set (read: element) must be serialized in canonical form:

<Object xmlns="http://www.w3.org/2000/09/xmldsig#" Id="object">some text</Object>Canonical XML is used here, which is inclusive This means the default namespacedefined by the Signature element, which is an ancestor of the Object element, is serializedwith the Object node A quick and simple way to canonicalize this element is copying it toanother document and serializing the new document The copy must be a deep copy so thatall attributes and children are copied During the copy, because this node becomes the top-level node, the inherited default namespace is re-created on the copy Because of the structure

of the XML signature and data you are working with, this is the only thing you need to do prior

to serialization to result in the correct canonical form For more complex structures, youwould need to use the techniques described in the “Introducing Canonical XML” section:

$dom = new DOMDocument();

$copyObject = $dom->importNode($Object, TRUE);

$dom->appendChild($copyObject);

■ Caution This works only because the content of the Objectelement is simple text and not an XMLsubtree If the contents were a subtree, you would need to apply the rules and techniques described in the

“Introducing Canonical XML” section so that namespaces and attributes in particular are generated correctly

Using the algorithm from the DigestMethod element, the canonical form of the data erates the digest This value is then encoded using Base64 encoding and set as the content ofthe DigestValue element:

gen-$query = '//*[local-name()="DigestMethod" and '

/* Create SHA1 hash of the canonical form of the Object element */

/* Create DigestValue element, and append to parent of DigestMethod */

contin-previously obtained is converted to binary form The sha1() function is being used, because it is

available by default in PHP To avoid having to convert the value into binary form, you can use

mhash , $bhash = mhash(MHASH_SHA1, $canonical);, because it returns the hash as a binary rather

than as a hexadecimal In any event, the binary value is then Base64 encoded A DigestValue

ele-ment is then created using the createEleele-mentNS method and passing in the encoded value

The additional code for handling whitespace is not needed when generating a signature.

The reason it has been added in this example is because whitespace is significant in canonical

form To present a document in an easily presentable form, such as the one shown in Listing 12-2,

I added whitespaces These whitespaces are included within a signature in order to present

you with a readable form as well as correct values for the DigestValue and SignatureValue

elements

Generating a Signature

Signature generation involves using the key, which in this case is the string "secret", to applythe algorithm specified by the Algorithm on the SignatureMethod element to the SignedInfoelement in canonical form This time the canonical form is generated using the method spe-cified by the CanonicalizationMethod element Rather than explain every single step in theprocess, because you should be experienced enough at this point to find nodes and values,

I will demonstrate only the steps specific to generating the signature This being said, thefollowing variables and values will be assumed:

• $canonMethod: "http://www.w3.org/TR/2001/REC-xml-c14n-20010315";

• $signedInfo: DOMElement for SignedInfo element

• $Object: DOMElement for Object element

• $key: "secret";

Listing 12-4 defines a generic HMAC function To use the sha1() function without tional dependencies, I will use the function in Listing 12-4 within the example

addi-Listing 12-4.Generic HMAC Function

function hmac ($key, $data)

$k_ipad = $key ^ $ipad ;

$k_opad = $key ^ $opad;

return sha1($k_opad pack("H*",sha1($k_ipad $data)));

}

The process for generating the signature is similar to generating the digest A differentnode set is used, and HMAC SHA1 is being performed; however, in this example, the elementSignedInfo is being converted into its canonical form, and the signing algorithm is applied.The resulting value is then set as the content for the SignatureValue element and appended

as a child to the Signature element For example:

$dom = new DOMDocument();

$copyInfo = $dom->importNode($signedInfo, TRUE);

$canonical = $dom->saveXML($copyInfo, LIBXML_NOEMPTYTAG);

/* Calculate HMAC SHA1 */

$hmac = hmac($key,$canonical);

print $hmac."\n";

$bhmac = base64_encode(pack("H*", $hmac));

/* Handle whitespaces for presentation layout */

Verifying a signature is similar to creating a signature but is a bit simpler A tree is not being

created, so you do not need to deal with insert nodes or add any whitespace to make it look

nice Verification requires validating the reference to ensure the integrity of the message and

validating the signature to ensure the message and signer authenticity The XML signature in

Listing 12-2 should be the same as the signature you just saw created You can use either in thefollowing sections because it will be used as the XML signature being verified.

Validating the Reference

The steps for validating the reference are almost identical to creating the value for the

DigestValue content when creating a signature The only difference is that the elements andcontent already exists, so no modifications to the document are made Normally, the followingsteps would be performed for each Reference element in the XML signature, but in this case,there is only a single Reference element

Steps 1 to 4 of generating a reference from the “Creating a Signature” section are formed on the XML signature The resulting digest value is then compared to the value withinthe DigestValue element in the XML signature Remember that the value within the signature

per-is Base64 encoded Although in many cases a Base64-to-Base64 comparper-ison should work, thespecification recommends a binary-to-binary comparison in the event that additional white-spaces ended up in the document This is a simple comparison because the content of theDigestValue is just the Base64-encoded binary value A simple call to base64_decode() willconvert the value to binary form The following code uses the resulting XML signature, refer-enced by the $doc variable, as the document being verified:

/* Retrieve Reference node and location of data */

$xPath = new DOMXpath($doc);

$query = '//*[local-name()="Reference" and

$signedDigest = $xPath->evaluate($query, $refElement);

$ID = substr ($dataURI, 1);

$query = '//*[@Id="'.$ID.'"]';

$Object = $xPath->query($query)->item(0);

/* Create canonical form for Object element */

$dom = new DOMDocument();

$copyObject = $dom->importNode($Object, TRUE);

$dom->appendChild($copyObject);

$canonical = $dom->saveXML($copyObject);

/* Assume digest algorithm retrieved and SHA1 was found */

/* Create SHA1 hash of the canonical form of the Object element */

$hash = sha1($canonical);

$bhash = pack("H*", $hash);

$digValue = base64_encode($bhash);

The steps for validating the signature are also similar to creating the signature, though the tree

is not modified Again, the algorithm specified by the SignatureMethod element is applied to the

canonical form of the SignedInfo element The canonical form is generated using the method

specified by the CanonicalizationMethod element The same rules apply for verifying the value

as those from verifying a reference In the following example, the binary values, rather than the

Base64-encoded values, are compared to determine the authenticity of the message and signer:

/* Retrieve Value for SignatureValue element */

$query = 'string(//*[local-name()="SignatureValue" '

'and namespace-uri()="http://www.w3.org/2000/09/xmldsig#"])';

$signature = base64_decode($xPath->evaluate($query));

/* Generate canonical form of SignedInfo element*/

$signedInfo = $xPath->query("//*[local-name() = 'SignedInfo']")->item(0);

$dom = new DOMDocument();

$copyInfo = $dom->importNode($signedInfo, TRUE);

$dom->appendChild($copyInfo);

/*

Following works only with PHP 5.1 and aboveLIBXML_NOEMPTYTAG used to create start and end tags for empty elementsdocument element $copyInfo passed dump the node which does not generate

■ Caution The steps to generate and verify signatures as well as the type of signatures used in thischapter are only a small subset of what can be performed using XML signatures The steps are meant as

an introduction to get you started using digital signatures Signatures can become quite complex workingwith multiple sets of data, data residing in different locations, different types of data, and different algo-rithms The material presented here is intended only as a starting point, and you should refer to the

specifications to work with more advanced and complex XML signatures

Introducing XML Encryption

In many instances, an XML document can contain sensitive data For example, an e-commercesystem can collect customer and payment information and send that to a secure server for pro-cessing rather than storing the information on a public server This type of scenario pertainsmore toward smaller businesses because they typically lack the resources to implement a large,secure environment and tend to host their e-commerce systems with a hosting provider

In this day and age, it is extremely unlikely for sensitive data to be left on these publicservers In some cases, online credit card processors are used, leaving the small business withthe freedom of not having to deal with storing and managing this information Some compa-nies, however, still process credit card information internally It is possible they also have abrick and mortar store and handle sales processing together It is important to these compa-nies to transmit the sensitive information from their public site to their more secure internalnetwork SSL is one possible method of handling this The data is encrypted during transit.Though once received, the data is back to clear text This may not be a desirable situation.This is a case where XML encryption may come in handy

Introducing XML Encryption

XML signatures only get you so far They provide the mechanisms to verify the integrity andauthenticity of the data, but the data is still, in most cases, in plain text The W3C has definedsome specifications in order for systems to implement a common format to perform XMLencryption The XML Encryption Syntax and Processing specification (http://www.w3.org/TR/xmlenc-core/) specifies a process for encrypting data and representing the result in XML.The XML Encryption Requirements specification (http://www.w3.org/TR/xml-encryption-req/)specifies the requirements for implementing XML encryption

Encryption Granularity

You can use XML encryption to sign virtually any type of data This includes both XML andnon-XML-based data Just like XML signatures, the data can even be located outside the XMLencryption document This section will explain the granularity available using XML encryp-tion This means examining the different pieces and types of data that could be encrypted andtheir relation to the XML encryption document Consider the example of an order from ane-commerce site explained earlier If using XML format to describe the order, it may appear

in the following form, which is a stripped-down version of some payment information:

This is not the type of information you would want to store or pass around in plain text.

Rather, it will be encrypted, and the information to be encrypted within the structure is

com-pletely up to your needs and/or security concerns

Element Encryption

Element encryption involves encrypting an element within the document It includes the

opening and closing tags as well as all of its content For example, you may want to encrypt

the entire creditcard element within the payment document This will protect the payment

information by not only encrypting the credit card number but also the type of payment:

they know the customer may have opted to pay by cash on delivery (COD)

Mixed Content Encryption

If hiding the type of payment made by a customer is not necessary, then the content of the

creditcard element could be encrypted rather than the entire element This would then allow

some, internal to the company, to be able to examine the XML document and know the type

of payment being made without needing access to any of the encrypted information For

<CipherData><! Encryption Information Here ></CipherData>

</EncryptedData>

</creditcard>

</payment>

Character Data Encryption

Those even less concerned with the security of all but the actual credit card number may opt

to encrypt only the value of the number element This would effectively encrypt the text tent of the number element For example:

Arbitrary Data and XML Document Encryption

As I said before, you can encrypt any type of data Someone may want the entire paymentdocument encrypted so if it were intercepted, the interceptor would have no idea what infor-mation was contained within the XML encryption document For example:

Super Encryption

Data that is encrypted more than once is called super encryption It’s possible you are a

secu-rity zealot and are trying to prevent an attacker from ever gaining access to your data Or it’salso possible you have an XML document that already contains some encrypted data, and you

have added some information to the XML document and would like to encrypt this new,

mod-ified document In this case, you want the original encrypted data to be included in your set of

data to be encrypted rather than adding an EncryptedData element to the document, which

would then contain two sets of encrypted data Based on the syntax of XML encryption, which

I will be coming to shortly, it is invalid for an EncryptedData element to have an EncryptedData

as an ancestor It is perfectly valid, however, to encrypt an EncryptedData element to create a

new EncryptedData element:

<! First Encrypted Data >

<EncryptedData Id="encrypt1" xmlns='http://www.w3.org/2001/04/xmlenc#'

MimeType='text/xml'>

<CipherData><! Encryption Information Here ></CipherData>

</EncryptedData>

<! Super Encrypted Data Containing EncryptedData element with Id encrypt1 >

<EncryptedData Id="encrypt2" xmlns='http://www.w3.org/2001/04/xmlenc#'

MimeType='text/xml'>

<CipherData><! Encryption Information Here ></CipherData>

</EncryptedData>

Formats of XML Encryption

XML encryption can either be enveloping or be detached The examples you have seen so far

have all been enveloping structures The physical location of the encrypted data does not need

to live within the XML encryption structure The information provided within the CipherData

element, which is broken out when the structure is explained, could point to the location of the

encrypted data rather than include it within its content:

<! Example of Enveloping structure >

Introducing the XML Encryption Structure

Depending upon the algorithm used and any optional information provided to the recipient

to aid in key retrieval and additional decryption information, the structure can become a bit

complex This chapter will be using the Triple DES algorithm for encryption, and the structure

explained in the following sections will provide enough information to support the use ofthis algorithm.

■ Note Using different encryption algorithms may require the use of elements and attributes not covered inthis chapter The goal of this chapter is to provide enough information and examples so that you can under-stand at least the basic concepts of XML encryption and can begin implementing it using PHP and Triple DESencryption after reading the material This topic is quite lengthy, and complete coverage is beyond the scope

of this book You can find additional information regarding algorithms, structure, and processing in the fications identified at the beginning of this chapter

speci-EncryptedData Element

The EncryptedData element is the root of the XML encryption structure It is the containerfor the structure and holds information regarding the encryption used, key retrieval, and theencrypted data This element replaces the data being encrypted within an XML document orbecomes the root of an XML document if the data being encrypted is an entire XML document

or is not an XML document and does not reside within a document

The element lives within the http://www.w3.org/2001/04/xmlenc# namespace, as do most

of its children The possible children of this element are a CipherData element, which is required,and EncryptionMethod, KeyInfo, and EncryptionProperties elements, which are all optional Fouroptional attributes exist Other than the Id attribute, the attributes help the recipient restore theencrypted data to its original form during decryption:

• The Id attribute specifies an ID for the element

• The type attributes identifies the type of data prior to encryption For example, thevalue http://www.w3.org/2001/04/xmlenc#Element specifies the original data is XMLcontaining either an empty-element tag or a single element and its contents The valuehttp://www.w3.org/2001/04/xmlenc#Content indicates that the original data is XMLcontaining the contents of an element, which could consist of mixed content You canuse other values to help in restoring the data to its original state during decryption

• The MimeType attribute can describe the media type of the data that has beenencrypted

• The optional Encoding attribute can indicate the encoding of the original data

Based on this, an element that has been encrypted would be replaced with the followingEncryptedData element:

<EncryptedData xmlns="http://www.w3.org/2001/04/xmlenc#"

Type="http://www.w3.org/2001/04/xmlenc#Element">

<! Contents of EncryptedData element >

</EncryptedData>

EncryptionMethod Element

The EncryptionMethod element is an optional element It describes the algorithm that was

used to encrypt the data Without this element, the recipient must already know the algorithm

used in order to decrypt the data The child elements on EncryptionMethod depend upon the

type of algorithm used, which is specified by the value of the Algorithm attribute In this case,

the algorithm is Triple DES:

The KeyInfo element provides information about obtaining the key needed to decrypt the

data It is not required, but when not provided, the recipient must already know the correct

key to use in order to decrypt data This element is from the XML-Signature Syntax and

Pro-cessing specification and used according to that specification Please refer to the section

“Introducing XML Signatures” or the specification for more information

■ Tip Remember that this element lives in the http://www.w3.org/2000/09/xmldsig#namespace and,

when used within XML encryption, must be namespaced properly

The examples of XML encryption within this chapter do not offer any hints about the keyused The key for the examples is just the string "secret", and the only additional key informa-tion that will be provided is the name of the key, which will be mcryptiv, and the value used for

the initialization vector for the mcrypt functions This value is created when the IV is created

during encryption and then sent within the KeyValue element so that the data can be properly

The CipherData element is a required element that provides the encrypted data through

inclu-sion or by providing a reference to the location of it It is a container for either a CipherValue

element or a CipherReference element Only one of these elements can be present as the

con-tent for this element

is when using a CipherValue element, it must be decoded prior to finishing processing:

per-1. Select the algorithm (and parameters) to be used in encrypting this data.

2. Obtain and (optionally) represent the key

a. If the key is to be identified (via naming, via a URI, or included in a child element),construct the ds:KeyInfo as appropriate (for example, ds:KeyName, ds:KeyValue,ds:RetrievalMethod, and so on)

b. If the key itself is to be encrypted, construct an EncryptedKey element by sively applying this encryption process The result may then be a child ofds:KeyInfo, or it may exist elsewhere and may be identified in the preceding step

recur-3. Encrypt the data

a. If the data is an element or is element content, obtain the octets by serializing thedata in UTF-8 as specified in the XML 1.0 specification The encryptor can do theserialization If the encryptor does not serialize, then the application must performthe serialization

b. If the data is of any other type that is not already octets, the application must alize it as octets

seri-c. Encrypt the octets using the algorithm and key from steps 1 and 2

d. Unless the decryptor will implicitly know the type of the encrypted data, theencryptor should provide the type for representation

4. Build the EncryptedType (EncryptedData or EncryptedKey) structure

a. If the encrypted octet sequence obtained in step 3 is to be stored in the CipherDataelement within the EncryptedType, then the encrypted octet sequence is Base64encoded and inserted as the content of a CipherValue element

b. If the encrypted octet sequence is to be stored externally to the EncryptedTypestructure, then store or return the encrypted octet sequence, and represent theURI and transforms (if any) required for the decryptor to retrieve the encryptedoctet sequence within a CipherReference element

5. Process EncryptedData

a. If the Type of the encrypted data is an element or is element content, then theencryptor must be able to return the EncryptedData element to the application

The application can use this as the top-level element in a new XML document

or insert it into another XML document, which may require a re-encoding

b. If the Type of the encrypted data is not element or element content, then theencryptor must always return the EncryptedData element to the application Theapplication can use this as the top-level element in a new XML document or insert

it into another XML document, which may require a re-encoding

Prior to beginning any coding, the first things you need to decide are the algorithms to beused and the data to be encrypted In this case, the payment document will be used as the

original document, which needs the creditcard element to be encrypted The variable $doc

will represent this data loaded into a DOMDocument object The encryption algorithm will beTriple DES in Cipher Block Chaining (CBC) mode and use "secret":

$key = "secret";

Obtain the data to be encrypted, which in this case is the creditcard element:

$xpath = new DOMXPath($doc);

to deal with writing a routine to create the canonical form, a really fast and easy shortcut is tocreate a new document and import the node to be encrypted, as demonstrated in Listing 12-5

Listing 12-5.Serializing a Namespace Element and Preserving Namespace Information

/* Preserving Namespace information */

$tempdoc = new DOMDocument();

$iv = mcrypt_create_iv(mcrypt_enc_get_iv_size($td), MCRYPT_RAND);

mcrypt_generic_init($td, $key, $iv);

$encrypted_data = rtrim(mcrypt_generic($td, $plaintext));

mcrypt_generic_deinit($td);

mcrypt_module_close($td);

Now that you have the information needed for the KeyInfo, you need to create it Toensure that the initialization vector value, $iv, remains intact, it must be Base64 encoded andthen set as the content of the KeyValue element:

$keyInfo = $doc->createElementNS("http://www.w3.org/2000/09/xmldsig#", "KeyInfo");

The last step is to put all the pieces together within an EncryptedData element The type

of encrypted data is an XML element, so the Type attribute will be set accordingly At this

point, you can swap out the creditcard element with the new EncryptedData element:

$encData = $doc->createElementNS("http://www.w3.org/2001/04/xmlenc#",

"EncryptedData");

$encData->setAttribute("Type", "http://www.w3.org/2001/04/xmlenc#Element");

$creditcard->parentNode->replaceChild($encData, $creditcard);

Add the EncryptionMethod element so the recipient knows the algorithm being used This

is completely optional If both parties have already agreed on an algorithm, then it is not

nec-essary that this be added:

■ Caution You must use the octet form of the data for encryption When encrypting XML data, it must be

serialized using UTF-8 encoding Serializing a node using saveXML($node)will automatically have the proper

encoding, but when serializing an entire document using saveXML(), the encoding of the original document

is used If using an encoding that does not fit into octet form, convert the encoding to UTF-8 prior to

encod-ing Calling $doc->encoding = "UTF-8"prior to serialization will change the encoding to output the

correct data to be encrypted

Decrypting the data is even easier than encrypting the value This time the tree does not need

to be modified, unless you want to re-create the entire original document rather than just usethe resulting creditcard element Using the resulting data from the “Encrypting Data” section,the variable $encdom will be used as the DOMDocument object with the loaded data

■ Note Decryption processing for other algorithms or complex structures is more involved than what ispresented in this chapter The steps presented here are enough to handle most cases using basic structures,such as the one from the previous section, and allow you to begin working with XML encryption once youhave finished reading the chapter To use other algorithms or handle more complex structures, refer to theXML Encryption Syntax and Processing specification

The steps to decrypt the data depend heavily upon how data needs to be decrypted Theexample shown here is within a controlled environment You know what has been encryptedand how it has been encrypted, so you do not need to create a generic processor to handle alltypes of algorithms and XML encryption structures Because of this, you can skip many stepsand even perform them in a different order than defined in the specification For those whomay need to handle different types of encryption algorithms and structures, the following arethe steps detailed in the specifications They are performed for each EncryptedData or

EncryptedKey element within the document

1. Process the element to determine the algorithm, parameters, and ds:KeyInfo element

to be used If some information is omitted, the application must supply it

2. Locate the data encryption key according to the ds:KeyInfo element, which may tain one or more children elements These children have no implied processing order

con-If the data encryption key is encrypted, locate the corresponding key to decrypt it

(This may be a recursive step because the key-encryption key may itself be encrypted.)

Or, one might retrieve the data encryption key from a local store using the providedattributes or implicit binding

3. Decrypt the data contained in the CipherData element

a. If a CipherValue child element is present, then the associated text value is retrievedand Base64 decoded so as to obtain the encrypted octet sequence

b. If a CipherReference child element is present, the URI and transforms (if any) areused to retrieve the encrypted octet sequence

c. The encrypted octet sequence is decrypted using the algorithm/parameters andkey value already determined from steps 1 and 2

4. Process decrypted data of a Type element or element content

a. The clear-text octet sequence obtained in step 3 is interpreted as UTF-8 encodedcharacter data

b. The decryptor must be able to return the value of Type and the UTF-8 encodedXML character data The decryptor is not required to perform validation on theserialized XML

c. The decryptor should support the ability to replace the EncryptedData elementwith the decrypted element or element content represented by the UTF-8 encodedcharacters The decryptor is not required to perform validation on the result of thisreplacement operation The application supplies the XML document context andidentifies the EncryptedData element being replaced If the document into whichthe replacement is occurring is not UTF-8, the decryptor must transcode theUTF-8 encoded characters into the target encoding

5. Process decrypted data if Type is unspecified or is not an element or element content

a. The clear-text octet sequence obtained in step 3 must be returned to the applicationfor further processing along with the Type, MimeType, and Encoding attribute valueswhen specified MimeType and Encoding are advisory The Type value is normativebecause it may contain information necessary for the processing or interpretation

of the data by the application

b. Note this step includes processing data decrypted from an EncryptedKey Theclear-text octet sequence represents a key value and is used by the application indecrypting other EncryptedType element(s)

Based on these steps, the first step you need to do is locate the information suppliedregarding how the data was encrypted and possibly what type of data was encrypted Using

the loaded document, the first step is to locate the EncryptedData element and determine thealgorithm, KeyInfo element, and parameters to use:

$xpath = new DOMXPath($encdom);

$query = "//*[local-name()='EncryptedData' and "

/* default algorithm */

$algorithm = "http://www.w3.org/2001/04/xmlenc#tripledes-cbc";

/* Find the algorithm used for encryption */

$query = "//*[local-name()='EncryptionMethod' and "

Once the algorithm is located, the code then determines how and if this algorithm can

be used Again, the current application can handle only Triple DES in CBC mode and will duce an error for any other algorithm The mcrypt extension is being used for encryption, sobased on the algorithm, some initial values are prepared for when mcrypt is used in thedecryption process:

You must now obtain the KeyInfo information This is a controlled environment, and youknow that it contains a KeyName and KeyValue element The value you are mainly concerned

with is the KeyValue because this is where the value for the initialization vector resides for the

mcrypt functions The following code uses the DOMXPath evaluate() method The queries

convert the proper elements to strings, which, according to the XPath specification, return the

contents of the elements

/* Find Key Information */

$query = "string(//*[local-name()='KeyName' and "

for either a CipherValue element or a CipherReference element The CipherData element can

have only one of these elements as its child; based on which one it has, it determines the

loca-tion of the encrypted data:

/* Find the Cipher Information */

/* Find the child element as this element may have only one */

foreach ($CipherData->childNodes AS $node) {

if ($node->nodeType == XML_ELEMENT_NODE) {break;

}}}

/* Error out if no child elements found */

if (! $node) {

print "Unable to find Encrypted Data";

exit;

}

/* Based on the element name, find the data and obtain encrypted octet sequence */

if ($node->nodeName == "CipherReference") {

/* Handle CipherReference here

$encryptedData =

*/

} elseif ($node->nodeName == "CipherValue") {

/* Base64 decode the value to obtain encrypted octet sequence */

$encryptedData = base64_decode($node->nodeValue);

}

Using the information obtained earlier for the algorithm used, decrypt the data:

$td = mcrypt_module_open($mcryptalg, '', $mcryptblock, '');

/* IV was passed with KeyValue and must be used to properly decrypt */

mcrypt_generic_init($td, $key, $keyValue);

$decrypted_data = rtrim(mdecrypt_generic($td, $encryptedData));

mcrypt_generic_deinit($td);

mcrypt_module_close($td);

The variable $decrypted_data should now contain the decrypted creditcard element Any type of data may actually be decrypted, so the following block demonstrates how to gen-erically handle the decrypted data It is based on the information supplied by the content ofthe EncryptedType element, which has been stored in $encType:

$newdoc = NULL;

switch ($encType) {

case "http://www.w3.org/2001/04/xmlenc#Element":

/* load element into a new document */

$newdoc = new DOMDocument();

$newdoc = new DOMDocument();

If you followed this demonstration starting with the “Encrypting Data” section, the outputyou should see is as follows:

Security is always a concern for a developer and becomes more of an issue the more

pub-licly available an application is It is no different when working with XML In many cases,

it becomes more of an issue because XML documents are sent to and received from remote

sources It becomes important that the data can be trusted before being processed Many

developers I have spoken to rely on SSL and some type of application authentication to

pro-vide security for their data The XML is then sent through an SSL tunnel This may be fine when

working with Web servers, but it becomes quite a task for many when this is not the case

The payment example shown in the chapter is just a small example of how you can tect sensitive data It is inexcusable for anyone to send credit card information in plain text

pro-across the Internet With the number of security-related issues in the news, sometimes even

occurring within a company, it is not even safe to have this data in plain text on a secured

net-work XML encryption adds a layer of security by keeping the data secret and accessible only

to those with the keys to access the data Therefore, you have no reason to have this data in

plain text, and using XML encryption allows for easy storage as well as provides an easy

pack-aging for transport

An advantage of XML security is that it is just a format and process for securing data Thedata does not have to be in XML format, and it does not have to reside within the structure Using

this common format, any type of data, processed correctly, can be safeguarded and (assuming

the correct keys and algorithms used) processed in a standardized way The technology does not

define the algorithms or keys available for use; this means you can use whatever encryption tools

you have available, or you can change to some other algorithm and key system

This chapter introduced XML security by demonstrating how to use both XML signaturesand XML encryption using PHP I touched on only the tip of these technologies because an

entire book could be written on them alone The information presented, though, should

pro-vide a decent foundation to not only begin using these technologies but also to understand

how you can handle other algorithms, key systems, and more complex structures using the

specifications as a reference

The next chapter is a break in the examination of XML technologies and provides anintroduction to PEAR and some of the XML packages it offers The packages provide function-

ality written in PHP that can be used rather than having to write your own custom code for

many of the common XML needs and technologies

PEAR and XML

With the introduction of PHP 5 came a bunch of new tools to work with XML From XML

parsers to an XSLT processor and a SOAP service, the available extensions provide enough

functionality to serve the majority of your needs Problems some developers face, however,

include that the extensions are not included on the server they are working with (and

there-fore not under their control) and that the extensions do not natively support some specific

functionality You can at least work around the latter problem You would just be required to

code the specific functionality by hand using the available tools

The former issue is a bit more difficult to handle In a similar fashion, you could choose

to write the functionality by hand but would need to start at the ground level and would be

forced to re-create functionality that otherwise would have been available through any of the

extensions not currently available In cases like these, many developers will search the

Inter-net for preexisting code to leverage rather than starting from scratch The PHP Extension and

Application Repository (PEAR) solves some of these problems

This chapter will introduce PEAR and many of the packages you can use to work withXML data

What Is PEAR?

PEAR (http://pear.php.net/) is a centralized location for open source libraries, known as

packages, that developers can leverage within their applications What sets PEAR apart from

many of the repositories on the Internet is that the packages available through PEAR must

conform to a set of defined guidelines This helps to ensure that the packages are high quality

and will be maintained Therefore, you know that reported bugs will be fixed, or at least dealt

with; new features may be added, as long as they won’t break existing functionality; and

updated packages will be made available This should provide you with at least some feeling

of ease; in other words, once you start using a package, you will not be completely on your

own in the event of a problem The following list summarizes the purpose of PEAR:

• PEAR provides a centralized location for libraries, called packages, written by the PHP

community

• PEAR provides a distribution and management mechanism for these packages

• Packages within PEAR follow set coding standards

491

C H A P T E R 1 3

■ ■ ■

• PEAR consists of a large community with support available through its Web site andmailing lists.

• PEAR is governed by the PEAR group, which enforces that packages conform to lines and maintainers continue to follow the set guidelines

guide-PEAR is not an ad hoc repository Packages must first be submitted and approved by thecommunity before being added to the repository This ensures that the package conforms toPEAR’s guidelines and standards, and it also makes sure the package provides some neededfunctionality Of course, not all developers like using code they have not written and may not

be interested in what PEAR has to offer For those who do, however, PEAR is a perfect place

to search for quality code without having to worry about being left stranded in the event aproblem arises

Using PEAR

The easiest way to work with PEAR is to use the PEAR Package Manager Unless specificallybuilt without PEAR support or running under Windows, the PEAR Package Manager, as well

as a few core packages, is installed with the core PHP installation

■ Note Currently, it appears that PEAR will not be included with a default installation of PHP 6 You mustmanually install the PEAR core and installer

In the event your system does not include the core PEAR installation, you can install itwith some simple commands In a Linux/Unix environment, depending upon the name ofyour command-line browsers, one of the following should install and set up the PEAR core:

lynx -source http://go-pear.org/ | php

links -source http://go-pear.org/ | php

Installing in a Windows environment is just a bit different The core PHP installation includes

a BAT file named go-pear.bat Execute this file, and follow the instructions it provides

In the event you are on a shared host or cannot install a systemwide PEAR installation,additional options are available, such as installing a local copy of PEAR To install packages asdescribed in this chapter, you should have the PEAR Package Manager installed and an avail-able Internet connection You can find instructions for performing manual installations ofPEAR packages within the PEAR manual at http://pear.php.net/manual/index.php

You can access the PEAR Package Manager from the command line using the pearcommand:

pear <command>

Although several commands are available, Table 13-1 presents the most commonly usedones

Table 13-1.PEAR Package Manager Commands

Command Argument Description

info <package name> Displays information about the supplied package

install <package name> Installs the specified package

list-all Lists all the packages and shows versions for both the

available and installed packageslist-upgrades Lists all the packages with upgrades available

remote-info <package name> Displays information about the specified package

remote-list Lists the packages and versions from the remote repository

upgrade <package name> Upgrades the specified package

upgrade-all Upgrades all the packages with upgrades available

Using the commands listed in Table 13-1, the following sequence of commands will list allcurrently installed PEAR packages, upgrade any installed packages with available upgrades,

display information about the XML_Parser package, and install the package (assuming it is notalready installed):

pear list

pear upgrade-all

pear remote-info XML_Parser

pear install XML_Parser

Using PEAR and XML Together

The majority of XML packages in PEAR require at least the xml extension This is not a serious

stumbling block because this extension has been part of the core PHP installation since the

pre–PHP 4 days The xml extension is the oldest XML-based extension With a lot of

applica-tions and other extensions based on the xml extension, it’s difficult to find an installation of

PHP that does not include this extension

PEAR provides many different branches in its tree Each branch provides a grouping of acertain type of functionality The packages I will present in this chapter deal specifically with

XML functionality Chapter 20 will cover packages relating to Web service functionality PEAR

has an active community, and packages are proposed and added often At the time of this

writing, PEAR contains 28 XML-based packages, but I will present only a few in this chapter

If you use any of the XML packages, your script needs to include the library Each ofthese packages lives in the XML branch and is included using the normal PEAR syntax

require_once 'XML/<package_name>'; You can find the require statement for each of the

packages in the following sections of this chapter

XML_Parser Package

The XML_Parser package provides an object-oriented interface to the xml extension If you

read Chapter 8, you are probably wondering what advantage this offers, because the extension