[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
AS3 Discusion - Section 7 - Structure and Processing of an MDN Message
Open for discussion
7. Structure and Processing of an MDN Message
7.1 Introduction
In order to support non-repudiation of receipt, a signed receipt,
based on digitally signing a message disposition notification, is to
be implemented by a receiving trading partner's UA. The message
disposition notification specified by RFC 2298 is digitally signed by
a receiving trading partner as part of a multipart/signed MIME
message.
The following support for signed receipts is REQUIRED:
1) The ability to create a multipart/report;
where the report-type = disposition-notification.
2) The ability to calculate a message integrity check (MIC) on the
received message. The calculated MIC value will be returned to the
sender of the message inside the signed receipt.
3) The ability to create a multipart/signed content with the message
disposition notification as the first body part, and the signature
as the second body part.
4) The ability to return the signed receipt to the sending trading
partner.
The signed receipt is used to notify a sending trading partner that
requested the signed receipt that:
1) The receiving trading partner acknowledges receipt of the sent EC
Interchange.
2) If the sent message was signed, then the receiving trading partner
Harding, Scott [Page 13]
INTERNET DRAFT FTP Transport Data for EDIINT April 2005
has authenticated the sender of the EC Interchange.
3) If the sent message was signed, then the receiving trading partner
has verified the integrity of the sent EC Interchange.
Regardless of whether the EDI/EC Interchange was sent in S/MIME
format
or not, the receiving trading partner's UA MUST provide the following
basic processing:
1) If the sent EDI/EC Interchange is encrypted, then the encrypted
symmetric key and initialization vector (if applicable) is
decrypted using the receiver's private key.
2) The decrypted symmetric encryption key is then used to decrypt the
EDI/EC Interchange.
3) The receiving trading partner authenticates signatures in a
message
using the sender's public key.
The authentication algorithm performs the following:
a) The message integrity check (MIC or Message Digest), is
decrypted
using the sender's public key.
b) A MIC on the signed contents (the MIME header and encoded EDI
object, as per RFC 1767) in the message received is calculated
using the same one-way hash function that the sending trading
partner used.
c) The MIC extracted from the message that was sent, and the MIC
calculated using the same one-way hash function that the
sending
trading partner used is compared for equality.
4) The receiving trading partner formats the MDN and sets the
calculated MIC into the "Received-content-MIC" extension field.
5) The receiving trading partner creates a multipart/signed MIME
message according to RFC 1847.
6) The MDN is the first part of the multipart/signed message, and the
digital signature is created over this MDN, including its MIME
headers.
7) The second part of the multipart/signed message contains the
digital signature. The "protocol" option specified in the second
part of the multipart/signed is as follows: S/MIME:
protocol = "application/pkcs7-signature"
8) The signature information is formatted according to S/MIME
specifications. The EC Interchange and the RFC 1767 MIME EDI
content header can actually be part of a multi-part MIME
content-type. When the EDI Interchange is part of a multi-part
MIME content-type, the MIC MUST be calculated across the entire
multi-part content, including the MIME headers.
The signed MDN, when received by the sender of the EDI Interchange
can
Harding, Scott [Page 14]
INTERNET DRAFT FTP Transport Data for EDIINT April 2005
be used by the sender:
1) As an acknowledgment that the EDI Interchange sent, was delivered
and acknowledged by the receiving trading partner. The receiver
does this by returning the original-message-id of the sent message
in the MDN portion of the signed receipt.
2) As an acknowledgment that the integrity of the EDI Interchange was
verified by the receiving trading partner. The receiver does this
by returning the calculated MIC of the received EC Interchange
(and 1767 MIME headers) in the "Received-content-MIC" field of the
signed MDN.
3) As an acknowledgment that the receiving trading partner has
authenticated the sender of the EDI Interchange.
4) As a non-repudiation of receipt when the signed MDN is
successfully
verified by the sender with the receiving trading partner's public
key and the returned MIC value inside the MDN is the same as the
digest of the original message.
7.2 Message Disposition Notifications (MDN)
The AS3-MDNs are returned on a separate FTP TCP/IP
connection and are a response to an AS3 message.
The following diagram illustrates the delivery of an
AS3-MDN delivery:
AS3-MDN
[S] ----( connect )----> [R] [FTP Server]
[S] ----( send )-------> [R] [AS3-Message]
[S] ----( disconnect )-> [R] [FTP Server]
[S] <---( connect )----- [R] [FTP Server]
[S] <---( send )-------- [R] [AS3-MDN]]
[S] <---( disconnect )-- [R] [FTP Server]
7.3 Requesting a signed receipt
Message Disposition Notifications are requested as per RFC 2298. A
request that the receiving user agent issue a message disposition
notification is made by placing the following header into the message
to be sent:
MDN-request-header = "Disposition-notification-to" ":" ftp-url
This syntax is a residual of the use of MDN's in a SMTP transfer.
Since
this specification is adjusting the functionality from SMTP to FTP
and
retaining as much as possible from the [5] functionality, the
ftp-url must be present.
The ftp-url field is specified as an RFC 1738
<URL:ftp://host.com:port/url-path>, and while it MUST be present,
it may be ignored if the ftp-url points to an unknown location. If
the
Harding, Scott [Page 15]
INTERNET DRAFT FTP Transport Data for EDIINT April 2005
ftp-url points to an unknown location it is RECOMMENDED that the mdn
is
returned back to a known ftp-url for the sender of the received
message.
For requesting MDN based receipts, the originator supplies the
required
extension headers that precede the message body.
The header "tags" are as follows:
A Disposition-notification-to header is added to indicate that a
message
disposition notification is requested. This header is specified in
[6].
A Message-ID header is added to support message reconciliation, so
that
an Original-Message-Id value can be returned in the body part of MDN.
Other headers, especially "Date", SHOULD be supplied; the
values of these headers are often mentioned in the human-readable
section of a MDN to aid in identifying the original message.
Disposition-notification-options identifies characteristics of
message
Disposition notification in accordance with [6].
EXAMPLE:
Disposition-notification-to: // Requests the MDN
ftp://host:port/inbox // Location to return MDN
Disposition-notification-options: // The signing options for
MDN
signed-receipt-protocol=optional, pkcs7-signature;
signed-receipt-micalg=optional, sha1, md5
Disposition-notification-options syntax:
Disposition-notification-options =
"Disposition-Notification-Options" ":"
disposition-notification-parameters
where
disposition-notification-parameters =
parameter *(";" parameter)
where
parameter = attribute "=" importance ", " 1#value"
where
importance = "required" | "optional"
So the Disposition-notification-options string could be:
signed-receipt-protocol=optional, <protocol symbol>;
signed-receipt-micalg=optional, <micalg1>, <micalg2>,...;
The currently supported value for <protocol symbol> is
"pkcs7-signature"
for the S/MIME detached signature format.
Harding, Scott [Page 16]
INTERNET DRAFT FTP Transport Data for EDIINT April 2005
The currently supported values for MIC algorithm <micalg> values are:
Algorithm Value
Used
-------- -------
MD5 md5
SHA-1 sha1
Receiving agents SHOULD be able to recover gracefully from a <micalg>
parameter value that they do not recognize.
The semantics of the "signed-receipt-protocol" parameter is as
follows:
1) The "signed-receipt-protocol" parameter is used to request a
signed
receipt from the recipient trading partner. The
"signed-receipt-protocol" parameter also specifies the format in
which the signed receipt should be returned to the requester.
The "signed-receipt-micalg" parameter is a list of MIC algorithms
preferred by the requester for use in signing the returned receipt
and calculating the micalg in the Received-content-MIC header.
The list of MIC algorithms should be honored by the recipient from
left to right. Both the "signed-receipt-protocol" and the
"signed-receipt-micalg" option parameters are REQUIRED when
requesting a signed receipt.
2) The "importance" attribute of "Optional" is defined in the RFC
2298
section 2.2 and has the following meaning:
Parameters with an importance of "Optional" permit a UA that does
not
understand the particular options parameter to still generate a
MDN
in response to a request for a MDN. A UA that does not understand
the
"signed-receipt-protocol" parameter, or the
"signed-receipt-micalg"
will obviously not return a signed receipt.
The importance of "Optional" is used for the signed receipt
parameters because it is RECOMMENDED that an MDN be returned to
the
requesting trading partner even if the recipient could not sign
it.
The returned MDN will contain information on the disposition of
the
message as well as why the MDN could not be signed. See the
Disposition field in section 7.5 for more information.
Within an EDI trading relationship, if a signed receipt is expected
and is not returned, then the validity of the transaction must be
determined by the trading partners. Typically, if a signed receipt
is
required by the trading relationship and is not received, the
transaction will likely not be considered valid.
7.3.1 Signed Receipt Considerations
The method used to request a receipt or a signed receipt is defined
in
RFC 2298, "An Extensible Message Format for Message Disposition
Notifications".
Harding, Scott [Page 17]
INTERNET DRAFT FTP Transport Data for EDIINT April 2005
The "rules" for processing a receipt-request follow:
1) When a receipt is requested, explicitly specifying that the receipt
be
signed, then the receipt MUST be returned with a signature unless
conditions (2) or (3) below are applicable.
2) When a receipt is requested, explicitly specifying that the receipt
be
signed, but the recipient cannot support either the requested
protocol
format, or requested MIC algorithms, then either a signed or unsigned
receipt SHOULD be returned.
3) When a receipt is requested, explicitly specifying that the receipt
be
signed, but the recipient is unable to compute the digest (e.g.,
message
was encrypted and recipient unable to decrypt), then the recipient
SHOULD
NOT return "Received-Content-MIC" in the MDN to the requestor. If
the
MDN sets the disposition (e.g., "processed/error: decryption-failed")
appropriately, then the "Received-Content-MIC" may be returned but
the
value must be discarded.
4) When a signature is not explicitly requested, or if the signed
receipt
request parameter is not recognized by the UA, then no receipt, an
unsigned receipt, or a signed receipt MAY be returned by the
recipient.
5) If a message is received without a request for a receipt, then a
receipt
(signed or unsigned) MAY be returned.
The "Received-content-MIC" MUST be calculated as follows:
- For any signed messages, the MIC to be returned is calculated on
the RFC1767 MIME header and content. Canonicalization as specified
in RFC 1848 MUST be performed before the MIC is calculated, since
the sender requesting the signed receipt was also REQUIRED to
canonicalize.
- For encrypted, unsigned messages, the MIC to be returned is
calculated on the decrypted RFC 1767 MIME header and content. The
content after decryption MUST be canonicalized before the MIC is
calculated.
- For unsigned, unencrypted messages, the MIC MUST be calculated
over the message contents prior to Content-Tranfer-Encoding and
without the MIME or any other RFC 822 headers, since these are
sometimes altered or reordered by MTAs.
7.4 MDN Format and value
This section defines the format of the AS3 Message Disposition
Notification (AS3-MDN).
7.4.1 AS3-MDN General Formats
The AS3-MDN follows the MDN specification [6] except where noted in
this section. The modified entity definitions in this document use
the vertical-bar character, '|', to denote a logical "OR"
construction. Refer to RFC 2045 for format of MIME-message-headers.
Harding, Scott [Page 18]
INTERNET DRAFT FTP Transport Data for EDIINT April 2005
The format of the AS3-MDN is
AS3-MDN = *(( MIME-message-headers | entity-headers )CRLF)
CRLF
AS3-MDN-body
AS3-MDN-body =
AS3-signed-MDN-body | AS3-unsigned-MDN-body
7.4.2 AS3-MDN Construction
The AS3-MDN-body is formatted as a MIME multipart/report with a
report-type of "disposition-notification".
When unsigned, the transfer-layer ( "outermost" ) entity-headers of
the AS3-MDN contain the content-type header that specifies a
content-type of "multipart/report" and parameters indicating the
report-type, and the value of the outermost multipart boundary.
When the AS3-MDN is signed, the transfer-layer ( "outermost" )
entity-headers of the AS3-MDN contain a content-type header that
specifies a content-type of "multipart/signed" and parameters
indicating the algorithm used to compute the message digest, the
signature formatting protocol ( e.g. pkcs7-signature ), and the
value of the outermost multipart boundary. The first part of the
MIME multipart/signed message is an embedded MIME multipart/report
of type "disposition-notification". The second part of the
multipart/signed message contains a MIME
application/pkcs7-signature
message.
The first part of the MIME multipart/report is a "human-readable"
portion that contains a general description of the message
disposition. The second part of the MIME multipart/report is a
"machine-readable" portion that is defined as
AS3-disposition-notification-content =
[ reporting-ua-field CRLF ]
[ mdn-gateway-field CRLF ]
[ original-recipient-field CRLF ]
final-recipient-field CRLF
[ original-message-id-field CRLF ]
AS3-disposition-field CRLF
*( failure-field CRLF )
*( error-field CRLF )
*( warning-field CRLF )
*( extension-field CRLF )
[ AS3-received-content-MIC-field CRLF ]
It is noted that several of the optional fields defined by RFC 2298
and shown above are not relevant to a point-to-point transport such
as FTP and would not normally appear in an AS3 MDN.
7.4.3 AS3-MDN Fields
The rules for constructing the AS3-disposition-notification-content
Harding, Scott [Page 19]
INTERNET DRAFT FTP Transport Data for EDIINT April 2005
are identical to the rules for constructing the
disposition-notification-content as defined in section 7 of RFC
2298 [6] except that the RFC 2298 disposition-field has
been replaced with the AS3-disposition-field and that the
AS3-received-content-MIC field has been added. The differences
between the RFC 2298 disposition-field and the
AS3-disposition-field are described below. Where
there are differences between this document and RFC 2298, those
entity names have been changed by prepending "AS3-". Entities below
that do not differ from RFC 2298 are not necessarily further
defined in this document.
Refer to RFC 2298 for AS3-MDN entities that are not further defined
in this document.
AS3-disposition-field = "Disposition" ":" disposition-mode ";"
AS3-disposition-type [ '/' AS3-disposition-modifier
]
disposition-mode = action-mode "/" sending-mode
action-mode = "manual-action" | "automatic-action"
sending-mode = "MDN-sent-manually" | "MDN-sent-automatically"
AS3-disposition-type = "processed" | "failed"
AS3-disposition-modifier = ( "error" | "warning" ) |
AS3-disposition-modifier-extension
AS3-disposition-modifier-extension =
"error: authentication-failed" |
"error: decompression-failed" |
"error: decryption-failed" |
"error: insufficient-message-security" |
"error: integrity-check-failed" |
"error: unexpected-processing-error" |
"warning: " AS3-MDN-warning-description |
"failure: " AS3-MDN-failure-description
AS3-MDN-warning-description = *( TEXT )
AS3-MDN-failure-description = *( TEXT )
AS3-received-content-MIC-field =
"Received-content-MIC" ":" encoded-message-digest
"," digest-alg-id CRLF
encoded-message-digest =
1*( 'A'-Z' | 'a'-'z' | '0'-'9' | '/' | '+' ) 0*3( '=' )
( i.e. base64( message-digest ) )
digest-alg-id = "sha1" | "md5"
The "Received-content-MIC" extension field is set after the
integrity of the received message is verified. The MIC is the
base64-encoded message-digest computed over the received message
Harding, Scott [Page 20]
INTERNET DRAFT FTP Transport Data for EDIINT April 2005
with a hash function. This field is required for signed receipts
but optional for unsigned receipts. For details defining the
specific content over which the message-digest is to be computed,
see Section 7.3.1 of this document.
The algorithm used to calculate the message digest MUST be the
same as the "micalg" value used by the sender in the
multipart/signed message. When no signature is received the
message-digest MUST be calculated using the algorithm specified
by the "micalg" value in the Disposition-Notification-Options
header.
When no signature is received and no micalg parameter is provided,
then the SHA-1 algorithm MUST be used to calculate the digest.
This field is set only when the contents of the message are
processed successfully. This field is used in conjunction with
the recipient's signature on the MDN in order for the sender to
verify non-repudiation of receipt.
AS3-MDN field names ( e.g. "Disposition:", "Final-Recipient:")
are case-insensitive ( cf. RFC 2298, 3.1.1 ).
AS3-MDN action-modes, sending-modes, AS3-disposition-types, and
AS3-disposition-modifier values that are defined above, and
user-supplied *( TEXT ) values are also case-insensitive. AS3
implementations MUST NOT make assumptions regarding the values
supplied for AS3-MDN-warning-description,
AS3-MDN-failure-description nor for the values of any (optional)
error, warning, or failure fields.
7.4.4 Additional AS3-MDN Programming Notes
1. Unlike SMTP, for FTP transactions, Original-Recipient and
Final Recipient SHOULD NOT be different. The value in
Original-Message-ID MUST match the original Message-ID
header value.
2. Refer to RFC 1892 and RFC 2298 for the formatting of the
content-type entity-headers for the MDN.
3. Use an action-mode of "automatic-action" when the disposition
described by the disposition type was a result of an automatic
action, rather than an explicit instruction by the user for
this message.
4. Use an action-mode of "manual-action" when the disposition
described by the disposition type was a result of an explicit
instruction by the user rather than some sort of automatically
performed action.
5. Use a sending-mode of "MDN-sent-automatically" when the MDN is
sent because the UA had previously been configured to do so.
6. Use a sending-mode of "MDN-sent-manually" when the user
explicitly gave permission for this particular MDN to be sent.
7. The sending-mode "MDN-sent-manually" is ONLY meaningful with
"manual-action", not with "automatic-action".
Harding, Scott [Page 21]
INTERNET DRAFT FTP Transport Data for EDIINT April 2005
8. The "failed" disposition type MAY NOT be used for the
situation in which there is some problem in processing the
message other than interpreting the request for an MDN.
The "processed" or other disposition type with appropriate
disposition modifiers is to be used in such situations.
7.5 Disposition Mode, Type, and Modifier
7.5.1 Disposition Mode Overview
This section will provide a brief overview of how processed,
error, failure, and warnings are used.
7.5.2 Successful Processing status indication
When the request for a receipt or signed receipt, and the received
message contents are successfully processed by the receiving EDI
UA, a receipt or MDN SHOULD be returned with the
"disposition-type" set to 'processed'. When the MDN is sent
automatically by the EDI UA, and there is no explicit
way for a user to control the sending of the MDN, then the first
part of the "disposition-mode" should be set to "automatic-action".
When the MDN is being sent under user configurable control, then
the first part of the "disposition-mode" should be set to
"manual-action". Since a request for a signed receipt should always
be honored, the user MUST not be allowed to configure the UA to not
send a signed receipt when the sender requests one.
The second part of the "disposition-mode" is set to
"MDN-sent-manually" if the user gave explicit permission for the
MDN to be sent. Again, the user MUST not be allowed to explicitly
refuse to send a signed receipt when the sender requests one. The
second part of the "disposition-mode" is set to
"MDN-sent-automatically" whenever the EDI UA sends the MDN
automatically, regardless of whether the sending was under a
user's, administrator's, or under software control.
Since EDI content is generally handled automatically by the EDI UA,
a request for a receipt or signed receipt will generally return the
following in the "disposition-field":
Disposition: automatic-action/MDN-sent-automatically; processed
Note this specification does not restrict the use of the
"disposition-mode" to just automatic actions. Manual actions are
valid as long as it is kept in mind that a request for a signed
receipt MUST be honored.
7.5.3 Unsuccessful processed Content
The request for a signed receipt requires the use of two
"disposition-notification-options", which specify the protocol
format of the returned signed receipt, and the MIC algorithm used
to calculate the MIC over the message contents. The
Harding, Scott [Page 22]
INTERNET DRAFT FTP Transport Data for EDIINT April 2005
"disposition-field" values that should be used in the case where
the message content is being rejected or ignored, for instance if
the EDI UA determines that a signed receipt cannot be returned
because it does not support the requested protocol format, so the
EDI UA chooses not to process the message contents itself, should
be specified in the MDN "disposition-field" as follows:
Disposition: "disposition-mode"; failed/Failure: unsupported Format
The "failed" AS3-disposition-type should be used when a failure
occurs that prevents the proper generation of an MDN.
For example, this disposition-type would apply if the sender of the
message requested the application of an unsupported
message-integrity-check (MIC) algorithm.
The "failure:" AS3-disposition-modifier-extension should be used
with an implementation-defined description of the failure.
Further information about the failure may be contained in a
failure-field. The syntax of the "failed" "disposition-type" is
general, allowing the sending of any textual information along with
the "failed" "disposition-type". Implementations WILL support any
printable textual characters after the Failure disposition-type.
For use in Internet EDI, the following "failed" values are
pre-defined and MUST be supported:
"Failure: unsupported format"
"Failure: unsupported MIC-algorithms"
7.5.4 Unsuccessful Non-Content Processing
When errors occur processing the received message other than
content, the "disposition-field" should be set to the "processed"
"disposition-type" value and the "error" "disposition-modifier" \
value.
The "error" AS3-disposition-modifier with the "processed"
disposition-type should be used to indicate that an error of some
sort occurred that prevented successful processing of the message.
Further information may be contained in an error-field.
An "error:" AS3-disposition-modifier-extension should be used to
combine the indication of an error with a pre-defined description
of a specific, well-known error. Further information about the
error may be contained in an error-field.
For use in Internet EDI, the following "error"
"disposition-modifier" values are defined:
"Error: decryption-failed" - the receiver could not decrypt the
message contents.
"Error: authentication-failed" - the receiver could not
Harding, Scott [Page 23]
INTERNET DRAFT FTP Transport Data for EDIINT April 2005
authenticate the sender.
"Error: integrity-check-failed" - the receiver could not verify
content integrity.
"Error: insufficient-message-security" - the security level of the
message did not match the
agreed level between TPs.
"Error: decompression-failed" - the receiver could not decompress
the message contents.
"Error: unexpected-processing-error" - a catch-all for any
additional processing
errors.
An example of how the "disposition-field" would look when other
than content processing errors are detected is as follows:
EXAMPLE
Disposition: "disposition-mode";
processed/Error: decryption-failed
7.5.5 Processing Warnings
Situations arise in EDI where even if a trading partner cannot be
authenticated correctly, the trading partners still agree to
continue processing the EDI transactions. Transaction
reconciliation
is done between the trading partners at a later time. In the
content
processing warning situations as described above, the
"disposition-field' SHOULD be set to the "processed"
"disposition-type" value, and the "warning" "disposition-modifier"
value.
The "warning" AS3-disposition-modifier should be used with the
"processed" disposition-type to indicate that the message was
successfully processed but that an exceptional condition occurred.
Further information may be contained in a warning-field.
A "warning:" AS3-disposition-modifier-extension should be used to
combine the indication of a warning with an implementation-defined
description of the warning. Further information about the warning
may be contained in an warning-field.
For use in Internet EDI, the following "warning"
"disposition-modifier" values are defined:
"Warning: authentication-failed, processing continued"
An example of how the "disposition-field" would look when other
than
content processing warnings are detected is as follows:
EXAMPLE
Disposition: "disposition-mode"; processed/Warning:
authentication-failed, processing continued
Harding, Scott [Page 24]
INTERNET DRAFT FTP Transport Data for EDIINT April 2005
*****************************************************
Terry Harding
Cyclone Commerce Inc.