Repository files navigation

Simple java client for submission of receipts to the central registry at eet.cz.

It solves following topics:

• Keys and certificates import
• Webservice communication
• Computation of verification codes PKP and BKP
• Signing of requests (WS-Security)
• Validating of responses (WS-Security)

Implementer has to take care of:

• Provide InputStream to a valid pkcs12 keystore with client keys
• Errors handling
• Resubmission, in case of failure

This is the 3rd generation of Java client. Latest release of 2nd generation is2.3.0.Difference between 2nd and 3rd generation is mainly simpler certificates handling, easier resubmission handling,tools for serialization and deserialization of requests.

Demo project ongithub.com/todvora/eet-client-demo.

ClientKeyclientKey =ClientKey.fromInputStream(getClass().getResourceAsStream("/keys/CZ683555118.p12"),"eet");ServerKeyserverKey =ServerKey.trustingEmbeddedCertificates();EETClientclient =EETServiceFactory.getInstance(clientKey,serverKey);TrzbaDataTypedata =newTrzbaDataType()        .withDicPopl("CZ683555118")        .withIdProvoz(243)        .withIdPokl("24/A-6/Brno_2")        .withPoradCis("#135433c/11/2016")        .withDatTrzby(newDate())        .withCelkTrzba(newBigDecimal("3264"));try {TrzbaTyperequest =eetService.prepareFirstRequest(data,CommunicationMode.REAL);SubmitResultresult =eetService.sendSync(request,EndpointType.PLAYGROUND);// print codes on the receiptSystem.out.println("FIK:" +result.getFik());System.out.println("BKP:" +result.getBKP());}catch (finalCommunicationTimeoutExceptione) {// timeout occurred, resend later againSystem.out.println("PKP:" +e.getPKP());System.out.println("BKP:" +e.getBKP());// get other data from the requestSystem.out.println(e.getRequest().getData().getDatTrzby());}catch (finalCommunicationExceptione) {// resend, if fails again, print PKP on the receiptSystem.out.println("PKP:" +e.getPKP());System.out.println("BKP:" +e.getBKP());// get other data from the requestSystem.out.println(e.getRequest().getData().getDatTrzby());}

Asynchronous call with a callback:

TrzbaTyperequest =eetClient.prepareFirstRequest(data,CommunicationMode.REAL);eetClient.sendAsync(request,EndpointType.PLAYGROUND,newResponseCallback() {@OverridepublicvoidonComplete(finalSubmitResultresult) {System.out.println("FIK:" +result.getFik());    }@OverridepublicvoidonError(finalCommunicationExceptione) {System.out.println("PKP:" +e.getPKP());    }@OverridepublicvoidonTimeout(finalCommunicationTimeoutExceptioncause) {System.out.println("PKP:" +e.getPKP());    }});

• Maven project info, containing all dependencies information:https://todvora.github.io/eet-client/latest/project-info.html
• Javadoc:https://todvora.github.io/eet-client/latest/apidocs/index.html
• Releases:https://github.com/todvora/eet-client/releases
• Continuous integration test results:https://travis-ci.org/todvora/eet-client
• Code coverage:https://codecov.io/github/todvora/eet-client/

Support during implementation or specific features required? No problem! Write me attodvora@gmail.com.You will donate toMédecins Sans Frontières and I will help you out with the #EET.

Every request has to be signed with a client's key. The key will be provided by EET (see how and where). For the demo application and playground environment, sometest keys have been published. Those keys are used in integration tests of this demo app.

The signing itself complies withWS-Security. There is aWSS4JOutInterceptor configured, which handles signing, key embedding, hashing algorithms selection and so one.

SOAP responses are signed by a certificate issued for:

• Production:O=Česká republika - Generální finanční ředitelství, C=CZ, CN=Elektronická evidence tržeb
• Playground:O=Česká republika - Generální finanční ředitelství, CN=Elektronická evidence tržeb - Playground, C=CZ

To be able to validate the signature, the root certificate(s) for the I.CA has to be present. There are two sets of CA certificates.

You need two certificates - root CA certificate and subordinate CA cert.

• rca15_rsa.der (Qualified system certificate root CA (CN = I.CA Root CA/RSA, sn: 100000000/0x5f5e100)).
• 2qca16_rsa.der Qualified system certificate subordinate QCA (CN = I.CA Qualified 2 CA/RSA 02/2016 sn: 100001006/0x5f5e4ee)

You can download them directly from links above or fromhttp://www.ica.cz/HCA-root-en andhttp://www.ica.cz/HCA-qualificate

You can download ithereor go tohttp://www.ica.cz/CA-pro-kvalifikovane-sluzby and download the SHA-2 DER variant.

Besides different certificates, everything is the same for both production and playground env.

This CA certificate(s) has to be provided as the third (and fourth) parameter in theEETServiceFactory#getInstance method call.

There is a pretty complicated logic, which decides, when the response is signed. Following table summarizes it:

see the original table from documentation

WSS4JInInterceptor handles response validation. It's configured to verify signature against I.CA root certificate, checks CRL and handles all the obscure cases, where message is deliberately unsigned (see the table above).

The client application should verify, that EET public certificate has not been revoked. To do that, eitherCRL orOCSP should be used.I.CA is the EET's certificate authority. They provide CRL onhttp://q.ica.cz/cgi-bin/crl_qpub.cgi?language=cs&snIssuer=10500000 for manual download (captcha is required). I.CA should also provide OCSP, as stated in thisnews article[2011, czech].

Current implementation of this client is based on CRL Distribution Points provided in the EET certificate itself.

The client reads the provided certificate (sent along with the response) downloads CRLs and checks the EET certificate validity against them. CLR has to have an update interval configured. The client caches CRL in memory and updates it when needed. See theMerlinWithCRLDistributionPointsExtension implementation for details.

WS-Policy is a specification that allows web services to use XML to advertise their policies (on security, quality of service, etc.) and for web service consumers to specify their policy requirements.(from Wikipedia)

EET WSDL contained ws-policy with security constraints defined till EET interface version 2. This definition has been removed in version 3. Every developer is now required to take care of setting security configuration manually, following official documentation of EET.

For more details seetodvora#1. See alsodiff between versions 2. and 3. of EET WSDL.

Note: It doesn't affect you as an user of this EET client, is important only for a green field implementations of EET webservice consumers.

If you want to use this library as a dependency in your Maven based project, follow instructions provided onjitpack.io. There is currently no maven central release.

Download latest releaseeet-client-X.Y.jar fromGithub Releases. Add it to your classpath, together withall dependencies included ineet-client-X.Y-dependencies.zip archive, located also inGithub Releases.(Dependencies should be extracted from the zip archive first and then added to classpath).

Dependencies archive is generated automatically with every release and contains all dependencies required by eet-client.

Since EET client has to deal with lots of encryption and security, up-to-date version of Java should be used.

Supported and tested are following versions:

• Oracle JDK 8
• Oracle JDK 7
• OpenJDK 7
• OpenJDK 6

Oracle Java 6 is after its end-of-life and doesn't provide required TLSv1.1 implementation for secure communication. Thus it's not possible to run this EET client on Oracle Java 6!

The production communication requires unlimited cryptography strength. If you are Open JDK / Open JRE user, you don't have to worry about that. Oracle users have to follow these steps:

• Download Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy File from Oracle website (direct links forJava 7,Java 8).
• Unzip the downloaded archive.
• Copy local_policy.jar and US_export_policy.jar to the$JAVA_HOME/jre/lib/security (overriding existing jars).

Exact information and instalation details are also in README.txt in the downloaded archives.

You will see in logs exceptions like:

java.io.IOException: exception unwrapping private key - java.security.InvalidKeyException: Illegal key size

The whole communication relies on private/public key cryptography. All keys have some validity interval defined.If they expire, they will be no more trusted and accepted. Thus it's important to keep allkeys up-to-date and get new versions before they expire.

For server side keys it means re-download of CA keys used for checking validity of server response.Current certificates have following expiration dates:

• 2qca16_rsa.der (production, playground): 2026-02-08T13:17:11+01:00
• rca15_rsa.der (production, playground): 2040-05-27T14:20:00+02:00

If you useServerKey.trustingEmbeddedCertificates(); for obtaining server keys, all you need to do is to updatethis eet-client library version in time, before the first certificate expires. If you provide certificateson your own, you don't have to update the lib, only the certificate itself.

Client keys you have got followingthis steps have validity of 3 years.So you will need to re-download them probably in 2019/2020 if you started with EET in first batches.

After you get new certificates, they will have to be inserted again into your POS application. From thislibrary perspective, it is this call:ClientKey.fromInputStream(someStream, "your-password").

The eet-client library will warn you 30 days ahead that some of your certificates is going to expire. You will see inlogs following message (under WARNING level of Slf4j):

#### WARNING ####Following certificate expires on 2019-09-01T02:00:00+02:00!{subject='OU=I.CA - Accredited Provider of Certification Services, O="První certifikační autorita, a.s.", CN="I.CA - Qualified Certification Authority, 09/2009", C=CZ', issuer='OU=I.CA - Accredited Provider of Certification Services, O="První certifikační autorita, a.s.", CN="I.CA - Qualified Certification Authority, 09/2009", C=CZ', SerialNumber=10500000, validFrom=2009-09-01T02:00:00+02:00, validTo=2019-09-01T02:00:00+02:00}Please update your certificate as soon as possible. More info on https://github.com/todvora/eet-client#certificate-expiration##################

This client has extended logging of both internal information and webservice communication.Logs are persisted insidelogs/ directory under current working directory (usually your app or workspace dir).Logs are rotated on date and file size basis, to be able to read and process them easily.

See

• logs/all.log - all produced logs from the app, containing also webservice requests and responses
• logs/webservice.log - only webservice communication, requests and responses

If you want to change the configuration of the logging, simply create your ownlog4j2 configuration file andprovide path to it in the following system property:

-Dlog4j.configurationFile=log4j2-custom.xml

you can copy and adaptthe current configuration file to your needs for that.

To print debugging information regarding SSL connection to EET servers, add following system property to your java command:

-ea -Djavax.net.debug=ssl,handshake

More onDebugging SSL/TLS Connections

Add following system property to your java command

    -Djava.security.debug=certpath

More onTroubleshooting Security

Every request is measured and the library collects time logs. They are stored astiming.csv insidelogs directory.Every row contains current date and time, endpoint url, request ID (to be able to compare timing with request/response data inside webservice.log) and finally request duration in millis.
For example:

2016-11-11T15:35:22+01:00;1143;https://pg.eet.cz:443/eet/services/EETServiceSOAP/v3;id_12016-11-11T15:35:23+01:00;253;https://pg.eet.cz:443/eet/services/EETServiceSOAP/v3;id_22016-11-11T15:35:23+01:00;247;https://pg.eet.cz:443/eet/services/EETServiceSOAP/v3;id_32016-11-11T15:35:23+01:00;244;https://pg.eet.cz:443/eet/services/EETServiceSOAP/v3;id_42016-11-11T15:35:24+01:00;242;https://pg.eet.cz:443/eet/services/EETServiceSOAP/v3;id_5

To follow latest news about #EET, join us ongitter.im/eet-client.

• https://github.com/ondrejnov/eet (PHP, MIT license)
• https://github.com/novakmi/eetlite (Groovy, MIT license)
• https://github.com/l-ra/openeet (Java, C#, UNIX shell, Apache 2.0 license)
• https://github.com/mirus77/DelphiEET (Delphi, MIT license)
• https://drive.google.com/drive/folders/0B2B4_OfsI25paTB2R0NNM1hqMzg (C#, unknown license)
• https://github.com/JakubMrozek/eet (Node.js, MIT license)
• https://github.com/MewsSystems/eet (C#, MIT License)
• https://github.com/slevomat/eet-client (PHP, MIT License)
• https://github.com/charlieMonroe/SwiftEET (Swift, GPL-3.0)

• Should be the I.CA root certificate downloaded automatically or provided by the implementer? IMHO no, not secure enough.
• Should the I.CA root be added to the default JVM truststore?
• Create demo project, using this client as a dependency
• Run integration tests on travis-ci (apparently blocked travis's IP/range to the WS by EET server itself)
• Security review - is everything as correct as possible?

MIT LicenseCopyright (c) 2016 Tomas DvorakPermission is hereby granted, free of charge, to any person obtaining a copyof this software and associated documentation files (the "Software"), to dealin the Software without restriction, including without limitation the rightsto use, copy, modify, merge, publish, distribute, sublicense, and/or sellcopies of the Software, and to permit persons to whom the Software isfurnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in allcopies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THESOFTWARE.

(See ahuman readable explanation of the MIT license).