TSW SOAP Interface Technical Notes for DotNET Client v0 4

TSW SOAP InterfaceTechnical Notes for .NET Client

document.docx - Page 1 of 13

Prepared for

NZCS

8th November, 2012

Version 0.4

Document ControlDocument 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 gateway for PULL Responses

0.1 New Zealand Custom Service

JBMS

Stage 1 integration steps to the EXT TSW B2B gateway for PULL Respones


JBMS

Integrating Party TSW B2B Gateway PILOT MessagingCertificate Guidelines


JBMS

Stage 2 integration steps to the EXT TSW B2B gateway for PULL Responses


JBMS

Stage 3 integration steps to the EXT TSW B2B gateway for PULL Responses


JBMS

Pilot Legacy Test Approach 1.0 New Zealand Custom Service

JBMS

TSW B2B Pilot Messaging Technical Overview for Direct Connect Clients


JBMS

Pilot Messaging Technical Overview - SOAP 0.5 New Zealand Custom Service

JBMS


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


1. Document PurposeThis 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.


2. Architecture/Modules OverviewThe 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 gatewayo 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.o 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.


http://wcfswaencoder.codeplex.com/

Jbms.TestApp:o Test application that demonstrate how to use Jbms.ServicesAPIo 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 won’t work on the earlier version of .NET.


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

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.

3.2 Request Lodge Response

TODO: Provide description of what the API does or refer to appropriate documentation

This is the API signature:

RequestLodgeResponseResponseSendPullRequest(RequestLodgeResponseRequestrequestLodgeResponseRequest, 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.


4. API Considerations

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).

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><clientCertificatefindValue="extb2b.tsw.message.sig.clientName"storeLocation="LocalMachine"storeName="My"x509FindType="FindBySubjectName" /><serviceCertificate><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:


<endpointaddress="https://extb2b.tsw.govt.nz/soap?service=TSW_WS_SUBMIT_LODGEMENT_SEC&TP=AS_AGREED_WITH_CUSTOMS"


5. Known Issues

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.

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 it’s possible that a custom signature verification code might be required.

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.

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.


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.

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.


6. Appendix A – Data structuresThis appendix provides a description of all data structures used in the client API in pseudo-code.

6.1 Submit LodgementpublicpartialclassSubmitLodgementRequest {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; }

6.2 Request Lodge ResponsepublicpartialclassRequestLodgeResponseRequest {publicRequestResponseRequestResponse; }

publicpartialclassRequestResponse


{publicstring Submitter;publicstring Item;publicItemChoiceTypeItemElementName; }

publicenumItemChoiceType {EntryID, SenderReference, }

publicpartialclassRequestLodgeResponseResponse { publicSystem.Xml.XmlElementprocessData;publicBinary attachment; }

publicpartialclassBinary {publicstringhref;publicbyte[] Value; }

TSW SOAP Interface Technical Notes for DotNET Client v0 4

Documents

ext tsw b2b gateway

customs tsw b2b gateway

net client solution

net framework version

pull responses0

standard net libraries

document purposethis

integration steps