TSW SOAP Interface

Technical Notes for .NET Client

264515281 - Page 1 of 23

Document Control
Document Revision History
Version Name

Comments

Date

0.1

Datacom

Draft

06/11/2012

0.2

Datacom

Reviewed copy sent to Customs for feedback.

07/11/2012

0.3

Datacom

Customs feedback

08/11/2012

0.4

JBMS

Prepared for first release to trade

08/11/2012

Document Contributors
Name

Role

Andrew Savinykh

Technical Lead, Datacom Systems Ltd

Chris Prior

Customs B2B Architect

Reviewers
Name

Organisation

Chris Prior

Customs

Related Documents
Document

Version

Organisation

Author

ClientName EXT Configuration TSW B2B 0.1

gateway for PULL Responses

New Zealand
Custom Service

JBMS

Stage 1 integration steps to the EXT

TSW B2B gateway for PULL Respones

0.1

New Zealand
Custom Service

JBMS

Integrating Party TSW B2B Gateway

PILOT MessagingCertificate Guidelines

0.5

New Zealand
Custom Service

JBMS

Stage 2 integration steps to the EXT

TSW B2B gateway for PULL Responses

0.1

New Zealand
Custom Service

JBMS

Stage 3 integration steps to the EXT

TSW B2B gateway for PULL Responses

0.1

New Zealand
Custom Service

JBMS

Pilot Legacy Test Approach

1.0

New Zealand
Custom Service

JBMS

TSW B2B Pilot Messaging Technical

Overview for Direct Connect Clients

0.5

New Zealand
Custom Service

JBMS

Pilot Messaging Technical Overview SOAP

0.5

New Zealand
Custom Service

JBMS

Prepared for
NZCS

8th November, 2012

Version 0.4

264515281 - Page 2 of 23

Contents
TSW SOAP Interface...................................................................................1
1.

Document Purpose..............................................................................4

2.

Architecture/Modules Overview...........................................................5

3.

API Overview......................................................................................7
3.1 Submit Lodgement........................................................................................... 7
3.2 Request Lodge Response.................................................................................. 7

4.

API Considerations..............................................................................8
4.1 Certificates....................................................................................................... 8
4.2 Bindings............................................................................................................ 8

5.

Known Issues.....................................................................................9
5.1 Attachments are not being signed....................................................................9
5.2 There is no verification of the response signatures..........................................9
5.3 Push interface for responses is not utilized......................................................9
5.4 There is a potential for lost responses..............................................................9
5.5 Only one attachment per message is supported............................................10
5.6 A number of MIME message headers are static..............................................10

6.

Appendix A Data structures.............................................................11

6.1 Submit Lodgement......................................................................................... 11
6.2 Request Lodge Response................................................................................ 11

264515281 - Page 3 of 23

1. Document Purpose
This document describes architecture and implementation of the Customs TSW B2B
gateway SOAP 1.1 client for .NET using a PUSH PULL interaction model for submitting
lodgements and receiving lodgement responses.
The Customs TSW B2B gateway exposes its endpoints with SOAP 1.1. SOAP and is a
well understood standard. However there are sometimes incompatibilities in
implementing an integration; often a fair amount of configuration effort is required as
well as specific code changes to support certain features of a protocol.
In particular, SOAP With Attachments protocol extension is not supported out of the
box by standard .Net libraries, preferring SOAP 1.2 and MTOM. With this in mind an
implementation of a .NET client, written in C#, to support SWA has been created.
The implementation is targeted to the developers that want to communicate with
Customs TSW B2B gateway from a .NET based application.

264515281 - Page 4 of 23

2. Architecture/Modules Overview
The following diagram represents the main components of the implemented solution
and related systems.
The .NET client is built on top of Windows Communication Foundation (WCF)
framework that is part of .NET Framework. The .NET Framework version 4.0 was used
whilst implementing the codebase using C#.

The .NET client solution itself comes in three parts:

SWA Library:
Microsoft.Austria.WcfHelpers.SoapWithAttachments a custom message
encoder to support SOAP With Attachments specification. Originally published
by Microsoft Austria on codeplex at http://wcfswaencoder.codeplex.com/ and
modified to suite JBMS project needs
Jbms.Client:
o Client API this is the main endpoint a client application calls to
communicate with the Customs TSW B2B gateway
o Proxy these are classes that represent data structures required in the
Client API calls. Generated from the WSDL and then hand-modified to
work around interop issues.
264515281 - Page 5 of 23

Support classes a sundry of related code, most notably the Signature

