Getting Started with cXML

2022-05-10

Content

1 Preface....................................................................6

1.1 Audience and Prerequisites......................................................6

1.2 Typography.................................................................6

2 Introduction to cXML.........................................................8

2.1 cXML, an XML Implementation...................................................8

2.2 cXML Capabilities.............................................................8

Catalogs.................................................................9

PunchOut...............................................................10

Purchase Orders...........................................................11

2.3 Types of Applications that Use cXML...............................................12

2.4 Content Delivery Strategy...................................................... 13

2.5 cXML DTDs.................................................................14

2.6 Prole Transaction............................................................15

2.7 Service Status Response .......................................................16

2.8 XML Utilities................................................................16

3 cXML Basics...............................................................17

3.1 Protocol Specication.........................................................17

Request-Response Model....................................................17

cXML Conventions.........................................................18

cXML Document.......................................................... 19

Wrapping Layers.......................................................... 19

Attachments.............................................................20

cXML Envelope...........................................................24

Header.................................................................27

Request................................................................32

Response...............................................................33

One-Way (Asynchronous) Model...............................................37

Message................................................................38

Transport Options.........................................................38

Service Status Response.................................................... 41

3.2 Basic Elements..............................................................42

Type Entities.............................................................42

Base Elements........................................................... 43

4 Alternative Authentication Methods............................................ 46

4.1 Message Authentication Code (MAC)..............................................46

Getting Started with cXML

Content

Overview of MACs.........................................................46

Computation Algorithm.....................................................46

Creation and Expiration Dates.................................................47

Computation Process.......................................................47

ProleResponse.......................................................... 49

CredentialMac............................................................49

4.2 Auth Transaction............................................................ 50

AuthRequest.............................................................51

AuthResponse............................................................52

5 cXML Digital Signatures......................................................54

5.1 Digital Signature Overview......................................................54

Options for Signing........................................................ 54

5.2 Signing cXML Documents......................................................55

cXML Digital Signatures.....................................................55

Error Status Codes for Digital Signatures.........................................58

Digital Signature Example....................................................58

6 Revision History............................................................61

Getting Started with cXML

Content

cXML License Agreement

IMPORTANT: PLEASE CAREFULLY READ THIS cXML LICENSE AGREEMENT (“LICENSE”) BEFORE USING THE

cXML SPECIFICATION (“SPECIFICATION”). BY USING THE SPECIFICATION, YOU AGREE TO BE BOUND BY

THE TERMS OF THIS LICENSE. IF YOU DO NOT AGREE TO THE TERMS OF THIS LICENSE, DO NOT USE OR

ACCESS THE SPECIFICATION. Licensor may publish new versions (including revisions) of this Agreement from

time to time on the cXML site (www.cxml.org). The rights granted under this license with respect to the

Specication are subject to the version of the Agreement in eect at the time it was downloaded or accessed

by you.

1. Openness. cXML is designed and intended to be an open standard to facilitate electronic commerce. You

are welcome to use and adopt this standard, and to submit comments, recommendations, and

suggestions to cXML.org. Once submitted, your comments go through an approval process - and your

comments may ultimately be incorporated into cXML.

2. License. Subject to the terms and conditions herein, Licensor hereby grants to you a perpetual,

nonexclusive, royalty-free, worldwide right and license to use the Specication under the Licensor

intellectual property necessary to implement the Specication to (a) use, copy, publish, and distribute

(including but not limited to distribution as part of a separate computer program) the unmodied

Specication, and (b) to implement and use the Specication, including the cXML tags and schema

guidelines included in the Specication for the purpose of creating, distributing, selling or otherwise

transferring computer programs that adhere to such guidelines. If you use, publish, or distribute the

unmodied Specication, you may call it “cXML”.

3. Restrictions. Your rights under this License will terminate automatically without notice from Licensor if you

fail to comply with any terms of this License.

4. Licensor expressly reserves all other rights it may have in the material and subject matter of the

Specication, and you acknowledge and agree that Licensor owns all right, title, and interest in and to the

Specication, however, Licensor does not own the computer programs or related documentation you

create, nor does Licensor own the underlying XML or non-Ariba intellectual property from which cXML has

been derived. You agree to not assert any intellectual property rights that would be necessarily infringed by

implementation or other use of the Specication against Licensor or any other entity with respect to such

implementation or other use of the Specication; provided that your agreement to not assert shall cease to

apply to any entity including Licensor (except where Licensor or another entity is asserting intellectual

property rights against you as part of an assertion that you have breached this Agreement) that asserts

against you that its intellectual property rights are infringed by your implementation or other use of the

Specication. If you publish, copy or distribute the Specication, then this License must be attached. If you

submit any comments or suggestions to Licensor, and Licensor modies the Specication based on your

input, Licensor shall own the modied version of the Specication.

5. No Warranty. YOU ACKNOWLEDGE AND AGREE THAT ANY USE OF THE SPECIFICATION BY YOU IS AT

YOUR OWN RISK. THE SPECIFICATION IS PROVIDED FOR USE “AS IS” WITHOUT WARRANTY OF ANY

KIND. LICENSOR AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES OF ANY KIND, INCLUDING BUT NOT

LIMITED TO ANY EXPRESS WARRANTIES, STATUTORY WARRANTIES, AND ANY IMPLIED WARRANTIES

OF: MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMNT. YOUR SOLE

AND EXCLUSIVE REMEDY RELATING TO YOUR USE OF THE SPECIFICATION SHALL BE TO DISCONTINUE

USING THE SPECIFICATION.

6. Limitation of Liability. TO THE MAXIMUM EXTENT PERMITTED BY LAW, UNDER NO CIRCUMSTANCES

SHALL LICENSOR BE LIABLE FOR ANY DAMAGES WHATSOEVER RELATING TO THIS LICENSE OR YOUR

Getting Started with cXML

cXML License Agreement

USE OF THE SPECIFICATION (INCLUDING BUT NOT LIMITED TO INCIDENTAL, SPECIAL, PUNITIVE,

DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES), REGARDLESS OF WHETHER A CLAIM IS BASED ON

TORT, CONTRACT, OR OTHER THEORY OF LIABILITY, AND EVEN IF LICENSOR IS ADVISED OF THE

POSSIBILITY OF SUCH DAMAGE. To the extent your jurisdiction does not allow any of the above exclusions

of damages, in such case you agree that Licensor's total liability to you for all damages under this License

shall not exceed the amount of ten dollars ($10.00). 6. Government End Users. If the Specication is

supplied to the United States Government, the Specication is classied as “restricted computer software”

as dened in clause 52.227-19 of the FAR. The United States Government's rights to the Specication are

as provided in clause 52.227-19 of the FAR.

7. This License shall be deemed to have been made in, and shall be construed pursuant to the laws of the

State of California and the federal U.S. laws applicable therein, excluding its conict of laws provisions. Any

legal action or proceeding relating to this License shall be instituted in a state or federal court in San

Francisco, Santa Clara or San Mateo County, California, and each party hereby consents to personal

jurisdiction in such counties. If for any reason a court of competent jurisdiction nds any provision, or

portion thereof, to be unenforceable, the remainder of this License shall continue in full force and eect.

8. You assume the entire risk resulting from your use of the Specication.

9. Complete Agreement. This License is the complete and exclusive statement, and an absolute integration of

the mutual understanding of the parties and supersedes and cancels all previous written and oral

agreements and communications relating to the subject matter of this License. You acknowledge that any

material breach by you of the provisions of the License will cause irreparable damage to Licensor and that

a remedy at law will be inadequate. Therefore, in addition to any and all other legal or equitable remedies,

Licensor will be entitled to seek injunctive relief necessary to remediate the breach of this License. Ariba,

Inc. shall be deemed the Licensor.

10. Notices. Any notice directed to Licensor must be sent in writing to comments@cxml.org.

7-19-04

Getting Started with cXML

cXML License Agreement

1 Preface

This document describes how to use cXML (commerce eXtensible Markup Language) for communication of

data related to electronic commerce.

Audience and Prerequisites [page 6]

Typography [page 6]

1.1 Audience and Prerequisites

This document is intended for application developers who design cXML-enabled applications.

cXML is an open versatile language for the transaction requirements of:

● E-commerce network hubs

● Electronic product catalogs

● PunchOut catalogs

● Procurement applications

● Buyers

● Suppliers

● E-commerce service providers

Readers should have a working knowledge of e-commerce concepts, the HTTP Internet communication

standard, and XML format.

This document does not describe how to use specic procurement applications or network hubs.

1.2 Typography

cXML elements and attributes are denoted with a monotype font. cXML element and attribute names are case-

sensitive. Both are a combination of lower and uppercase, with elements beginning with an uppercase letter,

and attributes beginning with a lowercase letter. For example, MyElement is a cXML element, and

myAttribute is a cXML attribute.

The following table describes the typographic conventions used in this book:

Typeface or Symbol

Meaning Example

AaBbCc123

Text you need to change is italicized. http://server:port/inspector

AaBbCc123 The names of user interface controls, me

nus, and menu items

Choose Edit from the File menu.

Getting Started with cXML

Preface

Typeface or Symbol Meaning Example

AaBbCc123

Files and directory names, parameters,

elds in CSV les, command lines, and code

examples

A ProfileRequest document is

sent from a buyer to the network.

AaBbCc123 Book titles For more information, see Acme Con

guration Overview.

Getting Started with cXML

Preface

2 Introduction to cXML

This section introduces cXML (commerce eXtensible Markup Language) for electronic-commerce

transactions.

cXML, an XML Implementation [page 8]

cXML Capabilities [page 8]

Types of Applications that Use cXML [page 12]

Content Delivery Strategy [page 13]

cXML DTDs [page 14]

Prole Transaction [page 15]

Service Status Response [page 16]

XML Utilities [page 16]

2.1 cXML, an XML Implementation

XML (eXtensible Markup Language) is a meta-markup language used to create syntaxes for languages. It is

also a standard for passing data between applications, particularly those that communicate across the

Internet.

XML documents contain data in the form of tag/value pairs, for example:

<DeliverTo>Joe Smith</DeliverTo>

XML has a structure similar to HTML (HyperText Markup Language), which is an implementation of SGML,

XML’s parent meta language. Applications can extract and use data from XML documents more easily than

from HTML documents, however, because XML data is tagged according to its purpose. XML contains only

data, while HTML contains both data and presentation information.

Each cXML document is constructed based on XML Document Type Denitions (DTDs). Acting as templates,

DTDs dene the content model of a cXML document, for example, the valid order and nesting of elements, and

the data types of attributes.

The DTDs for cXML are les available on the www.cXML.org website.

2.2 cXML Capabilities

cXML allows buying organizations, suppliers, service providers, and intermediaries to communicate using a

single, standard, open language.

Getting Started with cXML

Introduction to cXML

Successful business-to-business electronic commerce (B2B e-commerce) portals depend upon a exible,

widely adopted protocol. cXML is a well-dened, robust language designed specically for B2B e-commerce,

and it is the choice of high volume buying organizations and suppliers.

cXML transactions consist of documents, which are simple text les containing values enclosed by predened

