eSchKG Networking
Contents
1. Members of the eSchKG community network encode the addressee of a document ac cording to the following file name convention lt Sedex ID gt original filename Renaming is the responsibility of the enterprise system not MessageHandler v3 If you wanted to send test xm1 to Sedex ID 7 4 1 which is the eSchKG Testbed the enter prise application would need to change the file name to 7 4 1 test xml prior to moving it to the MessageHandler s OUTBOX Renaming is the responsibility of the enterprise system Once the files are in the OUTBOX MessageHandler builds the envelope and document files required by Sedex and forwards them to the Sedex client software In order to do that Mes sageHandler v3 must extract the addressee from the filename first It does so using an ex ternal program or script For usage in the eSchKG community network the following Groovy script will do the job param filename the name of the file to be sent including path return the resolved Sedex ID or an empty string import java util regex Matcher def String resolve String filename Matcher matcher null if System getProperty os name startsWith Windows matcher filename St _ S else eoulld be Unix matcher filename N NS t if matcher matches return matcher group 1 If all else fails return empty string return oii Listing Groovy script resolving Sedex add2. workingDir i corrupted Js db d sent 3 3 tmp P preparing d receiving di unknown Figure Example INBOX mh311 in and OUTBOX mh311 out mh311 signOut eSchKG Networking Red Book Edition March 2014 Page 11 Annex MessageHandler Configuration Overview The following sample configuration is to demonstrate some typical configuration options for use within the eSchKG community network lt config xmlns xsi http www w3 org 2001 XMLSchema instance xsi schemaLocation http msghandler suis admin ch xmlns config config xsd xmlns http msghandler suis admin ch xmlns config version 3 1 gt 1 2 3 4 3 lt sedexAdapter gt 6 E 8 lt participantId gt 7 4 1 lt participantId gt lt inboxDir gt C SedexAdapter inbox lt inboxDir gt lt outboxDir gt C SedexAdapter outbox lt outboxDir gt 9 lt receiptDir gt C SedexAdapter receipts lt receiptDir gt 10 lt sentDir gt C SedexAdapter sent lt sentDir gt 11 lt sedexAdapter gt 12 13 lt messageHandler gt 14 lt workingDir dirPath C SedexAdapter mh workingDir gt 15 lt baseDir dirPath C SedexAdapter mh runtime gt 16 lt sedexInboxDirCheck cron 0 30 9 gt 17 lt sedexReceiptDirCheck cron 0 30 gt 18 defaultOutboxCheck cron 0 30 2 gt T9 webserviceInterface host localhost port 18080 gt 20 lt statusDatabase dirPath C SedexAdapter mh workingDir db 21 dataHoldTimeInDays 2 resend tru
3. German French and Italian e Orange Book Anleitung ftir die Mitgliedschaft im eSchKG Verbund Ausgabe Marz 2014 A step by step guide to joining the eSchKG community network including pre paratory work and administrative tasks Available in German French and Italian e Red Book eSchKG Networking This document A technical guide to connecting an enterprise system to the eSchKG community network Available in English e Blue Book Exchange of Electronic Business Information in the Domain of Debt En forcement and Bankruptcy Schema Version 2 0 014 Edition March 2014 An intro duction to the architectural principles data model and high level protocols This document comprises two appendices o Appendix 1 XML Reference o Appendix 2 Testbed User Manual The Blue Book and appendices are available in English In order to become a full member of the eSchKG network applicants are required to adhere to the administrative procedures outlined in the Orange Book The full standard specification is available online www eschkg ch Licensing The MessageHandler software and all eSchKG specification documents are distributed freely under GNU public license GPL eSchKG Networking Red Book Edition March 2014 Page 4 1 Introducing MessageHandler v3 1 1 Before You Start Before you start reading the following documentation is highly recommended e Anleitung f r die Mitgliedschaft im eSchKG Verbund Orange Book Ausgabe M
4. ii iE EE Een KE EE Ee EER EREN E REK EERE 10 2 7 MessageHandler Configuration Examples on the Web sss 11 2 8 MessageHandler INBOX and OUTBOX rre reer e erare ereere E Esar E EAR ar KeK AREA AR ERKA K ESANA TRSKE Na EAKA 11 Annex MessageHandler Configuration Overview uusanssssssonsnnnssnnsnnnsnsnnnnsnnsnnnsnnnnnnnsnnsnnnnsnnsnnnsannsnsnsansnnnssnnen 12 eSchKG Networking Red Book Edition March 2014 Page 3 About This Document This document addresses integrators and architects responsible for operating software connecting to the eSchKG community network This document is a guide to using MessageHandler v3 in the eSchKG community network It is acomplementary manual to the Sedex user manual 1 and the Open eGov MessageHan dler technical documentation 2 both of which are considered mandatory reading along with this document In this document MessageHandler v3 is mentioned without specifying the minor version Actually we mean the latest version of the MessageHandler software package having major version 3 About eSchKG The eSchKG standard is a normative framework for the exchange of electronic business in formation between parties in a debt collection eSchKG is being published by the Swiss Fed eral Office of Justice comprising the following documentation e White Book Einf hrung in den eSchKG Standard Ausgabe M rz 2014 An introduc tion to eSchKG mainly addressing the executive Available in
5. RN sehen sen EUREN aa LATA EAR ERR aE TEER 5 2 Using MessageHandler v3 with eSchKG 1 ueee esee esee eene esee ee eene een n nennen esten enano assesses esee nass seen 6 2 1 General Commlents iubebo bbeimtetdeitetee ideis 6 2 2 Mode of Operation 2 22 eire anna bet Eoo le Ere are ate eio do Ee eere ade apto Le cated deletes ebeenel 6 2 3 Addressing ra a in a sided e Prae Ee a e hs Ma Nase Mea cae Pod TER eect es 6 2 4 Digitally Signing Outgoing Documents sssssseeseeeeneeee eene nennen nenne nennen eee nn nnns seen n nnne 7 24 1 ThesSigning QUIBOX i e tete titt einn oed ee etae deed ba a dendo san nalen 7 2 4 2 Signature Conventions t emailen Eichen 24 3 Signature Profile senaera aa ine br ee td E be ea du ee ea aa no eaa dr orna 2 44 Digital Certificate for Signing 2 45 Specifying the Signing OUTBOX Digital Certificate with a Logical Adapter sees 9 2 5 Event Logging and Traffic Monitoring ccccsscccccccesssssseeecceceeseeeseeeeececesseesaeeeeeeesseeeeeaeeeeeeeseseeenaea 10 2 6 Opetati nalssues ini OU E RO E ERE ER EGRE ERES 10 2 61 FileSystem Access Rights eae ae dea edo hedge adeo de aed d dede dde adea 10 2 6 2 Renewal of Sedex Client and MessageHandler Software essen 10 2 6 3 Renewal of the Sedex Client Certificate esses eese eene nnns nnns nena 10 2 6 4 eSchKG Member DirectoOry seeieeissssssess sans ann
6. Schweizerische Eidgenossenschaft Conf d ration suisse Confederazione Svizzera Confederaziun svizra Eidgen ssisches Justiz und Polizeidepartement EJPD Bundesamt f r Justiz BJ Direktionsbereich Zentrale Dienste Fachbereich Rechtsinformatik Exchange of Electronic Business Information in the Domain of Debt Enforcement and Bankruptcy MessageHandler Version 3 1 1 Edition March 2014 References 1 Sedex Handbuch Version 4 0 3 Bundesamt f r Statistik 15 11 2012 2 Open eGov MessageHandler v3 1 1 Technical Documentation Glue Software Engi neering 13 03 2013 eSchKG Networking Red Book Edition March 2014 Page 2 Table of Contents References 53 sass cassecsiesssascicacsenttevsacesachescstisdescstessoseasessndcesessoccetessoceetocscdsetbeneceesesbosessesuasesbasgcbesduaassersesdesessaaaneevene 2 AbOUU THIS Documentos ese osses sese esros aaa aSo ENS Soe aieo e So Saes ESS aoe ross Oe osia sise Sse asi 4 hop cp 4 LicerisiDng oerte c e te ec oce ste eto etes t sene esee Pere eter es eee roo ese eee Ceo ID 4 1 Introducing MessageHandler v3 reete 550408008804 50a eI eoe ee Ee ERAS TERES eee SER nE SE esae PERS eee teren 5 1 1 Before You Start nee et E EE Ne oe ipe neret Sovak ieh 5 1 2 Hiding Sedex Complexity From The Application sseeeeeeeseeeeeee enne 5 1 3 Why Use MessagehHlarid ler 5 3 5 rientro to Ee FS R ER NER ERR ee FEES R E
7. _N xxx required by the Sedex client Enter prise applications do not have to care about this at all 1 3 Why Use MessageHandler Using MessageHandler v3 you take advantage of the following e Easy integration of Sedex with the enterprise system e Enhanced traffic monitoring and control e Allows for transparently applying digital signatures to outgoing PDF documents There may be other middleware available on the market doing a similar job To the members of the eSchKG community network using MessageHandler v3 is highly recommended It is the only middleware for which ongoing maintenance and support are granted by the Federal Office of Justice eSchKG Networking Red Book Edition March 2014 Page 5 2 Using MessageHandler v3 with eSchKG 2 1 General Comments When reading the Sedex User Manual 1 or the Open eGov MessageHandler v3 0 Technical Documentation 2 you may find Sedex address descriptors having prefix T like in T7 4 2 As you may be aware such an address can only be used with the Sedex test network Don t worry aS a member of the eSchKG network your Sedex adapter is a fully productive one from the start Read the documents and examples as if the Sedex address descriptors were productive ones like 8 AG 13 2 2 Mode of Operation Members of the eSchKG community network use MessageHandler v3 in native mode See also Open eGov MessageHandler v3 Technical Documentation 2 section 2 3 2 3 Addressing
8. arz 2014 How to join the eSchKG community network and obtain your Sedex certificates e Sedex User Manual Sedex Handbuch latest version A guide to installing and con figuring Sedex so you can send and receive Sedex messages e Open eGov MessageHandler v3 Technical Documentation MessageHandler v3 was built for a wide variety of community networks Some of the configuration options are relevant for the eSchKG community network while others are not Apart from the above documentation there is one more thing you need to know When connecting to the eSchKG network community using your own physical Sedex endpoint a k a adapter is highly recommended Using a logical adapter means you ll have to renew your Sedex certificates manually when the time has come 1 2 Hiding Sedex Complexity From The Application MessageHandler v3 was designed to ease the integration of enterprise systems with the Sedex network so applications can rely on a secure message path to peers Instead of hav ing to re program your enterprise application so it can deal with the particulars of sending and receiving Sedex messages all it needs to do is read from and write to the local file sys tem MessageHandler v3 takes care of the cumbersome tasks associated with sending and receiving Sedex messages without the application even noticing Each time eSchKG messages are to be sent MessageHandler v3 generates the enve lope envi N xm1 and document file data
9. ch 2014 Page 13
10. e gt 22 lt messageHandler gt 23 24 lt nativeApp participantId 7 4 1 lt die lokale sedexId gt 25 lt outbox dirPath mh out msgType 10301 gt 26 lt recipientIdResolver 27 filePath C SedexAdapter mh conf recipientIdResolver groovy 28 method resolve gt 29 lt signingOutbox dirPath mh signOut 30 processedDir C SedexAdapter mh runtime mh signOut processed 3 signingProfilePath C SedexAdapter mh conf signing signature properties gt 32 lt certificateConfigFile EE filePath C SedexAdapter conf certificateConfiguration xml gt 34 lt signingOutbox gt 35 lt outbox gt 36 lt inbox dirPath mh in msgTypes 10301 gt 37 lt nativeApp gt 38 lt config gt Listing Typical configuration options for the eSchKG community network 6 participantId is the address of your Sedex client adapter 19 port can be chosen arbitrarily 24 participantId is the address of your Sedex client adapter 25 Always use 10301for attribute msgType 36 Always use 10301for attribute msgTypes eSchKG Networking Red Book Edition March 2014 Page 12 License Information eSchKG is free of charge and may be used and distributed freely MessageHandler is free of charge the GPL GNU Public License applies Publisher Swiss Federal Office of Justice Bundesrain 20 3003 Bern Switzerland Contact Fachbereich Rechtsinformatik T 031 324 74 74 www bj admin ch eschkg bj admin ch eSchKG Networking Red Book Edition Mar
11. ecifying the position of the visible signature on the PDF file The position and size of the signature are as follows e Always sign on page 1 e Position x 110 mm from left edge y 270 mm from upper edge e Size of signature box width 75 mm height 15 mm 2 43 Signature Profile In order to adhere to the signature conventions a signature profile must be created telling MessageHandler v3 the position of the signature in a document The following is a sample signature profile suitable for signing PDF documents like default summons and others by the collection offices bold text indicates configuration information that must be used exactly as shown typeOfSignature signature visibleSignature true location Bern reason contact name your company ch backgroundImage leftPos 110 eSchKG Networking Red Book Edition March 2014 Page 7 topPos 270 boxWidth 75 boxHeight 15 signOn 0 enableTimestamping false tsaurl http tsa swisssign net http tsa t0l admin ch rfc3161 esauser tsapassword Listing Signature profile compliant with eSchKG conventions Parameter Remarks Convention typeOfSignature The kind of signature to be produced MUST BE signature visibleSignature Prints a signature box in the PDF MUST BE true location The signer s domicile reason A text specifying the signing action contact A person s email address backgroundImage A picture display
12. fy the location of the Signing Outbox as well as the digital signature certificate For the eSchKG community network specify the location of the Sedex client certificate configura tion using lt certificateConfigFile gt as shown below eSchKG Networking Red Book Edition March 2014 Page 8 lt nativeApp participantId 7 4 1 gt lt your own local sedexId gt lt outbox dirPath mh3outbox msgType 10301 gt lt recipientIdResolver filePath C SedexAdapter mh3 conf recipientIdResolver groovy method resolve gt lt signingOutbox dirPath mh3signOutbox processedDir C SedexAdapter mh3 runtime mh3signOutbox processed signingProfilePath C SedexAdapter mh3 conf signing signature properties gt lt certificateConfigFile filePath C SedexAdapter conf certificateConfiguration xml gt lt signingOutbox gt lt outbox gt lt inbox dirPath mh3inbox msgTypes 10301 gt lt nativeApp gt Listing Configuring the Signing Outbox in the eSchKG community network The good news is that the certificate renewal process of Sedex has an immediate effect on the Signing Outbox There is no need for the system administrator to change or renew nei ther the configuration of MessageHandler v3 nor the signature certificate 2 45 Specifying the Signing OUTBOX Digital Certificate with a Logical Adapter Transparently signing outgoing PDF documents is a novel feature of MessageHandler v3 The software allows using any digital certifica
13. ing in the signature s background leftPos Position from left x in mm MUST BE 110 topPos Position from top y in mm MUST BE 270 boxWidth Width of the signature box in mm MUST BE 75 boxHeight Height of the signature box in mm MUST BE 15 signOn MUST BE 0 enableTimestamping true if you want the signature timestamped MUST BE false tsaurl The URL of a timestamp authority tsauser User name for the timestamp service tsapassword The password for the timestamp service Listing Parameters of the signature profile In the download file for MessageHandler v3 you can find a sample signature profile in lt installation dir gt conf signing signature properties According to the sample configuration file in lt installation dir gt conf config xml MessageHandler v3 uses a file called signature properties as the signature profile speci fication Feel free to override the location of the signature profile 2 4 4 Digital Certificate for Signing When configuring the signing feature of MessageHandler v3 users can specify the certificate and other parameters freely However users of the eSchKG community network have no freedom when it comes to specifying the signing certificate Users of the eSchKG community network MUST configure the signing feature such that it uses the certificate of the Sedex client software for signing In the MessageHandler v3 configuration file config xml the lt signingOutbox gt tag is used to speci
14. o or moved away from a specific directory Make sure the user account running MessageHandler v3 is granted the appropriate ac cess rights to launch services and scripts and to store and remove documents around in the file system where Sedex and MessageHandler directories reside 2 6 2 Renewal of Sedex Client and MessageHandler Software Sedex Client software is maintained and published by the Swiss Federal Statistical Office while MessageHandler v3 software is maintained and published by the Federal Office of Jus tice Whenever a new version of either software suite is released those registered as a tech nical contact are notified so they can download and re install the software Note that by the time of this writing updating the Sedex Client and MessageHandler v3 software suites are a manual task 2 6 3 Renewal of the Sedex Client Certificate The Sedex client is responsible for sending and receiving messages from and to the Sedex Server securely which is why they are encrypted decrypted using public key infrastructure technology PKI As mentioned above the Sedex client is unable to renew itself as a soft ware suite but it does renew the Sedex client s PKI information including the private key and the digital certificate Note that it can do so only with a physical adapter not a logical one Note that when using a logical Sedex adapter the Sedex messages you send are being encrypted and signed using the common physical adap
15. ress from compliant file names See also Open eGov MessageHandler v3 Technical Documentation 2 section 4 9 eSchKG Networking Red Book Edition March 2014 Page 6 2 4 Digitally Signing Outgoing Documents Collection offices have an obligation to digitally sign outgoing PDF files Collection offices can use the signing OUTBOX feature of MessageHandler v3 to do that 2 4 1 The Signing OUTBOX MessageHandler v3 allows for digitally signing outgoing PDF documents prior to forwarding them to the Sedex client Documents are moved to the Signing Outbox for pre processing rather than the ordinary OUTBOX After signing MessageHandler v3 would move the origi nal unsigned files to some pre defined directory called processed for instance while signed documents are moved forward to the OUTBOX for sending Before signing After signing document pdf Signing Outbox Signing Outbox oe Ga em N amp 7 N N document pdf N Signed lt a Er amp Processed dir 3 Processed dir 3 document sig pdf Outbox Outbox Figure Signing Outbox Directory Warning Do not put any other files but PDF documents to the Signing Outbox In particular you must not write any XML files to it Outgoing XML files eSchKG messages must always go to the normal MessageHandler s OUTBOX 2 4 2 Signature Conventions For usage in the eSchKG community network the signature applied by MessageHandler v3 must adhere to a common layout convention sp
16. sers of a logical Sedex adapter benefit from the certificate renewal process only as far as Sedex messaging is concerned Logical Sedex adapter certificates used for the Signing Outbox will need to be renewed manually Repeat Users of the eSchKG community network are encouraged to use a physical Sedex adapter of their own eSchKG Networking Red Book Edition March 2014 Page 9 2 5 Event Logging and Traffic Monitoring MessageHandler v3 keeps a monitoring log for each outgoing message See the Open eGov MessageHandler v3 Technical Documentation 2 section 2 7 Protocol for details Inspecting log files is a cumbersome and tricky task In order to make things easier Mes sageHandler v3 comes with a monitoring interface so traffic can be controlled from the enter prise application or console If you intend to exercise control over eSchKG traffic by the en terprise application you ll find this new feature very useful It is highly recommended that applications exercise some kind of monitoring and control over eSchKG traffic Enterprise applications shall be capable of responding to network issues timely and reliably See also Open eGov MessageHandler v3 Technical Documentation 2 section 5 2 6 Operational Issues 2 6 1 File System Access Rights Experience shows that in the early stages of configuration and testing a great number of issues are simply due to insufficient access rights preventing files from being written t
17. te for which a PKCS 12 description exists However users of the eSchKG community network use the Sedex client certificate as out lined earlier see 2 4 4 above For eSchKG users running their own physical Sedex adapter there s nothing more to say But those running a logical Sedex adapter have got some more work to do To those using a logical Sedex adapter CHECK THIS OUT When using the Signing Outbox feature of MessageHandler v3 you must use the digital certificate of your logical Sedex adapter As digital signatures are used to identify the signing party using the physical Sedex adapter s certificates would not work as they identify a different party not you In a nutshell if you run a logical Sedex adapter and intend to use the Signing Outbox feature of MessageHandler v3 you must do the following 1 Install the digital certificate of your logical Sedex adapter in a separate location from the physical Sedex adapter certificates You probably did not install this one yet 2 When configuring the Signing Outbox specify the logical adapter s certificate as the signature certificate see 2 4 4 above Doing so ensures your organisation is the originator of a digitally signed PDF document Yet you will continue using the physical adapter and its certificates for Sedex messaging Now that you use two different digital certificates do not forget that one of them gets re newed automatically while the other will not U
18. ter and its certificates This you must understand when using the Signing Outbox feature in an eSchKG context 2 6 4 eSchKG Member Directory Although this is not a particular MessageHandler v3 issue the following is worth mentioning eSchKG Networking Red Book Edition March 2014 Page 10 The eSchKG member directory is published on the Internet and distributed to the mem bers using the SN message by the Federal Office of Justice The member directory is available in two formats Microsoft Excel and CSV See the eSchKG homepage on www eschkg ch and the specification of the SN Sequence in the Blue Book 2 7 MessageHandler Configuration Examples on the Web As anovelty MessageHandler v3 comes with a variety of typical configuration examples in www e service admin ch wiki display openegovdoc Online supplement You are highly encouraged to consult this site the example library was developed after years of experience of solving configuration issues with MessageHandler and Sedex 2 8 MessageHandler INBOX and OUTBOX At the time of writing the installation instructions in the Open eGov MessageHandler v3 Technical Documentation 2 are missing the point when the INBOX and OUTBOX directo ries have to be created Don t forget to create those directories they can be located any where see example directories below jb mh311 Ji bin amp conf E Jj lib J log 3 runtime J mh3114n je mh311 out E d mh311 signOut i processed i jJ
Download Pdf Manuals
Related Search