Removing set of classes that set up WCF extensibility infrastructure for a
custom channel that in this case strips the signatures off incoming
messages.

264515281 - Page 6 of 23

Jbms.TestApp:
o Test application that demonstrate how to use Jbms.ServicesAPI
o Bindings configuration WCF bindings that are compatible with the
Customs TSW B2B gateway server configuration

Jbms.TestApp is not intended to be a part of any real-life solution, instead similar code
and bindings will become a part of each client application that wants to communicate
with the Customs TSW B2B gateway.
Note: These components are meant to be part of each individual client application
solution. There are no separate deployment requirements/scenarios for this apart from
those of encasing application. It is recommended, that these are added into the client
application Visual Studio solution in form of source code, so that any customisation
necessary is easier.
Components
Name

Version

Windows Server

2008 R2
Enterprise

.NET

4.0

Note: These are the version of components the solution was tested with. It is also likely
to work on other version of Windows as long as .NET version is 4.0. It might work on
.NET 3.5 but it is untested. It wont work on the earlier version of .NET.

264515281 - Page 7 of 23

3. API Overview
As of the moment of writing there are 2 APIs provided to communicate with the
Customs TSW B2B gateway.

264515281 - Page 8 of 23

3.1 Submit Lodgement

TODO: Provide description of what the API does or refer to appropriate documentation
This is the API signature:
SubmitLodgementResponseSendLodgementRequest(SubmitLodgementRequest request,
stringendpointName = "SubmitLodgement")

Please see Appendix A for the list of the pseudo-code of the structures used for the
request and response. The endpointName optional parameter specifies the endpoint
name as specified in the bindings configuration.

264515281 - Page 9 of 23

3.2 Request Lodge Response

TODO: Provide description of what the API does or refer to appropriate documentation
This is the API signature:
RequestLodgeResponseResponseSendPullRequest(RequestLodgeResponseRequestrequestLodg
eResponseRequest, stringendpointName = "RequestLodgeResponse")

Please see Appendix A for the list of the pseudo-code of the structures used for the
request and response. The endpointName optional parameter specifies the endpoint
name as specified in the bindings configuration.

264515281 - Page 10 of 23

4. API Considerations

264515281 - Page 11 of 23

4.1 Certificates
Access to the Customs TSW B2B gateway is secured by means of certificates. For each
particular client four certificates are used like so:

A server certificate for mutual SSL (the same for all clients)

A server certificate for message signature operations (the same for all clients)

A client certificate for mutual SSL (unique per client)

A client certificate for message signature operations (unique per client)

These certificates have to be installed on the .NET Client machine in the following
manner:

The server public key/certificate for mutual SSL

The server public key/certificate for message signature operations

The client private key/certificate for mutual SSL

The client private key/certificate for message signature operations

This is required so that the client application has access to them.

Note that the documentation following is written with an assumption that
mutual SSL certificate usage is setup prior to messaging library invocation
(i.e. only the message signature certificate is referred to).

264515281 - Page 12 of 23

4.2 Bindings
Most of the Bindings configuration, provided along with the JBMS.TestApp application,
does not need changing. However there are a few things that have to be customized:

Certificate names and locations as appropriate. The name should be the name
of the certificate you are using, and the location should be the location of the
store you installed it to:

<behaviorname="jbms_credentials_behavior">
<clientCredentials>
<!-- Change this line to specify your client certificate -->
<clientCertificatefindValue="extb2b.tsw.message.sig.clientName"storeLocation="LocalMachine"storeNam
e="My"x509FindType="FindBySubjectName" />
<serviceCertificate>
<!-- This certificate is to be obtained along with this code -->
<defaultCertificatefindValue="extb2b.tsw.message.sig.customs"storeLocation="LocalMachine"storeName
="My"x509FindType="FindBySubjectName" />
<authenticationcertificateValidationMode="None"trustedStoreLocation="LocalMachine"revocationMode="
NoCheck" />
</serviceCertificate>
</clientCredentials>
</behavior>

Service URL. Each endpoint (as of the moment of writing there are two) has its
own endpoint URL. This URL should be changed to point to the appropriate
server and the last part of the URL should correspond to the client certificate
used is the application:
<!-- Make sure to change everything after 'TP=' to keyword corresponded to your client
certificate -->
<endpointaddress="https://extb2b.tsw.govt.nz/soap?
service=TSW_WS_SUBMIT_LODGEMENT_SEC&amp;TP=AS_AGREED_WITH_CUSTOMS"

264515281 - Page 13 of 23

5. Known Issues

264515281 - Page 14 of 23