tags. Most types of cXML documents are analogous to hardcopy documents traditionally used in business.

The most commonly used types of cXML documents are:

● Catalogs [page 9]

● PunchOut [page 10]

● Purchase Orders [page 11]

The following subsections describe these cXML documents.

2.2.1 Catalogs

Catalogs are les that convey product and service content to buying organizations. They describe the products

and services oered by a supplier and their prices, and they are the main communication channel from

suppliers to their buyers.

Suppliers create catalogs so that organizations that use procurement applications can see their product and

service oerings and buy from them. Procurement applications read catalogs and store them internally in their

databases. After a buying organization approves a catalog, that content is visible to users, who can choose

items and add them to purchase requisitions.

Figure 1: Sending Product and Service Content to a Buying Organization

Suppliers can create catalogs for any product or service, regardless of how it is measured, priced, or delivered.

For each item in a catalog, basic information is required, and optional information enables advanced catalog

features, such as multi-language descriptions.

Getting Started with cXML

Introduction to cXML

2.2.2 PunchOut

PunchOut is an easy-to-implement protocol for interactive sessions managed across the Internet. Using real-

time, synchronous cXML messages, PunchOut enables communication between applications, providing

seamless user interaction at remote sites.

There are three types of PunchOut:

● Procurement PunchOut [page 10]

● PunchOut Chaining [page 11]

● Provider PunchOut [page 11]

Procurement PunchOut

Procurement PunchOut gives suppliers an alternative to static catalog les. PunchOut sites are live, interactive

catalogs running on a website.

Suppliers that have e-commerce websites can modify them to support PunchOut. PunchOut sites

communicate with procurement systems over the Internet by using cXML.

For PunchOut sites, procurement applications display a button instead of product or pricing details. When

users click this button, their Web browsers display pages from the supplier’s local website. Depending on how

the supplier implements these pages, users can browse product options, specify congurations, and select

delivery methods. When users are done selecting items, they click a button that returns the order information

to the procurement application. The fully congured products and their prices appear within users’ purchase

requisitions.

The following diagram shows an interactive PunchOut session between a user and a supplier web site.

Figure 2: Interactive PunchOut Session Between a User and a Supplier Website

Getting Started with cXML

Introduction to cXML

Suppliers’ websites can oer previously agreed-upon contract products and prices.

PunchOut Chaining

PunchOut chaining is Procurement PunchOut that involves more than one PunchOut. cXML Path Routing

enables this functionality.

Figure 3: PunchOut Chaining

cXML Path Routing allows the order and other subsequent messages to return to the marketplaces and

suppliers involved in producing the quote. Path Routing noties all parties about the nal order, and any

subsequent PunchOut species to the procurement application how to split orders on behalf of the

marketplace.

Provider PunchOut

Provider PunchOut enables applications to punch out to a remote applications that supply services to the

originating application, such as credit card validation, user authentication, or self-registration.

2.2.3 Purchase Orders

Buying organizations send purchase orders to suppliers to request fulllment of a contract.

Getting Started with cXML

Introduction to cXML

The following diagram shows a purchase order communicated to a supplier:

Figure 4: Purchase Order Communicated to a Supplier

cXML is better for communicating purchase orders than other formats (such as ANSI X12 EDI 850), because it

is exible, inexpensive to implement, and it supports the widest array of data and attachments.

2.3 Types of Applications that Use cXML

Any e-commerce application can use cXML. Buying organizations, vertical and horizontal buying communities,

suppliers, and application vendors currently use cXML. The following subsections describe the main types of

applications that currently use cXML.

Procurement Applications

Procurement applications, such as SAP Ariba Buying, SAP Ariba Buying and Invoicing, and Ariba Buyer, use

cXML for external transactions.

These applications allow communities of users to buy contract products and services from vendors approved

by their purchasing managers. Managers in the communities rst approve requested purchases, and approved

purchase orders are transmitted to suppliers through several possible channels, including cXML over the

Internet.

Getting Started with cXML

Introduction to cXML

Network Hubs

Network hubs, such as Ariba Network, are Web-based services for connecting buyers and suppliers. These Web

services provide features such as catalog validation and versioning, catalog publishing and subscription,

automated purchase order routing, and purchase order history.

Network hubs can act as intermediaries that authenticate and route requests and responses to and from

diverse organizations. Communication between these organizations can occur entirely through cXML over the

Internet.

PunchOut Catalogs

As described in the previous section, PunchOut catalogs are interactive catalogs, available at supplier websites.

PunchOut catalogs are made possible by Web server applications, written in a programming language such as

ASP (Active Server Pages), JavaScript, or CGI (Common Gateway Interface), that manage buyers’ PunchOut

sessions.

PunchOut catalogs accept PunchOut requests from procurement applications, identify the buying

organization, and display the appropriate products and prices in HTML format. Users then select items,

congure them, and select options if appropriate.

At the end of the PunchOut session, the PunchOut site sends descriptions of the users’ selections, in cXML

format, to the procurement applications.

Order-Receiving Systems

Order-receiving systems are applications at supplier sites that accept and process purchase orders sent by

buying organizations. Order-receiving systems can be any automated system, such as inventory management

systems, order-fulllment systems, or order-processing systems.

Because it is simple to extract information from cXML purchase orders, it is relatively easy to create the

adapters that enable existing order-receiving systems to accept them.

2.4 Content Delivery Strategy

Procurement applications present product and service content to users. Suppliers want to control the way their

buyers view their products or services, because presentation is critical to their sales process. Buying

organizations want to make content easily accessible and searchable to ensure high contract compliance.

Buying organizations and suppliers can choose from multiple methods for delivering product and service

content. The particular method to use is determined by agreement between a buying organization and a

supplier, and the nature of the products or services traded.

Getting Started with cXML

Introduction to cXML

The following table lists example categories of commonly procured products and services, and their preferred

content delivery methods.

Commodities Properties Content Delivery Method

Oce Supplies,

Internal Supplies

Static content, stable pricing Static catalogs

Lab Supplies,

MRO (Maintenance,

Repair, and Operations),

Electronic Parts

Requires normalization to be useful

PunchOut to a vertical commodity portal

Books,

Chemicals

Large number of line Items PunchOut to a supplier hosted site

Computers,

Network Equipment,

Peripherals

Many possible congurations PunchOut to a supplier hosted congura-

tion tool

Services,

Printed Materials

Content has highly variable attributes PunchOut to an electronic form at a sup

plier site

Buying organizations can either store content locally within the organization, or they can access it remotely on

the Internet through PunchOut. cXML catalogs support both storage strategies.

As this table indicates, PunchOut oers a exible framework upon which suppliers, depending on their

commodity or buyer, can provide customized content. The objective of this content strategy is to allow buyers

and suppliers to exchange catalog data by the method that makes the most sense.

2.5 cXML DTDs

Because cXML is an XML language, it is thoroughly dened by a set of Document Type Denitions (DTDs).

These DTDs are text les that describe the precise syntax and order of cXML elements. DTDs enable

applications to validate the cXML they read or write.

The header of each cXML document contains the URL to the DTD that denes the document. cXML

applications can retrieve the DTD and use it to validate the document.

For the most robust transaction handling, validate all cXML documents received. If you detect errors, issue the

appropriate error code so the sender can retransmit. cXML applications are not required to validate cXML

documents received, although it is recommended. However, all cXML documents must be valid and must refer

to the cXML DTDs described in the following section.

Getting cXML DTDs

DTDs for all versions of cXML are available on cXML.org. The various kinds of cXML documents are dened in

multiple DTDs to reduce DTD size, which enables faster validation in some parsers.

Getting Started with cXML

Introduction to cXML

Document DTD

Basic cXML documents http://xml.cXML.org/schemas/cXML/version/cXML.dtd

Conrmation and Ship No

tice

http://xml.cXML.org/schemas/cXML/version/Fulll.dtd

Invoice http://xml.cXML.org/schemas/cXML/version/InvoiceDetail.dtd

Type Denition http://xml.cXML.org/schemas/cXML/version/Catalog.dtd

Payment Remittance http://xml.cXML.org/schemas/cXML/version/PaymentRemittance.dtd

Request for Quotations http://xml.cXML.org/schemas/cXML/version/Quote.dtd

Contracts http://xml.cXML.org/schemas/cXML/version/Contract.dtd

Logistics http://xml.cXML.org/schemas/cXML/version/Logistics.dtd

where version is the full cXML version number.

cXML applications use these DTDs to validate all incoming and outgoing documents.

Caching DTDs

For best performance, cXML applications should cache DTDs locally. After cXML DTD les are published, they

never change, so you can cache them indenitely. (Each new version of the DTDs has a new URL.) When cXML

applications parse a cXML document, they should look at the SYSTEM identier in the document header and

retrieve that DTD if it has not already been stored locally.

Caching DTDs locally oers the advantages of faster document validation and less dependence on the

cXML.org site.

In some environments, cXML applications might not be allowed to automatically retrieve DTDs as they receive

new documents. In these environments, you must manually retrieve the DTDs, store them locally, and instruct

your applications to look for them locally, not at cXML.org. However, generated cXML documents must point to

the DTDs at cXML.org, not the local DTDs.

2.6 Prole Transaction

The Prole transaction communicates basic information about what transactions a particular cXML server can

receive. All cXML servers must support this transaction. It is intended for backend integrations between

applications, making the capabilities of cXML servers available to client systems.

This transaction consists of two documents, ProfileRequest and ProfileResponse. Together, they

retrieve server capabilities, including supported cXML version, supported transactions, and options to those

transactions.

 Note

All cXML 1.1 and higher servers must accept the Prole transaction.

Getting Started with cXML

Introduction to cXML

ProleRequest

The ProfileRequest document has no content. It simply routes to the specied cXML server.

ProleResponse

The server responds with a ProfileResponse document, which lists the cXML transactions it supports, their

locations, and any named options with a string value.

2.7 Service Status Response

A response with a status code of 200 from an URL that accepts POSTed cXML is up and running. When an

HTTP GET is sent to a service location, the service responds with a valid, dynamically generated cXML

Response document. A service can be any HTTP URL at which cXML Request documents are received.

2.8 XML Utilities

Utilities for editing and validating XML les are available free and for purchase on the Web. The following

describes a few of these utilities:

● Internet Explorer from Microsoft. An XML-aware Web browser that can validate XML les against DTDs.

www.microsoft.com/windows/ie/default.htm

● Turbo XML from TIBCO Software. An Integrated Development Environment (IDE) for creating, validating,

converting and managing XML assets.

www.tibco.com/software/metadata/turboxml.jsp

● XML Spy from Altova. A tool for maintaining DTDs and XML les with a grid, source and browser view.

www.altova.com

● XMLwriter from Wattle Software. A graphical XML authoring tool designed to manage XML projects.

www.xmlwriter.net

In addition, the following websites list more XML tools:

● www.xml.com

● http://www.ibm.com/developerworks/xml/

Getting Started with cXML

Introduction to cXML

3 cXML Basics

This section describes the basic protocol and data formats of cXML. It contains information needed to

implement all transactions.

Protocol Specication [page 17]

Basic Elements [page 42]

3.1 Protocol Specication

