RFC 2801
Internet Open Trading Protocol - IOTP Version 1.0
Pages: 290
Informational
Informational
Part 3 of 9 – Pages 56 to 92
4. IOTP Error Handling
IOTP is designed as a request/response protocol where each message is composed of a number of Trading Blocks which contain a number of Trading Components. There are several interrelated considerations in handling errors, re-transmissions, duplicates, and the like. These factors mean IOTP aware applications must manage message flows more complex than the simple request/response model. Also a wide variety of errors can occur in messages as well as at the transport level or in Trading Blocks or Components. This section describes at a high level how IOTP handles errors, retries and idempotency. It covers: o the different types of errors which can occur. This is divided into: - "technical errors" which are independent of the purpose of the IOTP Message, - "business errors" which indicate that there is a problem specific to the process (e.g., payment or delivery) which is being carried out, and o the depth of the error which indicates whether the error is at the transport, message or block/component level o how the different trading roles should handle the different types of messages which they may receive.
4.1 Technical Errors
Technical Errors are those which are independent of the meaning of the message. This means, they can affect any attempt at IOTP communication. Typically they are handled in a standard fashion with a limited number of standard options for the user. Specifically these are: o retrying the transmission, or o cancelling the transaction. When communications are operating sufficiently well, a technical error is indicated by an Error Component (see section 7.21) in an Error Block (see section 8.17) sent by the party which detected the error in an IOTP message to the party which sent the erroneous message. If communications are too poor, a message which was sent may not reach its destination. In this case a time-out might occur. The Error Codes associated with Technical Errors are recorded in the Error Component which lists all the different technical errors which can be set.4.2 Business Errors
Business Errors may occur when the IOTP messages are "technically" correct. They are connected with a particular process, for example, an offer, payment, delivery or authentication, where each process has a different set of possible business errors. For example, "Insufficient funds" is a reasonable payment error but makes no sense for a delivery while "Back ordered" is a reasonable delivery error but not meaningful for a payment. Business errors are indicated in the Status Component (see section 7.16) of a "response block" of the appropriate type, for example a Payment Response Block or a Delivery Response Block. This allows whatever additional response related information is needed to accompany the error indication. Business errors must usually be presented to the user so that they can decide what to do next. For example, if the error is insufficient funds in a Brand Independent Offer (see section 9.1.2.2), the user might wish to choose a different payment instrument/account of the same brand or a different brand or payment system. Alternatively, if
the IOTP based implementation allows it and it makes sense for that instrument, the user might want to put more funds into the instrument/account and try again.4.3 Error Depth
The three levels at which IOTP errors can occur are the transport level, the message level, and the block level. Each is described below.4.3.1 Transport Level
This level of error indicates a fundamental problem in the transport mechanism over which the IOTP communication is taking place. All transport level errors are technical errors and are indicated by either an explicit transport level error indication, such as a "No route to destination" error from TCP/IP, or by a time out where no response has been received to a request. The only reasonable automatic action when faced with transport level errors is to retry and, after some number of automatic retries, to inform the user. The explicit error indications that can be received are transport dependent and the documentation for the appropriate IOTP Transport supplement should be consulted for errors and appropriate actions. Appropriate time outs to use are a function of both the transport being used and of the payment system if the request encapsulates payment information. The transport and payment system specific documentation should be consulted for time out and automatic retry parameters. Frequently there is no way to directly inform the other party of transport level errors but they should generally be logged and if automatic recovery is unsuccessful and there is a human user, the user should be informed.4.3.2 Message Level
This level of error indicates a fundamental technical problem with an entire IOTP message. For example, the XML is not "Well Formed", or the message is too large for the receiver to handle or there are errors in the Transaction Reference Block (see section 3.3) so it is not possible to figure out what transaction the message relates to. All message level errors are technical errors and are indicated by Error Components (see section 7.21) sent to the other party. The Error Component includes a Severity attribute which indicates whether
the error is a Warning and may be ignored, a TransientError which indicates that a retry may resolve the problem or a HardError in which case the transaction must fail. The Technical Errors (see section 7.21.2 Error Codes) that are Message Level errors are: o XML not well formed. The document is not well formed XML (see [XML]) o XML not valid. The document is not valid XML (see [XML]) o block level technical errors (see section 4.3.3) on the Transaction Reference Block (see section 3.3) and the Signature Block only. Checks on these blocks should only be carried out if the XML is valid Note that checks on the Signature Block include checking, where possible, that each Signature Component is correctly calculated. If the Signature is incorrectly calculated then the data that should have been covered by the signature can not be trusted and must be treated as erroneous. A description of how to check a signature is correctly calculated is contained in section 6.2.4.3.3 Block Level
A Block level error indicates a problem with a block or one of its components in an IOTP message (apart from Transaction Reference or Signature Blocks). The message has been transported properly, the overall message structure and the block/component(s) including the Transaction Reference and Signature Blocks are meaningful but there is some error related to one of the other blocks. Block level errors can be either: o technical errors, or o business errors Technical Errors are further divided into: o Block Level Attribute and Element Checks, and o Block and Component Consistency Checks o Transient Technical Errors
If a technical error occurs related to a block or component, then an Error Component is generated for return.4.3.3.1 Block Level Attribute and Element Checks
Block Level Attribute and Element Checks occur only within the same block. Checks which involve cross-checking against other blocks are covered by Block and Component Consistency Checks. The Block Level Attribute & Element checks are: o checking that each attribute value within each element in a block conforms to any rules contained within this IOTP specification o checking that the content of each element conforms to any rules contained within this IOTP specification o if the previous checks are OK, then checking the consistency of attribute values and element content against other attribute values or element content within any other components in the same block.4.3.3.2 Block and Component Consistency Checks
Block and Component Consistency Checks consist of: o checking that the combination of blocks and/or components present in the IOTP Message are consistent with the rules contained within this IOTP specification o checking for consistency between attributes and element content within the blocks within the same IOTP message. o checking for consistency between attributes and elements in blocks in this IOTP message and blocks received in earlier IOTP messages for the same IOTP transaction If the block passes the "Block Level Attribute and Element Checks" and the "Block and Component Consistency Checks" then it is processed either by the IOTP Aware application or perhaps by some "back-end" system such as a payment server.4.3.3.3 Transient Technical Errors
During the processing of the Block some temporary failure may occur that can potentially be recovered by the other trading role re- transmitting, at some slightly later time, the original message that they sent. In this case the other role is informed of the Transient
Error by sending them an Error Component (see section 7.21) with the Severity Attribute set to TransientError and the MinRetrySecs attribute set to some value suitable for the Transport Mechanism and/or payment protocol being used (see appropriate Transport and payment protocol Supplements). Note that transient technical errors can be generated by any of the Trading Roles involved in transaction.4.3.3.4 Block Level Business Errors
If a business error occurs in a process such as a Payment or a Delivery, then the appropriate type of response block is returned containing a Status Component (see section 7.16) with the ProcessState attribute set to Failed and the CompletionCode indicating the nature of the problem. Some business errors may be "transient" in that the Consumer role may be able to recover and complete the transaction in some other way. For example if the Credit Card that a consumer provided had insufficient funds for a purchase, then the Consumer may recover by using a different credit card. Recovery from "transient" business errors is dependent on the CompletionCode. See the definition of the Status Component for what is possible. Note that no Error Component or Error Block is generated for business errors.4.4 Idempotency, Processing Sequence, and Message Flow
IOTP messages are actually a combination of blocks and components as described in 3.1.1 IOTP Message Structure. Especially in future extensions of IOTP, a rich variety of combinations of such blocks and components can occur. It is important that the multiple transmission/receipt of the "same" request for an action that will change state does not result in that action occurring more than once. This is called idempotency. For example, a customer paying for an order would want to pay the full amount only once. Most network transport mechanisms have some probability of delivering a message more than once or not at all, perhaps requiring retransmission. On the other hand, a request for status can reasonably be repeated and should be processed fresh each time it is received.
Correct implementation of IOTP can be modelled by a particular processing order as detailed below. Any other method that is indistinguishable in the messages sent between the parties is equally acceptable.4.5 Server Role Processing Sequence
"Server roles" are any Trading Role which is not the Consumer role. They are "Server roles" since they typically receive a request which they must service and then produce a response. However server roles can also initiate transactions. More specifically Server Roles must be able to: o Initiate a transaction (see section 4.5.1). These are divided into: - payment related transactions and - infrastructure transactions o Accept and process a message received from another role (see section 4.5.2). This includes: - identifying if the message belongs to a transaction that has been received before - handling duplicate messages - generating Transient errors if the servers that process the input message are too busy to handle it - processing the message if it is error free, authorised and, if appropriate, producing a response to send back to the other role o Cancel a current transaction if requested (see section 4.5.3) o Re-transmit messages if a response was expected but has not been received in a reasonable time (see section 4.5.4).4.5.1 Initiating Transactions
Server Roles may initiate a variety of different types of transaction. Specifically: o an Inquiry Transaction (see section 9.2.1) o a Ping Transaction (see section 9.2.2)
o an Authentication Transaction (see section 9.1.6) o a Payment Related Transaction such as: - a Deposit (see section 9.1.7) - a Purchase (see section 9.1.8) - a Refund (see section 9.1.9) - a Withdrawal (see section 9.1.10) - a Value Exchange (see section 9.1.11)4.5.2 Processing Input Messages
Processing input messages involves the following: o checking the structure and identity of the message o checking for and handling duplicate messages o processing non-duplicate original messages which includes: - checking for errors, then if no errors are found - processing the message to produce an output message if appropriate Each of these is discussed in more detail below.4.5.2.1 Checking Structure and Message Identity
It is critical to check that the message is "well formed" XML and that the transaction identifier (IotpTransId attribute on the TransId Component) within the IOTP message can be successfully identified since an IotpTransId will be needed to generate a response. If the input message is not well formed then generate an Error Component with a Severity of HardError and ErrorCode of XmlNotWellFrmd. If the message is well formed but the IotpTransId cannot be identified then generate an ErrorComponent with: o a Severity of HardError and an ErrorCode of AttMissing,
o a PackagedContent containing "IotpTransId" - the missing
attribute.
Insert the Error Component inside an Error Block with a new
TransactionId component with a new IotpTransId and return it to the
sender of the original message.
4.5.2.2 Checking/Handling Duplicate Messages
If the input message can be identified as potentially a valid input
message then check to see if an "identical" input message has been
received before. Identical means that all blocks, components,
elements, attribute values and element content in the input message
are the same.
Note: The recommended way of checking for identical messages is to
check for equal values of their [DOM-HASH]
If an identical message has been received before then check to see if
the processing of the previous message has completed.
If processing has not completed then generate an Error Component with
a Severity of Transient Error and an Error Code of MsgBeingProc to
indicate the message is being processed and send it back to the
sender of the Input Message requesting that the original message be
resent after an appropriate period of time.
Otherwise, if processing has completed and resulted in an output
message then retrieve the last message that was sent and send it
again.
If the message is not a duplicate then it should be processed.
4.5.2.3 Processing Non-Duplicate Message
Once it's been established that the message is not a duplicate, then
it can be processed. This involves:
o checking that a server is available to handle the message,
generating a Transient Error if it is not
o checking the Transaction is Not Already in error or cancelled
o validating the input message. This includes:
- checking for message level errors
- checking for block level errors
- checking any encapsulated data
o checking for errors in the sequence that blocks have been received
o generating error components for any errors that result
o if neither hard errors nor transient errors result, then
processing the message and generating an output message, if
required, for return to the sender of the Input Message
Note: This approach to handling of duplicate input messages means, if
absolutely "identical" messages are received then absolutely
"identical" messages are returned. This also applies to Inquiry and
Ping transactions when in reality the state of a transaction or the
processing ability of the servers may have changed. If up-to-date
status of transactions or servers is required, then an IOTP
transaction with a new value for the ID attribute of the MsgId
component must be used.
Each of the above steps is discussed below.
CHECKING A SERVER IS AVAILABLE
The process that is handling the input message should check that the
rest of the system is not so busy that a response in a reasonable
time cannot be produced.
If the server is too busy, then it should generate an Error Component
with a Severity of Transient Error and an Error Code of SystemBusy
and send it back to the sender of the Input Message requesting that
the original message be resent after an appropriate period of time.
Note: Some servers may occasionally become very busy due to
unexpected increases in workload. This approach allows short peaks in
workloads to be handled by delaying the input of messages by asking
the sender of the message to resubmit later.
CHECKING THE TRANSACTION IS NOT ALREADY IN ERROR OR CANCELLED
Check that:
o previous messages received or sent did not contain or result in
Hard Errors, and
o the Transaction has not been cancelled by either the Consumer or
the Server Trading Role
If it has then, ignore the message. A transaction with hard errors or
that has been cancelled, cannot be restarted.
CHECK FOR MESSAGE AND BLOCK LEVEL ERRORS
If the transaction is still OK then check for message level errors.
This involves:
o checking the XML is valid
o checking that the elements, attributes and content of the
Transaction Reference Block are without error and conform to this
specification
o checking the digital signature which involves:
- checking that the Signature value is correctly calculated, and
- the hash values in the digests are correctly calculated where
the source of the hash value is available.
Checking for block level errors involves:
o checking within each block (apart from the Transaction Reference
Block) that:
- the attributes, elements and element contents are valid
- the values of the attributes, elements and element contents are
consistent within the block
o checking that the combination of blocks are valid
o checking that the values of the attribute, elements and element
contents are consistent between the blocks in the input message
and blocks in earlier messages either sent or received. This
includes checking that the presence of a block is valid for a
particular transaction type
If the message contains any encapsulated data, then if possible check
the encapsulated data for errors using additional software to check
the data where appropriate.
4.5.2.4 Check for Errors in Block Sequence
Note: For reasons of brevity, the following explanations of how to
check for errors in Block sequence, the phrase "refers to an IOTP
transaction" is interpreted as "is contained in an IOTP Message where
the Trans Ref Block contains an IotpTransId that refers to". So, for
example, " If an Error or Cancel Block refers to an IOTP transaction
that is not recognised then ..." should be interpreted as " If an
Error or Cancel Block is contained in an IOTP Message where the Trans
Ref Block contains an IotpTransId that refers to an IOTP transaction
that is not recognised then ...
Errors in the sequence that blocks arrive depends on the block.
Blocks where checking for sequence is required are:
o Error and Cancel Blocks. If an Error or Cancel Block refers to an
IOTP transaction that is not recognised then it is a Hard Error.
Do not return an error if Error or Cancel Blocks have been
received for the IOTP Transaction before to avoid looping.
o Inquiry Request and Response Blocks. If an Inquiry Request or an
Inquiry Response Block refers to an IOTP transaction that is not
recognised then it is a Hard Error
o Authentication Request Block. If an Authentication Request Block
refers to an IOTP transaction that is recognised it is a Hard
Error
o Authentication Response Block. Check as follows:
- if an Authentication Response Block does not refer to an IOTP
transaction that is recognised it is a Hard Error, otherwise
- if the Authentication Response Block doesn't refer to an
Authentication Request that had been previously sent then it is
a Hard Error, otherwise
- if an Authentication Response for the same IOTP transaction has
been received before and the Authentication was successful then
it is a Hard Error.
o Authentication Status Block. Check as follows:
- if an Authentication Status Block does not refer to an IOTP
transaction that is recognised it is a Hard Error, otherwise
- if the Authentication Status Block doesn't refer to an
Authentication Response that had been previously sent then it
is a Hard Error, otherwise
- if an Authentication Status for the same IOTP transaction has
been received before then it is a Warning Error
o TPO Selection Block (Merchant only). Check as follows:
- if the TPO Selection Block doesn't refer to an IOTP Transaction
that is recognised then it is a Hard Error, otherwise
- if the TPO Selection Block refers to an IOTP Transaction where
a TPO Block and Offer Response (in one message) had previously
been sent then it is a Hard Error, otherwise
- if the TPO Selection Block does not refer to an IOTP
Transaction where a TPO Block only (i.e. without an Offer
Response) had previously been sent then it is a Hard Error,
otherwise
- if a TPO Selection Block for the same TPO Block has been
received before then it is a Hard Error
o Payment Request Block (Payment Handler only). Check as follows:
- if the Payment Request Block refers to an IOTP Transaction that
is not recognised then its OK, otherwise
- if the Payment Request Block refers to IOTP Transaction that
was not for a Payment then it is a Hard Error, otherwise
- if there was a previous payment that failed with a non-
recoverable Completion Code then it is a Hard Error, otherwise
- if a previous payment is still in progress then it is a Hard
Error
o Payment Exchange Block (Payment Handler only). Check as follows:
- if the Payment Exchange Block doesn't refer to an IOTP
Transaction that is recognised then it is a Hard Error,
otherwise
- if the Payment Exchange doesn't refer to an IOTP Transaction
where a Payment Exchange had previously been sent then it a
Hard Error
o Delivery Request (Delivery Handler Only). If the Delivery Request
Block refers to an IOTP Transaction that is recognised by the
Server then it is a Hard Error
If any Error Components have been generated then collect them into an
Error Block for sending to the sender of the Input message. Note that
Error Blocks should be sent back to the sender of the message and to
the ErrorLogNetLocn for the Trading Role of the sender if one is
specified.
Note: The above checking on the sequence of Authentication Responses
and Payment Requests supports the Consumer re-submitting a repeat
action request since the previous one failed, for example:
o because they did not know the correct response (e.g., a password)
on an authentication or,
o they were unable to pay as there were insufficient funds on a
credit card
PROCESS THE ERROR FREE INPUT MESSAGE
If the input message passes the previous checks then it can be
processed to produce an output message if required. Note that:
o Inquiry Requests on Ping Transactions should be ignored
o if the Input message contains an Error Block with a Transient
Error then wait for the required time then resend the previous
message, if a response to the earlier message has not been
received
o if the input message contains a Error Component with a HardError
or a Cancel Block then stop all further processing of the
transaction. This includes suppressing the sending of any messages
currently being generated or responding to any new non-duplicate
messages that are received
o processing of encapsulated messages (e.g., Payment Protocol
Messages) may result in additional transient errors
o a digital signature can only safely be generated once all the
blocks and components have been generated and it is known which
elements in the message need to be signed.
If an output message is generated then it should be saved so that it
can be resent as required if an identical input message is received
again. Note that output messages that contain transient errors are
not saved so that they can be processed afresh when the input message
is received again.
4.5.3 Cancelling a Transaction
This process is used to cancel a transaction running on an IOTP server. It is initiated by some other process as a result of an external request from another system or server that is being run by the same Trading Role. The processing required is as follows: o if the IotpTransId of the transaction to be cancelled is not recognised, or complete then fail the request, otherwise o if the IotpTransId refers to a Ping Transaction then fail the request, otherwise o determine which Document Exchange to cancel and generate a Cancel Block and send it to the other party Note: Cancelling a transaction on an IOTP server typically arises for a business reason. For example a merchant may have attempted authentication several times without success and as a result decides to cancel the transaction. Therefore the process that decides to take this action needs to send a message from the process/server that made the business decision to the IOTP server with the instruction that the IOTP transaction should be cancelled.4.5.4 Retransmitting Messages
The server should periodically check for transactions where a message is expected in return but none has been received after a time that is dependent on factors such as: o the Transport Mechanism being used; o the time required to process encapsulated messages (e.g., Payment messages) and o whether or not human input is required. If no message has been received the original message should be resent. This should occur up to a maximum number of times dependent on the reliability of the Transport Mechanism being used. If no response is received after the required time then the Transaction should be "timed out". In this case, set the process state of the transaction to Failed, and a completion code of either: o TimedOutRcvr if the transaction can potentially recovered later, or
o TimedOutNoRcvr if the transaction is non-recoverable4.6 Client Role Processing Sequence
The "Client role" in IOTP is the Consumer Trading Role. Note: A company or Organisation that is a Merchant, for example, may take on the Trading Role of a Consumer when making purchases or downloading or withdrawing electronic cash. More specifically the Consumer Role must be able to: o Initiate a transaction (see section 4.6.1). These are divided into: - payment related transactions and - infrastructure transactions o Accept and process a message received from another role (see section 4.6.2). This includes: - identifying if the message belongs to a transaction that has been received before - handling duplicate messages - generating Transient errors if the servers that process the input message are too busy to handle it - processing the message if it is error free and, if appropriate, producing a response to send back to the other role o Cancel a current transaction if requested, for example by the User (see section 4.6.3) o Re-transmit messages if a response was expected but has not been received in a reasonable time (see section 4.6.4).4.6.1 Initiating Transactions
The Consumer Role may initiate a number of different types of transaction. Specifically: o an Inquiry Transaction (see section 9.2.1) o a Ping Transaction (see section 9.2.2)
o an Authentication Transaction (see section 9.1.6)4.6.2 Processing Input Messages
Processing of Input Messages for a Consumer Role is the same as for an IOTP Server (see section 4.5.2) except in the area of checking for Errors in Block Sequence (for an IOTP Server see section 4.5.2.4). This is described below Note: The description of the processing for an IOTP Server includes consideration of multi-threading of input messages and multi-tasking of requests. For the Consumer Role - particularly if running on a stand-alone system such as a PC - use of multi-threading is a decision of the implementer of the consumer role IOTP solution.4.6.2.1 Check for Errors in Block Sequence
The handling of the following blocks is the same as for an IOTP Server (see section 4.5.2.4) except that the Consumer Role is substituted for IOTP Server Role: o Error and Cancel Blocks, o Inquiry Request and Response Blocks, o Authentication Request, Response and Status Blocks. For the other blocks a Consumer role might receive, the potential errors in the sequence that blocks arrive depends on the block. Blocks where checking for sequence is required are: o TPO Block. Check as follows: - if the input message also contains an Authentication Request block and an Offer Response Block then there is a Hard Error, otherwise - if the input message also contains an Authentication Request block and Authentication Status block then there is Hard Error otherwise, - if the input message also contains an Authentication Request block and the IOTP Transaction is recognised by the Consumer role's system, then there is a Hard Error, otherwise
- if the input message also contains an Authentication Status
block and the IOTP Transaction is not recognised by the
Consumer role's system then there is a Hard Error, otherwise
- if input message also contains an Authentication Status Block
and the Authentication Status Block has not been sent after an
earlier Authentication Response message then there is a hard
error
- if input message also contains an Offer Response Block and the
IOTP Transaction is recognised by the Consumer role's system
then there is a Hard Error, otherwise
- if the TPO Block occurs on its own and the IOTP Transaction is
recognised by the Consumer role's system then there is a Hard
Error
o Offer Response Block. Check as follows:
- if the Offer Response Block is part of a Brand Independent
Offer Exchange (see section 9.1.2.2) then there is no sequence
checking as it is part of the first message received, otherwise
- if the Offer Response Block is not part of an IOTP Transaction
that is recognised by the Consumer role then there is a Hard
Error, otherwise
- if the Offer Response Block does not refer to an IOTP
transaction where a TPO Selection Block was the last message
sent then there is a Hard Error
o Payment Exchange Block. Check as follows:
- if the Payment Exchange Block doesn't refer to an IOTP
Transaction that is recognised by the Consumer role's system
then there is a Hard Error, otherwise
- if the Payment Exchange doesn't refer to an IOTP Transaction
where either a Payment Request or a Payment Exchange block was
most recently sent then there is a Hard Error
o Payment Response Block. Check as follows:
- if the Payment Response Block doesn't refer to an IOTP
Transaction that is recognised by the Consumer role's system
then there is a Hard Error, otherwise
- if the Payment Response doesn't refer to an IOTOP Transaction
where either a Payment Request or a Payment Exchange block was
most recently sent then there is a Hard Error
o Delivery Response Block. Check as follows:
- if the Delivery Response Block doesn't refer to an IOTP
Transaction that is recognised by the Consumer role's system
then there is a Hard Error, otherwise
- If the Delivery Response doesn't refer to an IOTP Transaction
where either a Payment Request or a Payment Exchange block was
most recently sent then there is a Hard Error
4.6.3 Cancelling a Transaction
This process cancels a current transaction on an Consumer role's
system as a result of an external request from the user, or another
system or server in the Consumer's role. The processing is the same
as for an IOTP Server (see section 4.5.3).
4.6.4 Retransmitting Messages
The process of retransmitting messages is the same as for an IOTP
Server (see section 4.5.4).
5. Security Considerations
This section considers, from an IETF perspective how IOTP addresses
security. The next section (see section 6. Digital Signatures and
IOTP) describes how IOTP uses Digital Signatures when these are
needed.
This section covers:
o determining whether to use digital signatures
o data privacy, and
o payment protocol security.
5.1 Determining whether to use digital signatures
The use of digital signatures within IOTP are entirely optional. IOTP
can work successfully entirely without the use of digital signatures.
Ultimately it is up to the Merchant, or other trading role, to decide
whether IOTP Messages will include signatures, and for the Consumer
to decide whether carrying out a transaction without signatures is an
acceptable risk. If Merchants discover that transactions without
signatures are not being accepted, then they will either:
o start using signatures,
o find a method of working which does not need signatures, or
o accept a lower volume and value of business.
A non-exhaustive list of the reasons why digital signatures might be
used follows:
o the Merchant (or other trading role) wants to demonstrate that
they can be trusted. If, for example, a merchant generates an
Offer Response Signature (see section 7.19.2) using a certificate
from a trusted third party, known to the Consumer, then the
Consumer can check the signature and certificate and so more
reasonably rely on the offer being from the actual Organisation
the Merchant claims to be. In this case signatures using
asymmetric cryptography are likely to be required
o the Merchant, or other Trading Role, want to generate a record of
the transaction that is fit for a particular purpose. For example,
with appropriate trust hierarchies, digital signatures could be
checked by the Consumer to determine:
- if it would be accepted by tax authorities as a valid record of
a transaction, or
- if some warranty, for example from a "Better Business Bureau"
orsimilar was being provided
o the Payment Handler, or Delivery Handler, needs to know that the
request is unaltered and authorised. For example, in IOTP, details
of how much to pay is sent to the Consumer in the Offer Response
and then forwarded to the Payment Handler in a Payment Request. If
the request is not signed, the Consumer could change the amount
due by, for example, removing a digit. If the Payment Handler has
no access to the original payment information in the Offer
Response, then, without signatures, the Payment Handler cannot be
sure that the data has not been altered. Similarly, if the payment
information is not digitally signed, the Payment Handler cannot be
sure who is the Merchant that is requesting the payment
o a Payment Handler or Delivery Handler wants to provide a non-
refutable record of the completion status of a Payment or
Delivery. If a Payment Response or Delivery Response is signed,
then the Consumer can later use the record of the Payment or
Delivery to prove that it occurred. This could be used, for
example, for customer care purposes.
A non-exhaustive list of the reasons why digital signatures might not
be used follows:
o trading roles are combined therefore changes to data made by the
consumer can be detected. One of the reasons for using signatures
is so that one trading role can determine if data has been changed
by the Consumer or some other party. However if the trading roles
have access to the necessary data, then it might be possible to
compare, for example, the payment information in the Payment
Request with the payment information in the Offer Response. Access
to the data necessary could be realised by, for example, the
Merchant and Payment Handler roles being carried out by the same
Organisation on the same system, or the Merchant and Payment
Handler roles being carried out on different systems but the
systems can communicate in some way. (Note this type of
communication is outside the current scope of IOTP)
o the processing cost of the cryptography is too high. For example,
if a payment is being made of only a few cents, the cost of
carrying out all the cryptography associated with generating and
checking digital signatures might make the whole transaction
uneconomic. Co-locating trading roles, could help avoid this
problem.
5.2 Symmetric and Asymmetric Cryptography
The advantage of using symmetric keys with IOTP is that no Public Key
Infrastructure need be set up and just the Merchant, Payment Handler
and Delivery Handler need to agree on the shared secrets to use.
However the disadvantage of symmetric cryptography is that the
Consumer cannot easily check the credentials of the Merchant, Payment
Handler, etc. that they are dealing with. This is likely to reduce,
somewhat, the trust that the Consumer will have carrying out the
transaction.
However it should be noted that even if asymmetric cryptography is
being used, the Consumer does not NEED to be provided with any
digital certificates as the integrity of the transaction is
determined by, for example, the Payment Handler checking the Offer
Response Signature copied to the Payment Request.
Note that symmetric, asymmetric or both types of cryptography may be
used in a single transaction.
5.3 Data Privacy
Privacy of information is provided by sending IOTP Messages between the various Trading Roles using a secure channel such as [SSL/TLS]. Use of a secure channel within IOTP is optional.5.4 Payment Protocol Security
IOTP is designed to be completely blind to the payment protocol being used to effect a payment. From the security perspective, this means that IOTP neither helps, nor hinders, the achievement of payment security. If it is necessary to consider payment security from an IOTP perspective, then this should be included in the payment protocol supplement which describes how IOTP supports that payment protocol. However what IOTP is designed to do is to use digital signatures to bind together the record, contained in a "response" message, of each trading exchange in a transaction. For example IOTP can bind together: an Offer, a Payment and a Delivery.6. Digital Signatures and IOTP
IOTP can work successfully without using any digital signatures although in an open networking environment it will be less secure - see 5. Security Considerations for a description of the factors that need to be considered. However, this section describes how to use digital signatures in the many situations when they will be needed. Topics covered are: o an overview of how IOTP uses digital signatures o how to check a signature is correctly calculated o how Payment Handlers and Delivery Handlers check they can carry out payments or deliveries on behalf of a Merchant.6.1 How IOTP uses Digital Signatures
In general, signatures when used with IOTP: o are always treated as IOTP Components (see section 7) o contain digests of one or more IOTP Components or Trading Blocks, possibly including other Signature Components, in any IOTP message within the same IOTP Transaction
o identify:
- which Organisation signed (originated) the signature, and
- which Organisation(s) should process the signature in order to
check that the Action the Organisation should take can occur.
Digital certificates may be associated with digital signatures if
asymmetric cryptography is being used. However if symmetric
cryptography is being used, then the digital certificate will be
replaced by some identifier of the secret key to use.
The way in which Signatures Components digest one or more elements is
illustrated in the figure below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
IOTP MESSAGE SIGNATURE COMPONENT
IOTP Message Signature Id = P1.3
|-Trans Ref Block digest TransRefBlk |-Manifest
| | ID=P1.1-----------------------------|->|-Digest of P1.1--
| |-Trans Id Comp digest TransIdComp | | |
| | ID = M1.2----------------------------|->|-Digest of M1.2--|
| |-Msg Id Comp. digest Signature | | |
| | ID = P1 -------------------|->|-Digest of M1.5--|
| | digest element | | |
|-Signatures Block | -----------------|->|-Digest of M1.7--|
| | ID=P1.2 | | digest element | | |
| |-Signature ID=P1.3 | | ---------------|->|-Digest of C1.4--|
| |-Signature ID=M1.5---- | | | | |
| |-Signature ID=P1.4 | | Points to | -RecipientInfo* |
| |-Certificate ID=M1.6<---|-|---------------|------CertRef=M1.6 |
| | | | Certs to use | Sig.ValueRef=P1.4 |
| | | | | | |
| | | | | | |
|-Trading Block. ID=P1.5 | | | v |
| |-Comp. ID=M1.7---------- | -Value* ID=P1.4: |
| | | JtvwpMdmSfMbhK<--
| |-Comp. ID=P1.6 | r1Ln3vovbMQttbBI
| | | J8pxLjoSRfe1o6k
| |-Comp. ID=C1.4------------ OGG7nTFzTi+/0<-
| |-Comp. ID=C1.5
Digital signature of Manifest element
using certificate identified by CertRef
Elements that are digested can be in any IOTP Message
within the same IOTP Transaction
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 10 Signature Digests
Note: The classic example of one signature signing another in IOTP, is when an Offer is first signed by a Merchant creating an "Offer Response" signature, which is then later signed by a Payment Handler together with a record of the payment creating a "Payment Receipt" signature. In this way, the payment in an IOTP Transaction is bound to the Merchant's offer. Note that one Manifest may be associated with multiple signature "Value" elements where each Value element contains a digital signature over the same Manifest, perhaps using the same (or different) signature algorithm but using a different certificate or shared secret key. Specifically it will allow the Merchant to agree on different shared secrets keys with their Payment Handler and Delivery Handler. The detailed definitions of a Signature component are contained in section 7.19. The remainder of this section contains: o an example of how IOTP uses signatures o how the OriginatorInfo and RecipientInfo elements within a Signature Component are used to identify the Organisations associated with the signature o how IOTP uses signatures to prove actions complete successfully6.1.1 IOTP Signature Example
An example of how signatures are used is illustrated in the figure below which shows how the various components and elements in a Baseline Purchase relate to one another. Refer to this example in the later description of how signatures are used to check a payment or delivery can occur (see section 6.3). Note: A Baseline Purchase transaction has been used for illustration purposes. The usage of the elements and attributes is the same for all types of IOTP Transactions.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
TPO SELECTION BLOCK TPO BLOCK IOTPSIGNATURE BLOCK
| (Offer Response)
Brand Selection Organisation<--- |------Signature
Component Component | | Component
| | | -Manifest
|BrandList -Trading Role | |
| Ref Element | Originator |-Orig.
v (Merchant) ------------|--Info
Brand List Ref |
>Component |
| |-Protocol ------> Organisation Recipient |-Recipient
| | Amount Elem | Component <------------------|--Info
| | | | | Refs |
| |Pay|Protocol |Action -Trading Role |
| | | Ref |OrgRef Element |
| | v | (Payment Handler) |
| -PayProtocol-- |
| Elem ->Organisation Recipient |-Recipient
| | Component <--------------------Info
| | | Refs
| | -Trading Role
| | Element
| | (Delivery Handler
|
| OFFER RESPONSE BLOCK
| |
|BrandListRef |ActionOrgRef
| |
--Payment ---Delivery
Component Component
The Manifest element in the Signature Component contains digests of:
the Trans Ref Block (not shown); the Transaction ID Component (not
shown); Organisation Components (Merchant, Payment Handler, Delivery
Handler); the Brand List Component; the Order Component, the Payment
Component the Delivery Component and the Brand Selection Component (if a
Brand Dependent Purchase).
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 11 Example use of Signatures for Baseline Purchase
6.1.2 OriginatorInfo and RecipientInfo Elements
The OriginatorRef attribute of the OriginatorInfo element in the Signature Component contains an Element Reference (see section 3.5) that points to the Organisation Component of the Organisation which generated the Signature. In this example its the Merchant. Note that the value of the content of the Attribute element with a Type attribute set to IOTP Signature Type must match the Trading Role of the Organisation which signed it. If it does not, then it is an error. Valid combinations are given in the table below. IOTP Signature Type Valid Trading Role OfferResponse Merchant PaymentResponse PaymentHandler DeliveryResponse DeliveryHandler AuthenticationRequest any role AuthenticationResponse any role PingRequest any role PingResponse any role The RecipientRefs attribute of the RecipientInfo element in the Signature Component contains Element References to the Organisation Components of the Organisations that should use the signature to verify that: o they have a pre-existing relationship with the Organisation that generated the signature, o the data which is secured by the signature has not been changed, o the data has been signed correctly, and o the action they are required to undertake on behalf of the Merchant is therefore authorised. Note that if symmetric cryptography is being used then a separate RecipientInfo and Value elements for each different set of shared secret keys are likely within the Signature Component.
Alternatively if asymmetric cryptography is being used then the RecpientRefs attribute of one RecipientInfo element may refer to multiple Organisation Components if they are all using the same certificates.6.1.3 Using signatures to Prove Actions Complete Successfully
Proving an action completed successfully, is achieved by signing data on Response messages. Specifically: o on the Offer Response, when a Merchant is making an Offer to the Consumer which can then be sent to either: - a Payment Handler to prove that the Merchant authorises Payment, or - a Delivery Handler to prove that Merchant authorises Delivery, provided other necessary authorisations are complete (see below) o on the Payment Response, when a Payment Handler is generating a Payment Receipt which can be sent to either: - a Delivery Handler, in a Delivery Request Block to authorise Delivery together with the Offer Response signature, or - another Payment Handler, in a second Payment Request, to authorise the second payment in a Value Exchange IOTP Transaction o Delivery Response, when a Delivery Handler is generating a Delivery Note. This can be used to prove after the event what the Delivery Handler said they would do o Authentication Response. One method of authenticating another party to a trade is to send an Authentication Request specifying that a Digital Signature should be used for authentication o Transaction Status Inquiry. The Inquiry Response Block may be digitally signed to attest to the authenticity of the response o Ping. The Ping Response may be digitally signed so that checks can be made that the signature can be understood. This proof of an action may, in future versions of IOTP, also be used to prove after the event that the IOTP transaction occurred. For example to a Customer Care Provider.
6.2 Checking a Signature is Correctly Calculated
Checking a signature is correctly calculated is part of checking for Message Level Errors (see section 4.3.2). It is included here so that all signature and security related considerations are kept together. Before a Trading Role can check a signature it must identify which of the potentially multiple Signature elements should be checked. The steps involved are as follows: o check that a Signature Block is present and it contains one or more Signature Components o identify the Organisation Component which contains an OrgId attribute for the Organisation which is carrying out the signature check. If no or more than one Organisation Component is found then it is an error o use the ID attribute of the Organisation Component to find the RecipientInfo element that contains a RecipientRefs attribute that refers to that Organisation Component. Note there may be no signatures to verify o check the Signature Component that contains the identified RecipientInfo element as follows: - use the SignatureValueRef and the SignatureAlgorithmRef attributes to identify, respectively: the Value element that contains the signature to be checked and the Signature Algorithm element that describes the signature algorithm to be used to verify the Signature, then - if the Signature Algorithm element indicates that asymmetric cryptography is being used then use the SignatureCertRef to identify the Certificate to be used by the signature algorithm - if Signature Algorithm element indicates that symmetric cryptography is being used then the content of the RecipientInfo element is used to identify the correct shared secret key to use - use the specified signature algorithm to check that the Value Element correctly signs the Manifest Element - check that the Digest Elements in the Manifest Element are correctly calculated where Components or Blocks referenced by the Digest have been received by the Organisation checking the signature.
6.3 Checking a Payment or Delivery can occur
This section describes the processes required for a Payment Handler or Delivery Handler to check that a payment or delivery can occur. This may include checking signatures if this is specified by the Merchant. In outline the steps are: o check that the Payment Request or Delivery Request has been sent to the correct Organisation o check that correct IOTP components are present in the request, and o check that the payment or delivery is authorised For clarity and brevity the following terms or phrases are used in this section: o a "Request Block" is used to refer to either a Payment Request Block (see section 8.7) or a Delivery Request Block (see section 8.10) unless specified to the contrary o a "Response Block" is used to refer to either a Payment Response Block (see section 8.9) or a Delivery Response Block (see section 8.11) o an "Action" is used to refer to an action which occurs on receipt of a Request Block. Actions can be either a Payment or a Delivery o an "Action Organisation", is used to refer to the Payment Handler or Delivery Handler that carries out an Action o a "Signer of an Action", is used to refer to the Organisations that sign data about an Action to authorise the Action, either in whole or in part o a "Verifier of an Action", is used to refer to the Organisations that verify data to determine if they are authorised to carry out the Action o an ActionOrgRef attribute contains Element References which can be used to identify the "Action Organisation" that should carry out an Action
6.3.1 Check Request Block sent Correct Organisation
Checking the Request Block was sent to the correct Organisation varies depending on whether the request refers to a Payment or a Delivery.6.3.1.1 Payment
In outline a Payment Handler checks if it can accept or make a payment by identifying the Payment Component in the Payment Request Block it has received, then using the ID of the Payment Component to track through the Brand List and Brand Selection Components to identify the Organisation selected by the Consumer and then checking that this Organisation is itself.
The way data is accessed to do this is illustrated in the figure
below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Start
|
v
Brand List<--------------------------+-----------Payment
Component BrandListRef | Component
| |
|-Brand<-------------------------- |
| Element BrandRef | |
| | Brand Selection
| |Protocol Component
| | AmountRefs | |
| v Protocol | |
|-Protocol Amount<---------------- |
| Element---------- AmountRef |
| | | |
| |Currency |Pay |
| | AmountRefs |Protocol |
| v |Ref |
|-Currency Amount | |
| Element<---------|----------------
| |
-PayProtocol<-----
Element---------------------->Organisation
Action Component
OrgRef |
-Trading Role
Element
(Payment Handler)
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 12 Checking a Payment Handler can carry out a Payment
The following describes the steps involved and the checks which need
to be made:
o Identify the Payment Component (see section 7.9) in the Payment
Request Block that was received.
o Identify the Brand List and Brand Selection Components for the
Payment Component. This involves:
- identifying the Brand List Component (see section 7.7) where
the value of its ID attribute matches the BrandListRef
attribute of the Payment Component. If no or more than one
Brand List Component is found there is an error.
- identifying the Brand Selection Component (see section 7.8)
where the value of its BrandListRef attribute matches the
BrandListRef of the Payment Component. If no or more than one
matching Brand Selection Component is found there is an error.
o Identify the Brand, Protocol Amount, Pay Protocol and Currency
Amount elements within the Brand List that have been selected by
the Consumer as follows:
- the Brand Element (see section 7.7.1) selected is the element
where the value of its Id attribute matches the value of the
BrandRef attribute in the Brand Selection. If no or more than
one matching Brand Element is found then there is an error.
- the Protocol Amount Element (see section 7.7.3) selected is the
element where the value of its Id attribute matches the value
of the ProtocolAmountRef attribute in the Brand Selection
Component. If no or more than one matching Protocol Amount
Element is found there is an error
- the Pay Protocol Element (see section 7.7.5) selected is the
element where the value of its Id attribute matches the value
of the PayProtocolRef attribute in the identified Protocol
Amount Element. If no or more than one matching Pay Protocol
Element is found there is an error
- the Currency Amount Element (see section 7.7.4) selected is the
element where the value of its Id attribute matches the value
of the CurrencyAmountRef attribute in the Brand Selection
Component. If no or more than one matching Currency Amount
element is found there is an error
o Check the consistency of the references in the Brand List and
Brand Selection Components:
- check that an Element Reference exists in the
ProtocolAmountRefs attribute of the identified Brand Element
that matches the Id attribute of the identified Protocol Amount
Element. If no or more than one matching Element Reference can
be found there is an error
- check that the CurrencyAmountRefs attribute of the identified
Protocol Amount element contains an element reference that
matches the Id attribute of the identified Currency Amount
element. If no or more than one matching Element Reference is
found there is an error.
- check the consistency of the elements in the Brand List.
Specifically, the selected Brand, Protocol Amount, Pay Protocol
and Currency Amount Elements are all child elements of the
identified Brand List Component. If they are not there is an
error.
o Check that the Payment Handler that received the Payment Request
Block is the Payment Handler selected by the Consumer. This
involves:
- identifying the Organisation Component for the Payment Handler.
This is the Organisation Component where its ID attribute
matches the ActionOrgRef attribute in the identified Pay
Protocol Element. If no or more than one matching Organisation
Component is found there is an error
- checking the Organisation Component has a Trading Role Element
with a Role attribute of PaymentHandler. If not there is an
error
- finally, if the identified Organisation Component is not the
same as the Organisation that received the Payment Request
Block, then there is an error.
6.3.1.2 Delivery
The way data is accessed by a Delivery Handler in order to check that it may carry out a delivery is illustrated in the figure below. *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* Start | v Delivery Component | |ActionOrgRef | v Organisation Component | -Trading Role Element (Delivery Handler) *-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-* Figure 13 Checking a Delivery Handler can carry out a Delivery The steps involved are as follows: o Identify the Delivery Component in the Delivery Request Block. If there is no or more than one matching Delivery Component there is an error o Use the ActionOrgRef attribute of the Delivery Component to identify the Organisation Component of the Delivery Handler. If there is no or more than one matching Organisation Component there is an error o If the Organisation Component for the Delivery Handler does not have a Trading Role Element with a Role attribute of DeliveryHandler there is an error o Finally, if the Organisation that received the Delivery Request Block does not identify the Organisation Component for the Delivery Handler as itself, then there is an error.
6.3.2 Check Correct Components present in Request Block
Check that the correct components are present in the Payment Request Block (see section 8.7) or in the Delivery Request Block (see section 8.10). If components are missing, there is an error.6.3.3 Check an Action is Authorised
The previous steps identified the Action Organisation and that all the necessary components are present. This step checks that the Action Organisation is authorised to carry out the Action. In outline the Action Organisation will identifies the Merchant, checks that it has a pre-existing agreement with the Merchant that allows it carry out the Action and that any constraints implied by that agreement are being followed, then, if signatures are required, it checks that they sign the correct data. The steps involved are as follows: o Identify the Merchant. This is the Organisation Component with a Trading Role Element which has a Role attribute with a value of Merchant. If no or more than one Trading Role Element is found, there is an error o Check the Action Organisation's agreements with the Merchant allows the Action to be carried out. To do this the Action Organisation must check that: - the Merchant is known and a pre-existing agreement exists for the Action Organisation to be their agent for the payment or delivery - they are allowed to take part in the type of IOTP transaction that is occurring. For example a Payment Handler may have agreed to accept payments as part of a Baseline Purchase, but not make payments as part of a Baseline Refund - any constraints in their agreement with the Merchant are being followed, for example, whether or not an Offer Response signature is required o Check the signatures are correct. If signatures are required then they need to be checked. This involves:
- Identifying the correct signatures to check. This involves the
Action Organisation identifying the Signature Components that
contain references to the Action Organisation (see 6.3.1).
Depending on the IOTP Transaction being carried out (see
section 9) either one or two signatures may be identified
- checking that the Signature Components are correct. This
involves checking that Digest elements exist within the
Manifest Element that refer to the necessary Trading Components
(see section 6.3.3.1).
6.3.3.1 Check the Signatures Digests are correct
All Signature Components contained within IOTP Messages must include
Digest elements that refer to:
o the Transaction Id Component (see section 3.3.1) of the IOTP
message that contains the Signature Component. This binds the
globally unique IotpTransId to other components which make up the
IOTP Transaction
o the Transaction Reference Block (see section 3.3) of the first
IOTP Message that contained the signature. This binds the
IotpTransId with information about the IOTP Message contained
inside the Message Id Component (see section 3.3.2).
Check that each Signature Component contains Digest elements that
refer to the correct data required.
The Digest elements that need to be present depend on the Trading
Role of the Organisation which generated (signed) the signature:
o if the signer of the signature is a Merchant then:
- Digest elements must be present for all the components in the
Request Block apart from the Brand Selection Component which is
optional
o if the signer of the signature is a Payment Handler then Digest
elements must be present for:
- the Signature Component signed by the Merchant, and optionally
- one or more Signature Components signed by the previous Payment
Handler(s) in the Transaction.
(next page on part 4)