5.1 Attachments are not being signed

The SOAP With Attachments Codeplex implementation being used does not support
signing the contents of the attachments. The out-of-the-box WCF based code signs
only the contents of the SOAP message body, and when an attachment is not in-line,
as in the case of SOAP With Attachments specification, they are not being signed.
In order to be able to sign them custom code has to be written, that would calculate
the signature across the SOAP message body and the attachment(s) and add it to the
MIME header for the attachments, as per the SOAP With Attachments specification.

264515281 - Page 15 of 23

5.2 There is no verification of the response signatures

Due to observed incompatibility of signing libraries used on the client as compared to
the server side, client signature verification on the responses received from the server
fails (whereas server side verification of signatures sent by a client has been proven to
work correctly) . Until a solution to this is found the signatures are being removed from
the responses on arrival and not being checked this represents a business risk to
trade and customs of impaired non-repudiation.
To solve this issue it is necessary to find out why server side libraries and client side
libraries produce different message digests for the same message and remedy the
reason. Ultimately its possible that a custom signature verification code might be
required.

264515281 - Page 16 of 23

5.3 Push interface for responses is not utilized

Push responses, where JBMS initiates the communication channel, are out of scope of
this solution.
TODO: Add rationale why WCF server was not implemented in this phase.
At a later phase when Push interface responses are to be provided, implementation
will require a WCF server as opposed to WCF client implementation of this solution.

264515281 - Page 17 of 23

5.4 There is a potential for lost responses

The pull interface caters for polling for responses to the submitted lodgments. Once a
pull request is processed on the server, the server removes it from the pool of
available responses. If, for whatever reason, a message is successfully sent from the
server but is not stored by the client, then the delivery of this message will be lost.
It is responsibility of the integrating party to architect for this possibility through
tracking and reporting Lodgements that have not been responded to in a timely
manner. A manual process should be initiated through the help desk to log
retransmission of the response with Customs.

264515281 - Page 18 of 23

5.5 Only one attachment per message is supported

The current SOAP With Attachments implementation from Codeplex only supports one
attachment per message, so it will not work with multiple attachments be it sent or
received ones.
It should not be too difficult to modify the code base to support multiple attachments.

264515281 - Page 19 of 23

5.6 A number of MIME message headers are static

Currently most of the MIME headers values that do not have to be dynamic are static
(i.e. exactly the same for all messages). This includes various message IDs and
content IDs and most notably the attachment name. It should not be too difficult to
modify the code base to support dynamic IDs.

264515281 - Page 20 of 23

6. Appendix A Data structures

This appendix provides a description of all data structures used in the client API in
pseudo-code.

264515281 - Page 21 of 23

6.1 Submit Lodgement

publicpartialclassSubmitLodgementRequest {
publicManifestDocumentManifest;
publicBinary attachment;
}
publicpartialclassManifest {
publicstringNumberOfItems;
publicManifestItem[] ManifestItem;
}
publicpartialclassManifestItem {
publicManifestType Type;
publicMIMEMediaTypeContentTypeMimeTypeQualifierCode;
publicstringUniformResourceIdentifier;
publicstringAdditionalDocumentIdentification;
publicstring Authentication;
}
publicenumManifestType {
DEC,BWD,CDF,CRW,GFL,GMI,ICD,GIL,PAX,POC,MDH,SST,CDO,BAC,IFC,
}
publicenumMIMEMediaTypeContentType {
applicationactivemessage,
(hundreds more MIME content types go here)
}
publicpartialclassBinary {
publicstringhref;
publicbyte[] Value;
}
publicpartialclassSubmitLodgementResponse {
publicMessageInfoMessageInfo;
public.Binary attachment;
}
publicpartialclassMessageInfo {
publicstring Document;
publicstringDeliveryMethod;
publicstring Direction;
publicstringDocumentSize;
publicSystem.DateTimeDateReceived;
publicboolDateReceivedSpecified;
publicstring Status;
}

264515281 - Page 22 of 23

6.2 Request Lodge Response

publicpartialclassRequestLodgeResponseRequest
{
publicRequestResponseRequestResponse;
}
publicpartialclassRequestResponse
{
publicstring Submitter;
publicstring Item;
publicItemChoiceTypeItemElementName;
}
publicenumItemChoiceType
{
EntryID, SenderReference,
}
publicpartialclassRequestLodgeResponseResponse
{
publicSystem.Xml.XmlElementprocessData;
publicBinary attachment;
}
publicpartialclassBinary
{
publicstringhref;
publicbyte[] Value;
}

264515281 - Page 23 of 23