There are two communication models for cXML transactions: Request-Response and One-Way. Because these

two models strictly specify the operations, they enable simple implementation. Both models are required,

because there are situations when one model would not be appropriate.

3.1.1 Request-Response Model

Request-Response transactions can be performed only over an HTTP or HTTPS connection. The following

gure illustrates the steps in a Request-Response interaction between parties A and B:

Figure 5: Request-Response Transaction

This transaction contains the following steps:

1. Site A initiates an HTTP/1.x connection with Site B on a predetermined URL that represents Site B’s

address.

Getting Started with cXML

cXML Basics

2. Site A uses a POST operation to send the cXML document through the HTTP connection. Site A then waits

for a response.

3. Site B has an HTTP/1.x-compliant server that dispatches the HTTP Request to the resource specied by

the URL used in step 1. This resource can be any valid location known to Site B’s HTTP server, for example,

a CGI program or an ASP page.

4. Site B’s resource identied in step 3 reads the cXML document contents and maps the Request to the

appropriate handler for that request.

5. Site B’s handler for the cXML Request performs the work that the Request species and generates a

cXML Response document.

6. Site B sends the cXML Response to Site A through the HTTP connection established in step 1.

7. Site A reads the cXML Response and returns it to the process that initiated the Request.

8. Site A closes the HTTP connection established in step 1.

This process is then repeated for further Request/Response cycles.

To simplify the work in the above steps, cXML documents are divided into two distinct parts:

● Header—Contains authentication information and addressing.

● Request or Response data—Contains a specic request or response and the information to be passed.

Both of these elements are carried in a parent envelope element. The following example shows the structure of

a cXML Request document:

<cXML>

Header information

</Header>

Request information

</Request>

</cXML>

The following example shows the structure of a cXML Response document:

<cXML>

Response information

</Response>

</cXML>

The Response structure does not use a Header element. It is not necessary, because the Response always

travels in the same HTTP connection as the Request.

3.1.2 cXML Conventions

cXML uses elements to describe discrete items, which are properties in traditional business documents.

Elements also describe information with obvious subdivisions and relationships between those subdivisions,

such as an addresses, which are composed of street, city, and country.

cXML also uses attributes, which modify elements or provide context.

Getting Started with cXML

cXML Basics

Element and attribute names are case-sensitive and use whole words with capitals (not hyphens) separating

the words. Element names begin with an uppercase letter; attribute names begin with a lowercase letter, for

example:

Elements: Sender, Credential, Payment, ItemDetail

Attributes: payloadID, lineNumber, domain

If optional elements have no content (they are null), leave them out entirely. Avoid empty or whitespace

elements, because missing values can aect some parsers.

In DTD les and in this document, symbols are used to indicate how many times an element can occur in a

transaction. A ‘+’ means the element can occur one or more times, a ‘?’ means the element can occur 0 or

once, and a ‘*’ means the element can occur 0 or more times.

3.1.3 cXML Document

The cXML element is the body of a cXML document. A document might begin as follows:

<?xml version='1.0' encoding='UTF-8'?>

<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">

<cXML xml:lang="en-US"

payloadID=”[email protected]"

timestamp="2002-01-09T01:36:05-08:00">

The rst characters in cXML documents must be <? or <!. Documents must not start with white space or tabs.

For example, the HTML form that contains a PunchOutOrderMessage document must not insert any

character between the opening quote and the left angle bracket.

The second line in cXML documents must contain the DOCTYPE document type declaration. This is the only

external entity that can appear in cXML documents. This line references the cXML DTD.

cXML documents can have any one of the following top-level elements: cXML, Supplier, Contract, and

Index. The cXML element is for “transactional” data. The other elements describe static content.

Related Information

cXML DTDs [page 14]

3.1.4 Wrapping Layers

cXML documents are usually transmitted through HTTP with the HTTP header specifying a MIME

(Multipurpose Internet Mail Extensions) media type of text/xml and a charset parameter matching the

encoding in the cXML document.

Because HTTP is eight-bit clean, any character encoding supported by the receiving parser can be used

without a content-transfer encoding such as base64 or quoted-printable. All XML parsers support the UTF-8

Getting Started with cXML

cXML Basics

(Universal Transformation Format) encoding, which includes all Unicode characters, including all of US-ASCII.

Therefore, applications should use UTF-8 when transmitting cXML documents.

 Note

According to IETF RFC 2376 “XML Media Types,” the MIME charset parameter overrides any encoding

specied in the XML declaration. Further, the default encoding for the text/xml media type is us-ascii,

not UTF-8 as mentioned in Section 4.3.3 of the XML Specication. For clarity, cXML documents should

include an explicit encoding in the XML declaration. MIME envelopes should use a matching charset

parameter for the text/xml. You can also use the application/xml media type, which does not override

the XML declaration or aect the recipient's decoding notes, and which does not require the charset

parameter.

An HTTP transmission of a cXML document might include the following MIME and HTTP headers:

POST /cXML HTTP/1.0

Content-type: text/xml; charset="UTF-8"

Content-length: 1862

Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2

User-Agent: Java1.1

Host: localhost:8080

Connection: Keep-Alive

<?xml version="1.0" encoding="UTF-8"?>

…

3.1.5 Attachments

The cXML protocol supports the attachment of external les of any type to cXML documents. For example,

buyers sometimes need to clarify purchase orders with supporting memos, drawings, or faxes. Another

example is the CatalogUploadRequest document, which includes catalog les as attachments.

Files referenced by cXML documents can reside either on a server accessible by the receiver or within an

envelope that also includes the cXML documents themselves. To attach external les to a cXML document in a

single envelope, use Multipurpose Internet Mail Extensions (MIME). The cXML document contains references

to external parts sent within a multipart MIME envelope.

Including Attachments

A cXML requirement for this envelope (over the requirements described in IETF RFC 2046 “Multipurpose

Internet Mail Extensions Part Two: Media Types”) is the inclusion of Content-ID headers with each attached

le.

The contained URL must begin with cid:, which is the identier for the referenced attachment within the

larger transmission. The cid: identier must match the Content-ID header of one (and only one) part of the

MIME transmission containing the document being forwarded.

The following example shows the required skeleton of a cXML document with an attached JPEG image (without

the HTTP headers shown above):

POST /cXML HTTP/1.0

Getting Started with cXML

cXML Basics

Content-type: multipart/mixed; boundary=something unique

--something unique

Content-type: text/xml; charset="UTF-8"

<?xml version="1.0" encoding="UTF-8"?>

…

<URL>cid:[email protected]</URL>

</Attachment>

…

--something unique

Content-type: image/jpeg

Content-ID: <[email protected]>

…

--something unique--

This skeleton is also all that a receiving MIME parser must be able to process. Applications that make use of the

media type described in RFC 2387 “The MIME Multipart/Related Content-type” will get much more information

if the skeleton is enhanced:

POST /cXML HTTP/1.0

Content-type: multipart/related; boundary=something unique;

type="text/xml"; start=<[email protected]>

--something unique

Content-type: text/xml; charset="UTF-8"

Content-ID: <[email protected]>

<?xml version="1.0" encoding="UTF-8"?>

…

<URL>cid:[email protected]</URL>

</Attachment>

…

--something unique

Content-type: image/jpeg

Content-ID: <[email protected]>

…

--something unique--

Receiving MIME parsers that do not understand the multipart/related media type must treat the two

examples above identically. Each part of the MIME transmission can additionally have a Content-transfer-

encoding and use that encoding. This addition is not necessary for HTTP transmission. Content-description

and Content-disposition headers are optional within the cXML protocol, although they provide useful

documentation.

Attachment Examples

The following example shows a CatalogUploadRequest with an attached catalog.

POST /cXML HTTP/1.0

Content-type: multipart/related; boundary=kdflkajfdksadjfk;

type="text/xml"; start="<[email protected]>"

<--! begin first MIME body part header -->

--kdflkajfdksadjfk

Content-type: text/xml; charset=UTF-8

Content-ID: <[email protected]>

<--! end first MIME body part header -->

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">

<From>

Getting Started with cXML

cXML Basics

</Credential>

</From>

<To>

</Credential>

</To>

<SharedSecret>abracadabra</SharedSecret>

</Credential>

</Sender>

</Header>

<CatalogName xml:lang="en">Winter Prices</CatalogName>

<Description xml:lang="en">premiere-level prices</Description>

<URL>cid:[email protected]</URL>

</Attachment>

</CatalogUploadRequest>

</Request>

</cXML>

<--! begin second MIME body part header -->

--kdflkajfdksadjfk

Content-type: text/plain; charset=US-ASCII

Content-Disposition: attachment; filename=PremiereCatalog.cif

Content-ID: <[email protected]>

Content-length: 364

<--! end second MIME body part header -->

CIF_I_V3.0

LOADMODE: F

CODEFORMAT: UNSPSC

CURRENCY: USD

SUPPLIERID_DOMAIN: DUNS

ITEMCOUNT: 3

TIMESTAMP: 2001-01-15 15:25:04

DATA

942888710,34A11,C11,"Eames Chair",11116767,400.00,EA,3,"Fast MFG",,,400.00

942888710,56A12,C12,"Eames Ottoman",11116767,100.00,EA,3,"Fast MFG",,,100.00

942888710,78A13,C13,"Folding Chair",11116767,25.95,EA,3,"Fast MFG",,,25.95

ENDOFDATA

--kdflkajfdksadjfk--

Surround IDs in Content-ID or Content-Type headers with angle brackets (< >), but omit these brackets

when referring to IDs in URL elements. Similarly, prepend message IDs with cid: in URL elements, but not in

MIME headers.

Special characters in cid URLs must be hex encoded (in %hh format).

Use the Attachment element when attaching text les, PDFs, images, or other such documents to a cXML

document. When attaching another cXML document, use cXMLAttachment, regardless of whether that cXML

document contains attachments itself. The cXMLAttachment element serves to alert the receiving system

that additional cXML processing might be required to handle the attachment.

The following example shows a CopyRequest forwarding a cXML document with attachments using

cXMLAttachment.

Content-Type: Multipart/Related; boundary=outer-boundary

Getting Started with cXML

cXML Basics

[Other headers]

--outer-boundary

Content-Type: text/xml; charset=UTF-8

Content-ID: <[email protected]>

[Other headers]

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">

<cXML payloadID="[email protected]"

timestamp="2003-11-20T23:59:45-07:00">

<From>

<Identity>[email protected]</Identity>

</Credential>

</From>

<To>

<Identity>[email protected]</Identity>

</Credential>

</To>

<Identity>[email protected]</Identity>

<SharedSecret>abracadabra</SharedSecret>

</Credential>

<UserAgent>Sender Application 1.0</UserAgent>

</Sender>

</Header>

<URL>cid:[email protected]</URL>

</Attachment>

</cXMLAttachment>

</CopyRequest>

</Request>

</cXML>

--outer-boundary

Content-Type: Multipart/Related; boundary=inner-boundary

Content-ID: <[email protected]>

[Other headers]

--inner-boundary

Content-Type: text/xml; charset=UTF-8

Content-ID: <[email protected]>

[Other headers]

[Forwarded cXML]

--inner-boundary

[Attachment 1 of the forwarded cXML]

--inner-boundary

[Attachment 2 of the forwarded cXML]

--inner-boundary--

--outer-boundary--

More Information About MIME

For more information about the MIME standard, see the following websites:

● www.hunnysoft.com/mime

Getting Started with cXML

cXML Basics

● www.ietf.org/rfc1341.txt

● www.ietf.org/rfc/rfc2046.txt

● www.ietf.org/rfc/rfc2387.txt

3.1.6 cXML Envelope

The cXML element is the root of cXML documents, and it contains all other elements. The cXML element is

present in every cXML transaction. The following example shows a fully specied cXML element:

<cXML xml:lang="en-US"

[email protected]

timestamp="1999-03-31T18:39:09-08:00">

cXML has the following attributes:

Attribute

Description

version

(deprecated)

This attribute was deprecated in cXML 1.2.007; do not use it in new cXML documents.

Species the version of the cXML protocol. A validating XML parser could also determine

the version attribute from the referenced DTD.

Because this version number also appears in the SYSTEM identier in the cXML docu

ment, you should omit this attribute.

xml:lang

The locale used for all free text sent within this document. The receiver should reply or dis

play information in the same or a similar locale. For example, a client specifying

xml:lang=“en-UK” in a request might receive “en” data in return. Specify the most

descriptive and specic locale possible.

payloadID

(required)

A unique number with respect to space and time, used for logging purposes to identify

documents that might have been lost or had problems. This value should not change for

retry attempts.

The recommended implementation is:

datetime.process id.random number@hostname

timestamp

(required)

The date and time the message was sent, in ISO 8601 format. This value should not

change for retry attempts.

The format is YYYY-MM-DDThh:mm:ss-hh:mm (for example,

2015-07-14T19:20:30+01:00).

signatureVersion

If present, implies that the document is digitally signed, that is, that the document con

tains one or more valid

ds:Signature elements immediately following the Request,

Response, or Message element. The only valid value for the attribute is 1.0; other val

ues are reserved for future use.

Related Information

cXML Digital Signatures [page 54]

Getting Started with cXML

cXML Basics

3.1.6.1 Locale Specied by xml:lang

The xml:lang attribute also appears with most free text elements (such as Description and Comments).

While the XML specication allows the locale for an element to default to that specied for any parent element,

such defaults result in inecient queries of the document tree. cXML attempts to keep the locale identiers

together with the aected strings. The most descriptive and specic locale known should be specied in this

attribute.

The xml:lang attributes appearing throughout the cXML protocol have no eect on formatted data such as

numbers, dates, and times. As described for the timestamp attribute in the following section, for the

timestamp attribute, such discrete values are formatted according to their data types. Longer strings (and

referenced Web pages) not intended for machine processing might contain a locale-specic numeric or date

format that matches a nearby xml:lang attribute.

3.1.6.2 Date, Time, and Other Data Types

The timestamp attribute, and all other dates and times in cXML, must be formatted in the restricted subset of

ISO 8601. This is described in the Word Wide Web Consortium (W3C) Note entitled “Date and Time Formats”

available at

www.w3.org/TR/NOTE-datetime-970915.html.

Timestamps should include a complete date plus hours, minutes, and seconds. Fractions of a second are

optional. This protocol requires times expressed in local time with a time-zone oset from UTC (Coordinated

Universal Time, also known as Greenwich Mean Time). The “Z” time zone designator is not allowed.

For example, 2015-04-14T13:36:00-08:00 corresponds to April 14, 2015, 1:36 p.m., U.S. Pacic Standard

Time.

 Note

Although the timestamp attribute is required by the cXML DTD, validation of the value's format depends

on your application.

Further references for the date, time, and other data type formats used by cXML are:

● Microsoft’s XML Data Types Reference, msdn.microsoft.com/library/default.asp?url=/library/en-us/

xmlsdk/html/b24aafc2-bf1b-4702-bf1c-b7ae3597eb0c.asp

● The original XML Data proposal to the Word Wide Web Consortium (W3C), www.w3c.org/TR/1998/NOTE-

XML-data-0105

3.1.6.3 Special Characters

In cXML, as in XML, not all characters can be typed from the keyboard, such as the registered trademark

symbol (®). Others, such as < and &, have special meaning to XML. These characters must be encoded using

character entities.

Getting Started with cXML

cXML Basics

XML denes the following built-in character entities:

Entity Character

< <

> >

& &

" “

' ‘

For characters outside of the encoding you use, use the Unicode number of the character (decimal or

hexadecimal), preceded by pound (#). For example, ® and ® represent a registered trademark

symbol, ®.

For example,

<Description xml:lang="en-US">The best prices for software®</Description>

could be encoded as

<Description xml:lang="en-US">The best prices for software ®</Description>

Single (') or double (") quotation marks must be escaped only within attribute values that are quoted using that

delimiter. It is recommended that you use only single quotes to delimit attributes, unless the content will never

contain quotes.

3.1.6.3.1 Handling Special Characters in Documents

1. Use a template that only uses single quotes to delimit attributes.

2. Add values to the template by doing one of the following:

○ If the document is a PunchOutOrderMessage to be transmitted by the cxml-urlencoded hidden eld,

ll the values in the template using US-ASCII encoding. This encoding requires XML character entities

for all characters beyond that encoding. For example, enter the registered trademark symbol (®), which

is not available in US-ASCII, as ®.

○ Otherwise, ll the values in the document using UTF-8 encoding. UTF-8 should be used for all

documents sent by HTTP Post directly, or embedded in a cXML-base64 hidden eld. UTF-8 includes all

of US-ASCII.

3. XML escape attribute values and element content as you create the cXML document. Characters that

must be escaped are &, ', < and >.

The following steps are required if you are transmitting the document in a PunchOutOrderMessage.

4. Pay attention to all characters that browsers interpret:

○ If you are using a cxml-urlencoded hidden eld, convert all double quotes to ".

○ Further (for the cxml-urlencoded eld), escape all ampersands that appear in contexts signicant to

HTML with &. To be safe, you can escape all ampersands. For example, escape ampersand (&) as

& and apostrophe (') as '. Escape the registered trademark symbol (®) as ®.

○ Otherwise, if you are using a cxml-base64 hidden eld, base64 encode the entire cXML document.

Getting Started with cXML

cXML Basics

5. Embed the document in the HTML form with double quotes around the string value. For example, to send a

Money element with an attribute having the value ®®'"""&<>> and containing the value ®®''"""&<>>",

the XML document might appear as:

<?xml version='1.0' encoding='UTF-8'?>

<!DOCTYPE Money SYSTEM 'SpecialChars.dtd'>

®®'"""&lt;>></Money>

which should be encoded as follows:

<Input type="Hidden" name="cXML-urlencoded" value="<?xml version='1.0'

encoding='UTF-8'?>

<!DOCTYPE Money SYSTEM 'SpecialChars.dtd'>

<Money

alternateAmount='MoneyalternateAmount='&#174;&#xAE;&apos;"&#3

&quot;&amp;&lt;>&gt;'>&#174;&#xAE;'&apos;

"&#34;&quot;&amp;&lt;&gt;&gt;'</Money>">

<Input type="Hidden" name="cXML-

base64"value="PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0nVVRGLTgnPz4K

PCFET0NUWVBFIE1vbmV5IFNZU1RFTSAnU3BlY2lhbENoYXJzLmR0ZCc+CjxNb

25leSBhbHRlcm5hdGVBbW91bnQ9JyYjMTc0OyYjeEFFOyZhcG9zOyImIzM0OyZxd

W90OyZhbXA7Jmx0Oz4mZ3Q7Jz4KJiMxNzQ7JiN4QUU7JyZhcG9zOyImIzM0OyZx

dW90OyZhbXA7Jmx0Oz4mZ3Q7PC9Nb25leT4K">

The preceding examples illustrate alternatives for encoding the cXML-urlencoded eld. They avoid XML

escaping a few characters, such as angle brackets, that are not special to XML in all contexts. A direct

implementation of the previous steps would result in an HTML eld such as:

<Input type="Hidden" name="cXML-urlencoded" value="<?xml version='1.0'

encoding='UTF-8'?>

<!DOCTYPE Money SYSTEM 'SpecialChars.dtd'>

<Money alternateAmount='®®'"""

&<>>'>®®''"""

&<>></Money>">

or the XML document:

<?xml version='1.0' encoding='UTF-8'?>

<!DOCTYPE Money SYSTEM 'SpecialChars.dtd'>

®®''"""&<>></Money>

3.1.7 Header

The Header element contains addressing and authentication information. The Header element is the same

regardless of the specic Request or Response within the body of the cXML message. Applications need the

requestor's identity, but not validation that the information provided for identity is correct.

The following example shows the Header element:

Getting Started with cXML

cXML Basics

<From>

<Identity>[email protected]</Identity>

</Credential>

</From>

<To>

</Credential>

</To>

<Identity>[email protected]</Identity>

<SharedSecret>abracadabra</SharedSecret>

</Credential>

<UserAgent>Network Hub 1.1</UserAgent>

</Sender>

</Header>

The From and To elements are synonymous with From and To in SMTP mail messages; they are the logical

source and destination of the messages. Sender is the party that opens the HTTP connection and sends the

cXML document.

Sender contains the Credential element, which allows the receiving party to authenticate the sending party.

This credential allows strong authentication without requiring a public-key end-to-end digital certicate

infrastructure. Only a user name and password need to be issued by the receiving party to allow the sending

party to perform Requests.

When the document is initially sent, Sender and From are the same, However, if the cXML document travels

through network hubs, the Sender element changes to indicate current sending party.

3.1.7.1 From

This element identies the originator of the cXML request.

3.1.7.2 To

This element identies the destination of the cXML request.

3.1.7.3 Sender

This element allows the receiving party to identify and authenticate the party that opened the HTTP

connection. It contains a stronger authentication Credential than the ones in the From or To elements,

because the receiving party must authenticate who is asking it to perform work.

Getting Started with cXML

cXML Basics

3.1.7.4 UserAgent

A textual string representing the UserAgent who is conducting the cXML conversation. This should be a

unique per-product string, and ideally, per-version. Analogous to UserAgent for HTTP conversations.

3.1.7.5 Credential

This element contains identication and authentication values.

Credential has the following attributes:

Attribute

Description

domain

(required)

Species the type of credential. This attribute allows documents to contain multiple types

of credentials for multiple authentication domains.

For messages sent on Ariba Network, for instance, the domain can be

AribaNetworkUserId to indicate an email address, DUNS for a D-U-N-S number, or

NetworkId for a preassigned ID.

type

Requests to or from a marketplace identify both the marketplace and the member com

pany in

From or To Credential elements. In this case, the credential for the market

place uses the type attribute, which is set to the value “marketplace”.

Credential contains an Identity element and optionally a SharedSecret or a CredentialMac element.

The Identity element states who the Credential represents, while the optional authentication elements

verify the identity of the party.

SharedSecret

The SharedSecret element is used when the Sender has a password that the requester recognizes.

 Note

Do not use authentication elements in documents sent through one-way communication. One-way

transport routes through users’ browsers, so users would be able to see the document source, including

Credential elements.

CredentialMac

The CredentialMac element is used for the Message Authentication Code (MAC) authentication method.

This authentication method is used in situations where the sender must prove to the receiver that it has been

authenticated by shared secret by a trusted third party. For example, a direct PunchOut request can travel

directly from a buyer to a supplier without going through a network hub, because it contains a MAC (generated

by the network hub) that allows the supplier to authenticate it.

Getting Started with cXML

cXML Basics

The trusted third party computes the MAC and transfers it to the sender through the Prole transaction. The

MAC is opaque to the sender (it is secure and non-reversible). The MAC is transmitted from the trusted third

party to the sender with a ProfileResponse object.

The receiver computes the MAC using the same inputs as the trusted third party and compares it with the MAC

received in the cXML document. If the two values match, the document is authentic.

To learn how to compute the MAC value, see Message Authentication Code (MAC) [page 46].

CredentialMac has the following attributes:

Attribute

Description

type

(required)

Identies the data being authenticated and the method in which it is formatted for authen

tication. The only supported value is

"FromSenderCredentials".

algorithm

(required)

Identies for the MAC algorithm used on the data. The only supported value is “HMAC-

SHA1-96”.

creationDate

(required)

Species the date and time the MAC was generated.

expirationDate

(required)

Species the date and time after which this MAC is no longer valid. Receivers must reject

MACs that are received after the expirationDate. Receivers can optionally reject unexpired

MACs. For example, a receiver might reject MACs that are scheduled to expire in less than

an hour.

The following example shows a Credential element that contains a CredentialMac element:

<CredentialMac type=”FromSenderCredentials”

algorithm=”HMAC-SHA1-96”

creationDate=”2003-01-15T08:42:46-0800”

expirationDate=”2003-01-15T11:42:46-0800”>

MnXkusp8Jj0lw3mf

</CredentialMac>

<UserAgent>Procurement Application 8.1</UserAgent>

</Credential>

</Sender>

Multiple Credentials

The From, To, and Sender elements can each optionally contain multiple Credential elements. The purpose

of supplying multiple credentials is to identify a single organization using dierent domains. For example, an

organization might be identied by including both a DUNS number and a NetworkId number.

The receiver should validate all credentials with domains it recognizes and it should reject the document if any

credentials with recognized domains do not match an organization it knows. It should also reject the document

if any two credentials in the same From, To, or Sender section appear to refer to dierent entities.

The receiver should reject the document if there are multiple credentials in a To, From, or Sender section that

use dierent values but use the same domain.

Getting Started with cXML

cXML Basics

3.1.7.6 Correspondent

The From and To elements can each optionally contain a Correspondent element. Correspondent elements

are used in cases where a party or a connecting hub does not know the originating or receiving organization.

The sender, receiver, or connecting hub can use the information in the Correspondent element to identify the

unknown organization.

Correspondent has the following attribute:

Attribute

Description

preferredLanguage

The preferred language of the organization, if it is known.

Correspondent has the following elements:

Element

Description

Contact

(required)

Contains contact information for following up on an order. See Contact [page 44].

Routing

Denes the corresponding routing destination. See Routing [page 31].

Extrinsic

Contains any additional information related to this organization.

3.1.7.6.1 Routing

Denes the corresponding routing destination of an external business partner. Routing has the following

attribute:

Attribute

Description

destination

(required)

The name of the routing destination. Possible values:

● peppol

● fieldglass

The following example shows a Routing element for an external business partner:

<From>

</Identity>

</Credential>

</From>

<To>

</Identity>

</Credential>

<Name xml:lang="en-US">SupplierTradingName Ltd.</Name>

Getting Started with cXML

cXML Basics

<Street>Street</Street>

<State>State</State>

</PostalAddress>

</TelephoneNumber>

</Phone>

</Contact>

</Correspondent>

</To>

</Credential>

<UserAgent>Ariba Network</UserAgent>

</Sender>

</Header>

3.1.8 Request

Clients send requests for operations. Only one Request element is allowed for each cXML envelope element,

which simplies the server implementations, because no de-multiplexing needs to occur when reading cXML

documents. The Request element can contain virtually any type of XML data.

Typical Request elements are:

● OrderRequest

● ProfileRequest

● PunchOutSetupRequest

● StatusUpdateRequest

● GetPendingRequest

● ConfirmationRequest

● ShipNoticeRequest

● ProviderSetupRequest

● PaymentRemittanceRequest

Request has the following attributes:

Attribute

Description

deploymentMode

Indicates whether the request is a test request or a production request. Allowed values are

“production” (default) or “test”.

This attribute can be used to call out an element and all its children as a target for a digital

signing.

Getting Started with cXML

cXML Basics

Related Information

cXML Digital Signatures [page 54]

3.1.9 Response

Servers send responses to inform clients of the results of operations. Because the result of some requests

might not have any data, the Response element can optionally contain nothing but a Status element. A

Response element can also contain any application-level data. During PunchOut for example, the application-

level data is contained in a PunchOutSetupResponse element.

The typical Response elements are:

● ProfileResponse

● PunchOutSetupResponse

● GetPendingResponse

Response has the following attribute:

Attribute

Description

This attribute can be used to call out an element and all its children as a target for a digital

signing.

Related Information

cXML Digital Signatures [page 54]

3.1.9.1 Status

This element conveys the success, transient failure, or permanent failure of a request operation.

Status has the following attributes:

Attribute

Description

code

(required)

The status code of the request. For example, 200 represents a successful request. See the

table of codes below.

text

(required)

The text of the status. This text aids user readability in logs, and is a canonical string for

the error in English.

xml:lang The language of the data in the Status element. Optional for compatibility with cXML

1.0. Might be required in future versions of cXML.

Getting Started with cXML

cXML Basics

The attributes of the Status element indicate what happened to the request. For example:

The content of the Status element can be any data needed by the requestor and should describe the error. For

a cXML

200/OK status code, there might be no data. However, for a cXML 500/Internal Server Error

status code, or other similar code, it is strongly recommended that the actual XML parse error or application

error be presented. This error allows better one-sided debugging and interoperability testing. For example:

<Status code="406" text="Not Acceptable">cXML did not validate. Big Problem!</

Status>

The following table describes the cXML status code ranges:

Range

Meaning

2xx Success

4xx Permanent error. Client should not retry. The error prevents the request from being accepted.

5xx Transient error. Typically a transport error. Client should retry. The recommended number of retries is

10, with a frequency of one hour. At a minimum a six hour retry window is recommended. For high prior

ity requests, such as rush orders, you might want to increase the retry frequency.

Servers should not include additional Response elements (for example, a PunchOutSetupResponse

element) unless the status code is in the cXML 200 range (for example, cXML 200/OK).

Because cXML is layered above HTTP in most cases, many errors (such as HTTP 404/Not Found) are

handled by the transport. All transport errors should be treated as transient and the client should retry, as if a

cXML 500 range status code had been received. All HTTP replies that don’t include valid cXML content,

including HTTP 404/Not found and HTTP 500/Internal Server Error status codes, are considered transport

errors. Other common transport problems include timeouts, TCP errors (such as “connection refused”),

and DNS errors (such as “host unknown”). Validation errors in parsing a Request document would normally

result in a cXML permanent error in the 400 range, preferably 406/Not Acceptable.

The following table includes possible cXML status codes:

Status

Text Meaning

200 OK The server was able to execute the request or deliver it to the nal recipient. The

returned

Response might contain application warnings or errors: the cXML

Request itself generated no errors or warnings, however, this status does not

reect any errors or warnings that might be generated afterward by the applica

tion itself. You will receive no further status updates, unless an error occurs dur

ing later processing.

201

Accepted The request has been accepted for forwarding by an intermediate hub, or has

been accepted by its ultimate destination and not yet been examined. You will re

ceive updates on the status of the request, if a mechanism to deliver them is

available.

The client should expect later StatusUpdate transactions.

Getting Started with cXML

cXML Basics

Status Text Meaning

204 No Content

All Request information was valid and recognized. The server has no

Response data of the type requested.

In a PunchOutOrderMessage, this status indicates that the PunchOut ses

sion ended without change to the shopping cart (or client requisition).

211

OK Buyers can use this status code to send a broadcast message to suppliers to in

form them about any events they need to know, such as holiday schedules, pro

duction facility closure, or completion of certain activities such as planning run

completion.

280

The request has been forwarded by an intermediate hub. You will receive at least

one more status update. This status could mean that the request was delivered

to another intermediary or to the nal recipient with 201 status, or that it was for

warded via a reliable non-cXML transport.

281

The request has been forwarded by an intermediate hub using an unreliable

transport (such as email). You might receive status updates; however, if you do

not received status updates, there is not necessarily a problem.

400 Bad Request Request unacceptable to the server, although it parsed correctly.

401 Unauthorized

Credentials provided in the Request (the Sender element) were not recog

nized by the server.

402 Payment Required

This Request must include a complete Payment element.

403 Forbidden

The user has insucient privileges to execute this Request.

406 Not Acceptable

Request unacceptable to the server, likely due to a parsing failure.

409 Conict The current state of the server or its internal data prevented the (update) opera

tion request. An identical

Request is unlikely to succeed in the future, but only

after another operation has executed, if at all.

412 Precondition Failed

A precondition of the Request (for example, a PunchOut session appropriate

for a PunchOutSetupRequest edit) was not met. This status normally

implies the client ignored some portion of a previous transmission from a server

(for example, the operationAllowed attribute of a

PunchOutOrderMessageHeader).

417

Expectation Failed

Request implied a resource condition that was not met. One example might be

a SupplierDataRequest asking for information about a supplier unknown

to the server. This status might imply lost information at the client or server.

450 Not Implemented

The server does not implement the particular Request. For example,

PunchOutSetupRequest or the requested operation might not be sup

ported. This status normally implies the client has ignored the server’s prole.

475 Signature Required The receiver is unwilling to accept the document because it does not have a digi

tal signature.

476 Signature Verication

Failed

The receiver is unable to validate the signature, possibly because the document

was altered in transit, or the receiver does not support one or more algorithms

used in the signature.

Getting Started with cXML

cXML Basics

Status Text Meaning

477 Signature Unacceptable The signature is technically valid, but is not acceptable to the receiver for some

other reason. The signature policies or certicate policies may be unacceptable,

the type of certicate used may be unacceptable, or there may be some other

problem.

500

Internal Server Error

Server was unable to complete the Request.

550 Unable to reach cXML

server

Unable to reach next cXML server to complete a transaction requiring upstream

connections. An intermediate hub can return this code when a supplier site is un

reachable. If upstream connections complete, intermediate hubs should return

errors directly to the client.

551

Unable to forward re

quest

Unable to forward request because of supplier misconguration. For example, an

intermediate hub failed to authenticate itself to a supplier. Clients cannot rectify

this error, but this error might be resolved before the client retries.

560 Temporary server error For example, a server might be down for maintenance. The client should retry

later.

The following table lists possible status codes for catalog-upload requests:

Status

Text Meaning

200 Success The catalog-upload request succeeded.

201 Accepted The catalog-upload request is processing.

461 Bad Commodity Code The commodity code you assigned to the catalog is invalid.

462 Notication Error No notication method (email or URL) provided.

463 Bad Catalog Format The zip le is invalid.

464 Bad Catalog No catalog is attached, or more than one is attached.

465 Duplicate Catalog Name The name of the catalog exists.

466 No Catalog to Update The catalog to be updated does not exist.

467 Publish Not Allowed You attempted to publish a catalog that was not previously published.

468 Catalog Too Large The size of the uploaded le exceeds the 4 MB limit. Zip the catalog to

compress it before uploading it.

469 Bad Catalog Extension The le name of the catalog must have .cif, .xml, or .zip extensions.

470 Catalog Has Errors The message is the status of the catalog. (HasErrors)

499 Document Size Error The cXML document is too large.

561 Too Many Catalogs You cannot upload more than a specic number of catalogs per hour.

562 Publish Disabled Catalog publishing is temporarily unavailable due to scheduled mainte

nance. It will be back online by the specied date and time.

563 Catalog Validating You attempted to update a catalog before validation nished on a previ

ous version of the catalog.

When receiving unrecognized codes, cXML clients must handle them according to their class. Therefore, older

clients should treat all new 2xx codes as 200 (success), 4xx codes as 400 (permanent failure), and 5xx codes

as 500 (transient error). This behavior allows for both further expansions of the cXML protocol and server-

specic codes without loss of interoperability.

Getting Started with cXML

cXML Basics

3.1.10 One-Way (Asynchronous) Model

Unlike Request-Response transactions, One-Way messages are not restricted to the HTTP transport. One-way

messages are for situations when an HTTP channel (a synchronous request-response type operation) is not

appropriate. The following gure shows an example of how A and B might communicate with messages instead

of the Request-Response transaction.

Figure 6: One-Way Message (Asynchronous)

In this case, a possible scenario would be:

1. Site A formats and encodes a cXML document in a transport that Site B understands.

2. Site A sends the document using the known transport. Site A does not (and cannot) actively wait for a

response to come back from Site B.

3. Site B receives the cXML document and decodes it out of the transport stream.

4. Site B processes the document.

In the One-Way model, Site A and Site B do not have an explicit Request-Response cycle. For example, between

One-Way messages, messages from other parties might arrive and other conversations could take place.

To fully specify a one-way transaction, the transport used for the message must also be documented. For the

cXML transactions that use the one-way approach, the transport and encoding are specied. A common

example of a transaction that uses one-way is the PunchOutOrderMessage.

One-way messages have a similar structure to the Request-Response model:

<cXML>

Header information here…

</Header>

Message information here…

</Message>

</cXML>

The Header element is treated exactly as it is in the Request-Response case. The cXML element is also

identical to the one described in cXML Envelope [page 24]. The easiest way to tell the dierence between a

one-way message and a Request-Response message is the presence of a Message element (instead of a

Request or Response element). The following section discusses the Message element in more detail.

The Header element in a one-way message should not contain shared secret information in the sender

credential. Authentication is done using the BuyerCookie. This is dierent from Request-Response Header.

Getting Started with cXML

cXML Basics

3.1.11 Message

This element carries all the body level information in a cXML message. It can contain an optional Status

element, identical to that found in a Response element—it would be used in messages that are logical

responses to request messages.

Message has the following attributes:

Attribute

Description

deploymentMode

Indicates whether the request is a test request or a production request. Allowed values are

“production” (default) or “test”.

inReplyTo Species to which Message this Message responds. The contents of the inReplyTo

attribute would be the payloadID of a Message that was received earlier. This would

be used to construct a two-way conversation with many messages.

This attribute can be used to call out an element and all its children as a target for a digital

signing.

The inReplyTo attribute can also reference the payloadID of an earlier Request or Response document.

When a Request-Response transaction initiates a “conversation” through multiple one-way interactions, the

rst message can include the payloadID of the most recent relevant Request or Response that went in the

other direction. For example, a Message containing a PunchOutOrderMessage might include an inReplyTo

attribute containing the payloadID of the PunchOutSetupRequest that started the PunchOut session. The

BuyerCookie included in the PunchOut documents performs a similar function to that of the inReplyTo

attribute.

Related Information

cXML Digital Signatures [page 54]

3.1.12 Transport Options

There are two commonly used transports for one-way messages: HTTP and URL-Form-Encoding. These are

just two of the well-dened transports today; more could become supported in the future.

HTTP

Procurement applications pull information using one-way HTTP communication. The one type of transaction

that uses one-way HTTP communication is GetPendingRequest.

HTTPS is preferred, because it encrypts transmitted data for security.

Getting Started with cXML

cXML Basics

URL-Form-Encoding

URL-Form-Encoding enables integration between remote websites and procurement applications. It also

serves as a way to avoid requiring a listening server on the buyer’s system that is directly accessible through

the Internet. This transport is best understood by examining how the PunchOutOrderMessage transaction

works.

Remote websites do not directly send cXML PunchOutOrderMessage documents to procurement

applications; instead, they encode them as hidden HTML Form elds and post them to the URL specied in the

BrowserFormPost element of the PunchOutSetupRequest. When the user clicks a Check Out button on the

website after shopping, the website sends the data to the procurement application as an HTML Form Submit.

The following diagram illustrates what happens.

The semantics of packing and unpacking are described below.

Form Packing

Remote websites assign each PunchOutOrderMessage document to a hidden eld on the Form named cXML-

urlencoded or cXML-base64. They assign the HTML Form element a METHOD of POST and an ACTION

consisting of the URL passed in the BrowserFormPost element of the PunchOutSetupRequest. For

example:

<FORM METHOD=POST

ACTION="http://workchairs.com:1616/punchoutexit">

Getting Started with cXML

cXML Basics

<INPUT TYPE=HIDDEN NAME="cXML-urlencoded"

VALUE="Entire URL-Encoded PunchOutOrderMessage document">

</FORM>

Additional HTML tags on the page might contain the above fragment to describe the contents of the shopping

basket in detail.

 Note

When Web servers send the cXML-urlencoded eld, it is not yet URL encoded. This encoding is required

only when the form is submitted by Web browsers (when users click Check Out in the above example). Web

browsers themselves meet this requirement. The Web server must HTML-encode only the eld value,

escaping quotation marks and other special characters, so the form displays properly for the user.

The names cXML-urlencoded and cXML-base64 are case insensitive.

cXML-urlencoded

The cXML-urlencoded eld is URL encoded (per the HTTP specication) by the Web browser, not by the Web

server or the supplier. This is because the encoding is required only when the form is submitted by a Web

browser, such as when a user clicks Check Out in the previous example. However, the Web server must HTML-

encode the eld value, escaping quotation marks and other special characters, so that the form will display

correctly.

 Note

Suppliers should never URL encode the cXML-urlencoded eld. This eld is automatically URL-encoded by

the web browser.

For cXML-urlencoded data, the receiving parser cannot assume a charset parameter beyond the default for

media type text/xml. No character encoding information for the posted data is carried in an HTTP POST. The

receiving Web server cannot determine the encoding of the HTML page containing the hidden eld. The cXML

document forwarded in this fashion must therefore use us-ascii character encoding. Any characters

(including those “URI encoded” as “%XX”) found in the XML source document must be in the “us-ascii” set.

Other Unicode symbols can be encoded using character entities in that source document.

cXML-Base64

The cXML-base64 hidden eld supports international documents. cXML documents containing symbols

outside of “us-ascii” should use this eld instead of the cXML-urlencoded hidden eld. This alternative has

almost identical semantics, but the entire document is base64-encoded throughout transport and not HTML-

encoded to the browser or URL-encoded to the receiving Web server. Base64-encoding is described in RFC

2045 “Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies.”

Base64-encoding from the remote website through the browser and to the receiving Web server at the client

maintains the original character encoding of a cXML document. Though no charset parameter arrives with

the posted information, the decoded document (after the transfer encoding is removed) can be treated as the

Getting Started with cXML

cXML Basics

media type application/xml. This encoding allows the receiving parser to honor any encoding attribute

specied in the XML declaration. For this eld (as for any application/xml documents), the default

character encoding is

UTF-8.

Either of these hidden elds (cXML-urlencoded or cXML-base64) must appear in the data posted to the

procurement application. Though recipients should rst look for cXML-base64 in the data, it is wasteful to

send both elds.

Form Unpacking and Processing

The procurement application, which previously provided the appropriate URL, receives an HTML Form POST

containing the Form data as described above. The Form POST processor would rst look for the cXML-base64

variable, extract the value and base64-decode its contents. If that eld does not exist in the data, the Form

POST processor would look for the cXML-urlencoded variable, extract the URL-encoded cXML message and

URL-decode it. The decoded content of the eld is then processed as if it had been received through a normal

HTTP Request/Response cycle.

The implied media type of the document after decoding varies, with dierent possible character encodings:

● The cXML-urlencoded variable is of media type text/xml with no charset attribute. It is thus restricted to

the us-ascii character encoding. The receiving parser must ignore any encoding attribute in the XML

declaration of the cXML document because the browser might have changed the encoding.

● The cXML-base64 variable is of media type application/xml and thus might have any character

encoding (indicated by the encoding attribute of the contained XML declaration, if any). The default

character encoding is UTF-8, as for any application/xml documents.

The primary dierence between this transaction and a normal Request-Response transaction is that there is no

response that can be generated, because there is no HTTP connection through which to send it.

3.1.13 Service Status Response

This transaction determines whether a particular service is currently available. When an HTTP GET is sent to a

service location, the service responds with a valid, dynamically generated cXML Response document. A

service can be any HTTP URL at which cXML

Request documents are received.

For example, an HTTP GET sent to https://service.ariba.com/service/transaction/cxml.asp

yields the following response:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE cXML "http://xml.cXML.org/schemas/cXML/1.2.014/cXML.dtd">

<cXML timestamp="2001-01-08T10:47:01-08:00"

payloadID="[email protected]">

<Status code="200" text="OK">Ping Response Message</Status>

</Response>

</cXML>

Getting Started with cXML

cXML Basics

 Note

This combination of transport (HTTP) and protocol (cXML) levels should be used only for the case

described above.

3.2 Basic Elements

The following entities and elements are used throughout the cXML specication. Most of the denitions listed

here are basic vocabulary with which the higher-order business documents are described. The common type

entities and the common elements representing low-level objects are dened here.

3.2.1 Type Entities

Most of these denitions are from the XML-Data note submission to the World Wide Web Consortium (W3C). A

few higher-level type entities that are also dened here are not from XML-Data.

isoLangCode

An ISO Language Code from the ISO 639 standard.

isoStateCode

An ISO 3166-2:2013 country subdivision code that identies a state or province. It is used in conjunction with

the country codes listed in ISO 3166-1.

isoCountryCode

An ISO Country Code from the ISO 3166 standard.

xmlLangCode

A language code as dened by the XML 1.0 Specication (at www.w3.org/TR/1998/REC-xml-19980210.html).

In the most common case, this includes an ISO 639 Language Code and (optionally) an ISO 3166 Country Code

separated by a hyphen. Unlike the full XML recommendation, IANA or private language codes should not be

Getting Started with cXML

cXML Basics

used in cXML. IANA and private subcodes are allowed, though they should come after a valid ISO 3166 Country

Code.

The recommended cXML language code format is xx[-YY[-zzz]*]? where xx is an ISO 639 Language code, YY is

an ISO 3166 Country Code and zzz is an IANA or private subcode for the language in question. Again, use of the

Country Code is always recommended. By convention, the language code is lowercase and the country code is

uppercase. This is not required for correct matching of the codes.

UnitOfMeasure

UnitOfMeasure describes how the product is packaged or shipped. It must conform to UN/CEFACT Unit of

Measure Common Codes. See www.unece.org/cefact/codesfortrade/codes_index.html.

URL

A URL (Uniform Resource Locator) as dened by the HTTP/1.1 standard.

Related Information

cXML Envelope [page 24]

3.2.2 Base Elements

These elements, used throughout the specication, range from generic ones such as Name and Extrinsic to

specic ones such as Money.

Money

The Money element has three possible attributes: currency, alternateAmount, alternateCurrency.

The attributes currency and alternateCurrecy must be a three-letter ISO 4217 currency code. The

content of the Money element and of the aternateAmount attribute should be a numeric value. For example:

Getting Started with cXML

cXML Basics

The optional alternateCurrency and alternateAmount attributes are used together to specify an amount

in an alternate currency. These can be used to support dual-currency requirements such as the euro. For

example:

<Money currency="USD" alternateCurrency="EUR" alternateAmount="14.28">12.34

</Money>

 Note

You can optionally use commas as thousands separators. Do not use commas as decimal separators.

State

Contains the state or country subdivision identier. Contained by the PostalAddress element. It has an

optional isoStateCode [page 42] attribute.

Country

Contains the name of the country in a location. Contained by the PostalAddress element. It has an optional

isoCountryCode [page 42] attribute.

<Country isoCountryCode="US">United States</Country>

CountryCode

Contains the International ITU dial code for the country code. It can be entered onto a telephone keypad after

the escape code to reach the country. Used by the TelephoneNumber element.

</TelephoneNumber>

Contact

The Contact element contains information about any contact important to the current transaction. For

example:

Getting Started with cXML

cXML Basics

<Name xml:lang="en-US">Mr. Smart E. Pants</Name>

<Email>[email protected]</Email>

…

</Phone>

</Contact>

Getting Started with cXML

cXML Basics

4 Alternative Authentication Methods

cXML supports alternatives to the shared secret authentication method for verifying the sender of cXML

documents.

Message Authentication Code (MAC) [page 46]

Auth Transaction [page 50]

4.1 Message Authentication Code (MAC)

Message Authentication Code (MAC) authentication allows the authentication of documents sent directly from

a client to a server without passing through a trusted third party (such as a network hub) for authentication.

These documents contain a credential with an authentication code that can be interpreted only by the trusted

third party and the receiving server, not by the sender.

The format of the Credential element containing the MAC is described in Credential [page 29].

4.1.1 Overview of MACs

The primary purpose of MACs is to convey receivers’ shared secrets without revealing them to senders. MACs

keep shared secrets secure by encoding them through a hash.

MACs are as secure as shared secrets. Senders must guard MACs as carefully as shared secrets.

Compromising either piece of information could make trading partners vulnerable.

To use MAC authentication, both the trusted third party and the receiver must be able to compute MACs.

4.1.2 Computation Algorithm

MACs are created by an algorithm that combines data known by both the trusted third party and the receiver.

cXML species the use of the HMAC-SHA1 algorithm described in IETF RFC 2104, “HMAC: Keyed-Hashing for

Message Authentication”.

The HMAC-SHA1 algorithm provide the security required for cXML, and it has been formally proven to be as

secure as the underlying hash algorithm.

For more information about IETF RFC 2104, see www.ietf.org/rfc/rfc2104.txt.

Getting Started with cXML

Alternative Authentication Methods

4.1.3 Creation and Expiration Dates

Creation and expiration dates add additional security to MACs.

If a MAC is stolen, changing the sender’s shared secret has no eect. It is impractical to expect the sender to

contact the receiver out-of-band to invalidate the MAC, because they might not have an established

relationship. To address this problem, a creation date (creationDate) and an expiration date

(expirationDate) are embedded in MACs. The expiration date limits the damage that can be result from a

stolen MAC, because MACs eventually expire. The shorter the expiration period, the greater the security

aorded. Receivers must reject MACs that are received after their expiration date.

Receivers can also reject unexpired MACs based on the amount of time that has elapsed since the creation

date. For example, if a receiver receives a MAC that was created several years ago, but expires tomorrow, the

receiver might not wish to accept the MAC. This decision is left with the implementors of the receiving systems.

It is mandatory for receivers to check that the creation date is in the past and the expiration date is in the

future, and to reject it if either is not the case. However, it is optional for receivers to check whether the creation

date is too long in the past.

Receivers must not only check that MACs are valid, but also that the data authenticated by MACs is acceptable.

Specically, receivers must validate that they wish to accept messages from the entities identied by the From

and Sender credentials.

4.1.4 Computation Process

This section describes how to compute a MAC of type="FromSenderCredentials". The inputs for this MAC

type are known only by the trusted third party and the receiver.

The trusted third party uses this computation to generate ProfileResponse Option elements and the

receiving server uses it to validate the CredentialMac element.

4.1.4.1 Assembling the Hash Inputs

The MAC function takes two inputs, the data input and the secret key input:

● The data input is the UTF-8-encoded byte representation of each value listed below, in order, after

normalization, with each value terminated by a single null byte (0x00):

From/Credential@domain

From/Credential/Identity

Sender/Credential@domain

Sender/Credential/Identity

Sender/Credential/CredentialMac@creationDate

Sender/Credential/CredentialMac@expirationDate

● The secret key input is the cXML shared secret used between the receiver and the third party.

Getting Started with cXML

Alternative Authentication Methods

4.1.4.2 Normalizing the Inputs

Normalize the hash input values to remove dierences in case and formatting before computation:

Value Normalize by... Normalized Example

domain

Use the lowercase version of the string, unless it is known to

be case sensitive, for example, “AribaNetworkUserId”. Note

that “NetworkId” and “DUNS” are not case-sensitive.

networkid

Identity

Discard leading or trailing whitespace and use the lowercase

version of the string.

an9900000100

creationDate

expirationDate

No normalization needed, because they are in ISO8601 for

mat described in Date, Time, and Other Data Types [page

25].

2003-01-15T11:42:46-08:0

Do not normalize the shared secret.

4.1.4.3 MAC Algorithm

The only supported MAC algorithm value is "HMAC-SHA1-96", which corresponds to the HMAC-SHA1

algorithm, which produces a 160 bit (20 byte) output, and retaining only the left-most 96 bits (12 bytes). The 12

bytes are then base-64 encoded, yielding a 16-byte character string consisting only of characters in the set [A-

Z a-z 0-9 +/].

To computer the MAC:

1. Concatenate the UTF-8-encoded byte representation of the following strings, each followed by a null byte

(0x00). (The strings have been normalized as described above):

“networkid”, “an9900000100”, “networkid”, “an9900000100”,

“2003-01-15T08:42:46-08:00”, “2003-01-15T11:42:46-08:00”

The concatenation yields the following byte sequence:

6e 65 74 77 6f 72 6b 69 64 00 61 6e 39 39 30 30

30 30 30 31 30 30 00 6e 65 74 77 6f 72 6b 69 64

00 61 6e 39 39 30 30 30 30 30 31 30 30 00 32 30

30 33 2d 30 31 2d 31 35 54 30 38 3a 34 32 3a 34

36 2d 30 38 3a 30 30 00 32 30 30 33 2d 30 31 2d

31 35 54 31 31 3a 34 32 3a 34 36 2d 30 38 3a 30

30 00

2. Use HMAC-SHA1 to hash the above sequence with the receiver’s shared secret, for example,

“abracadabra” (61 62 72 61 63 61 64 61 62 72 61), which yields:

71 1e 89 a7 3e 7c 9e b8 97 11 10 cd 78 57 fd a0 94 da fd

Do not terminate or normalize the shared secret.

3. Truncate the above result to 96 bits (12 bytes):

71 1e 89 a7 3e 7c 9e b8 97 11 10 cd

Truncation helps increase the security of the hash.

Getting Started with cXML

Alternative Authentication Methods

4. Base-64 encode the above result to yield the nal result:

cR6Jpz58nriXERDN

The trusted third party inserts the nal result in ProfileResponse documents it sends to the entity that

will be the client (document sender), and the client inserts it in a CredentialMac element in all direct

communication to the server (document receiver).

4.1.5 ProleResponse

The following cXML example shows a ProfileResponse sent from a trusted third party (such as a network

hub) to a client (such as a procurement application) so the client can send direct requests to the receiving

server.

<cXML payloadID="[email protected]"

timestamp="2003-01-15T09:39:09-08:00" xml:lang="en-US">

<Option name="CredentialMac.type">FromSenderCredentials</Option>

<Option name="CredentialMac.creationDate">2003-01-15T08:42:46

-0800</Option>

<Option name="CredentialMac.expirationDate">2003-01-15T11:42:46

-0800</Option>

<Option name="CredentialMac.value">cR6Jpz58nriXERDN</Option>

<URL>https://service.hub.com/ANCXMLDispatcher.aw/ad/cxml</URL>

</Transaction>

<URL>https://service.hub.com/AN/cxml</URL>

<Option name="Direct.URL">https://bigsupplier.com/punchout</Option>

<Option name="Direct.AuthenticationMethod.CredentialMac">Yes

</Option>

</Transaction>

</ProfileResponse>

</Response>

</cXML>

4.1.6 CredentialMac

The following cXML document fragment shows an example CredentialMac element as it would be inserted

by the client in documents sent directly to the server.

<cXML>

<To>

</Credential>

</To>

<From>

Getting Started with cXML

Alternative Authentication Methods

</Credential>

</From>

<CredentialMac type="FromSenderCredentials"

algorithm="HMAC-SHA1-96"

creationDate="2016-01-15T08:42:46-0800">

expirationDate="2016-01-15T11:42:46-0800">

cR6Jpz58nriXERDN

</CredentialMac>

<UserAgent>Procure System 3.0</UserAgent>

</Credential>

</Sender>

</Header>

[. . .]

</cXML>

Related Information

Credential [page 29]

4.2 Auth Transaction

The Auth transaction allows receivers to validate organizations’ credentials through a mutually trusted third

party. It should be used to authenticate received documents that do not contain either a shared secret or a

MAC.

The receiver encloses the credential of the sender (the principal) in an AuthRequest document and sends it to

the trusted third party for validation.

If the principal attempts to authenticate using a client digital certicate, the receiver includes both the

principal’s credential and information about the principal’s certicate in the AuthRequest document. (The

receiver obtains this certicate information from its Webserver or TLS implementation.)

The trusted third party receives the AuthRequest and looks up the principal’s credential to see if it is a

recognized organization. If the principal’s certicate information was included, the trusted third party makes

sure the certicate is valid and that it matches the organization associated with the credential.

If the credential (and optional certicate) authenticates, the trusted third party responds with a positive

AuthResponse that contains the validated credential. If the credential is invalid, the trusted third party

responds with an empty cXML response of status 403 (Forbidden).

The receiver can cache the results of the Auth transaction until the expiration date indicated in the

AuthResponse. During this period, if the principal presents the same credential and certicate, the receiver

need not send another AuthRequest.

Getting Started with cXML

Alternative Authentication Methods

4.2.1 AuthRequest

A request sent to a mutually trusted third party to authenticate an entity.

The following example includes X509 certicate information, which comes from the requesting entity’s client

digital certicate.

<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.014/cXML.dtd">

<From>

</Credential>

</From>

<To>

</Credential>

</To>

<SharedSecret>abracadabra</SharedSecret>

</Credential>

<UserAgent>cXML application 2.0</UserAgent>

</Sender>

</Header>

</Credential>

<X509IssuerName>Verisign</X509IssuerName>

</X509IssuerSerial>

</X509Data>

</AuthRequest>

</Request>

</cXML>

4.2.1.1 Credential

A cXML credential. See Credential [page 29].

4.2.1.2 X509Data

Describes the X.509 client certicate being used for authentication.

Getting Started with cXML

Alternative Authentication Methods

X509IssuerSerial

A container for the serial number and issuer name of the X.509 certicate.

X509IssuerSerialChild has the following elements:

● X509IssuerName

The distinguished name of the issuer of the X.509 certicate. The distinguished name should be a string

representation of an LDAP Distinguished Name, as described in RFC 2253. For example,

C=US, O=”Mega Data Security, Inc.”, OU=Secure Server CA

● X509SerialNumber

The serial number of the X.509 certicate.

X509SKI

The Subject Key Identier of the X.509 certicate.

X509 SubjectName

The distinguished name of the subject of the X.509 certicate. This should be a string representation of an

LDAP distinguished name, as described in RFC 2253.

X509Certicate

Contains the Base-64-encoded X.509v3 certicate.

X509CRL

Contains a Base-64-encoded X.509v3 Certicate Revocation List.

4.2.2 AuthResponse

Returns a list of valid credentials of the person entity in the AuthRequest document. Note that this response

is for successful authentications only.

Getting Started with cXML

Alternative Authentication Methods

AuthResponse has the following attribute:

Attribute Description

expirationDate Species the time beyond which the information contained in the AuthResponse must

be discarded. The inclusion of this attribute species that the receiver can cache the Au

thResponse information until the expirationDate.

The absence of an expirationDate should be interpreted to forbid caching.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.014/cXML.dtd">

</Credential>

</AuthResponse>

</Response>

</cXML>

Getting Started with cXML

Alternative Authentication Methods

5 cXML Digital Signatures

Any cXML request, response, or message can be signed using World Wide Web Consortium (W3C) XML Digital

Signatures. Support for the XML Advanced Electronic Signature (XAdES) standard is also included.

Readers of this section should be familiar with electronic signature terminology and concepts such as

asymmetric key pairs, certicates, and smart cards.

Digital Signature Overview [page 54]

Signing cXML Documents [page 55]

5.1 Digital Signature Overview

Digital signatures conrm the identity of the sender of an electronic document, and ensure that the document

was not modied after it was generated by the signer. They consist of a series of bytes that contain

cryptographic information, including the sender’s public key and detailed information about the contents of the

document being signed.

An XML digital signature—which is a specic arrangement of a digital signature—is an element that contains

other information besides the cryptographic signature itself, including a list of what was signed, the signer’s

public key, and other attributes. A cXML signature is an XML digital signature of a certain form, as described

later in this chapter.

XML Advanced Electronic Signature (XAdES) provides basic authentication and integrity protection.

W3C XML signatures and XAdES have many options designed to allow for exibility.

For information about W3C XML digital signatures, see the following resources:

● www.w3.org

● XML Signature Syntax and Processing Version 1.1

For information about XAdES, see the following resources:

● XML Advanced Electronic Signatures (XAdES)

● uri.etsi.org/01903/v1.3.2

5.1.1 Options for Signing

You can use a service to sign documents on your behalf, or you can implement the necessary hardware or

software systems to sign the documents yourself. If you implement your own signing system, you must obtain

a certicate signed by a Certicate Authority (CA) trusted by the receiver. Meeting receiver requirements might

mean obtaining hardware that keeps the private key secret, such as a smart card or Hardware Security Module.

Note that signature and certicate requirements vary according to local laws and regulations. Prior to

implementing a signing system, be sure you learn the requirements of the relevant locale.

Getting Started with cXML

cXML Digital Signatures

5.2 Signing cXML Documents

A valid cXML digital signature is not just an XML signature, but an XML signature that uses particular options,

has particular elements present, and signs (or does not sign) certain portions of the document.

5.2.1 cXML Digital Signatures

Note that namespace prex conventions are used here when referring to elements that come from other

specications. All W3C XML Digital Signature elements use the ds prex, and all XAdES elements use the

xades prex.

5.2.1.1 ds:Signature Element

The cXML element contains a space for the ds:Signature element after the Request, Response, or

Message element. The ds:Signature element holds information about what is being signed, one or more

signatures, and the keys used to create the signature or signatures. It also has a place to store additional

information such as XAdES extensions or attachment manifests.

The cXML element also contains a space for the signatureVersion attribute.

Attribute

Description

signatureVersion If present, signatureVersion implies that the document is digitally

signed, that is, that the document contains a valid ds:Signature element

immediately following the Request, Response, or Message element. If

the document is signed, this attribute must be present. The only valid value

for the attribute is

1.0; other values are reserved for future use.

This attribute can be used to call out an element and all its children as a tar

get for signing. For example, if a document contains

<Request

Id="foo">, then in the digital signature <Reference URI="#foo">

will refer to the Request element and all its children. If the document is

signed, this attribute must be present.

The Message, Request, and Response elements contain an Id attribute.

Related Information

cXML Envelope [page 24]

cXML Basics [page 17]

Getting Started with cXML

cXML Digital Signatures

5.2.1.2 cXMLSignedInfo

The cXMLSignedInfo element includes cXML-specic details about the signature, and has the following

attributes:

Attribute

Description

signatureVersion

(required)

Implies that the document is digitally signed, that is, that the document con

tains a valid

ds:Signature element immediately following the Request,

Response, or Message element. The only valid value for the attribute is

1.0; other values are reserved for future use.

payloadID

(required)

Used to establish links between documents. The payloadID in the

cXMLSignedInfo element must be the same as the payloadID in the

document’s main cXML element.

(required)

Identies this cXMLSignedInfo element for purposes of the signature.

This attribute must always be present and should always have the value

"cXMLSignedInfo".

5.2.1.3 Signing Essentials

Because some information from the cXML header is signicant, it must be signed. To sign these attributes

from the header, repeat the information in a cXMLSignedInfo element placed within a ds:Object element.

The ds:Object must be the rst ds:Object in the signature. For example:

<ds:Object>

<cXMLSignedInfo Id="cXMLSignedInfo"

signatureVersion="1.0"

payloadID="xxx"/>

</ds:Object>

The value of the Id attribute must be "cXMLSignedInfo". The values of the signatureVersion and

payloadID attributes must exactly match the values specied in the cXML element, and the receiver of the

document must verify this match. No transforms should be used in this ds:Reference. This element must be

signed via the rst ds:Reference object in the ds:SignedInfo, as follows:

<ds:Reference URI="#cXMLSignedInfo">

<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>

<ds:DigestValue>xxxxxxxxxxxxxxxxxxxxxxxxxxx</ds:DigestValue>

</ds:Reference>

The Request, Response, or Message element should be signed in its entirety. To do this, specify the string

"cXMLData" as the value of the Id attribute on the Request, Response, or Message element and include a

ds:Reference element with the URI "#cXMLData" in the ds:SignedInfo. No transforms should be applied

to this reference. This ds:Reference must be the second ds:Reference in the ds:SignedInfo.

The ds:KeyInfo element should be present with a single ds:X509Certificate element. This should

include the Base64 encoding of the DER representation of an X.509 certicate containing the public key

corresponding to the private key used to sign the document.

Getting Started with cXML

cXML Digital Signatures

5.2.1.4 Using XAdES

The use of XAdES is required for digital signatures. In the signature, xades:QualifyingProperties should

be the second ds:Object. The xades:SignedProperties element and all its children must be signed by

specifying "

XAdESSignedProps" as the value for the Id attribute of xades:SignedProperties and including

a ds:Reference with the URI "#XAdESSignedProps" and no transforms in the ds:SignedInfo. When using

XAdES, the certicate referred to in the xades:Cert element must be the same as that contained in the

ds:KeyInfo element, the Id attribute of the ds:Signature element must be set to cXMLSignature and the

Target attribute of xades:QualifyingProperties must be #cXMLSignature.

5.2.1.5 Signing Attachments

If the document in question includes attachments, digital signatures can be used to sign just the document, or

both the document and its attachments. Signatures are structured in such a way that if the attachments are

discarded, the signature on the document itself can still be validated.

The attachments should be signed using ds:Reference elements in a ds:Manifest element included under

a ds:Object contained in the signature. The Id attribute of the ds:Manifest element must be

"AttachmentManifest". The ds:Object should occur immediately after the ds:Object containing the

xades:QualifyingProperties element, if it is present. Otherwise, it should occur immediately after the

ds:Object containing the cXMLSignedInfo element.

Each ds:Reference in the manifest should use a URI with the "cid:" scheme to refer to the attachments

through their MIME Content-Id. The ds:Manifest element itself should be signed using a fragment URI

reference included in the ds:SignedInfo. This requirement exists because a compliant XML signature

implementation must validate all the ds:Reference elements under ds:SignedInfo. Base validation

ensures that the manifest itself has not been corrupted, but will not validate the objects referred to in the

manifest. This approach makes it possible to validate the document on its own if the attachments have been

discarded. For example:

<ds:Object>

<ds:Manifest Id="AttachmentManifest">

<ds:Reference URI="cid:[email protected]">

<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>

<ds:DigestValue>P6ua59kKBLLtMBFE+IwPUgp2xqc=</ds:DigestValue>

</ds:Reference>

<ds:Reference URI="cid:[email protected]">

<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>

<ds:DigestValue>P6ua59kKBLLtMBFE+IwPUgp2xqc=</ds:DigestValue>

</ds:Reference>

</ds:Manifest>

</ds:Object>

Getting Started with cXML

cXML Digital Signatures

5.2.2 Error Status Codes for Digital Signatures

The following table lists cXML digital signature status codes:

Status

Text Meaning

475 Signature Required The receiver is unwilling to accept the document because it does not have a digi

tal signature.

476 Signature Verication

Failed

The receiver is unable to validate the signature, possibly because the document

was altered in transit, or the receiver does not support one or more algorithms

used in the signature.

477 Signature Unacceptable The signature is technically valid, but is not acceptable to the receiver for some

other reason. The signature policies or certicate policies might be unaccepta

ble, the type of certicate used might be unacceptable, or there might be some