Skip to content

Latest commit

 

History

History
342 lines (256 loc) · 18.1 KB

README.md

File metadata and controls

342 lines (256 loc) · 18.1 KB
Raw

Client / demo application for #EET - etrzby.cz

example workflow Codecov Jitpack

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

3rd generation

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

Usage

Demo project on github.com/todvora/eet-client-demo.

ClientKey clientKey = ClientKey.fromInputStream(getClass().getResourceAsStream("/keys/CZ683555118.p12"), "eet");
ServerKey serverKey = ServerKey.trustingEmbeddedCertificates();
EETClient client = EETServiceFactory.getInstance(clientKey, serverKey);

TrzbaDataType data = new TrzbaDataType()
        .withDicPopl("CZ683555118")
        .withIdProvoz(243)
        .withIdPokl("24/A-6/Brno_2")
        .withPoradCis("#135433c/11/2016")
        .withDatTrzby(new Date())
        .withCelkTrzba(new BigDecimal("3264"));

try {
    TrzbaType request = eetService.prepareFirstRequest(data, CommunicationMode.REAL);
    SubmitResult result = eetService.sendSync(request, EndpointType.PLAYGROUND);
    // print codes on the receipt
    System.out.println("FIK:" + result.getFik());
    System.out.println("BKP:" + result.getBKP());
} catch (final CommunicationTimeoutException e) {
    // timeout occurred, resend later again
    System.out.println("PKP:" + e.getPKP());
    System.out.println("BKP:" + e.getBKP());
    // get other data from the request
    System.out.println(e.getRequest().getData().getDatTrzby());
} catch (final CommunicationException e) {
    // resend, if fails again, print PKP on the receipt
    System.out.println("PKP:" + e.getPKP());
    System.out.println("BKP:" + e.getBKP());
    // get other data from the request
    System.out.println(e.getRequest().getData().getDatTrzby());
}

Asynchronous call with a callback:

TrzbaType request = eetClient.prepareFirstRequest(data, CommunicationMode.REAL);
eetClient.sendAsync(request, EndpointType.PLAYGROUND, new ResponseCallback() {
    @Override
    public void onComplete(final SubmitResult result) {
        System.out.println("FIK:" + result.getFik());
    }
    @Override
    public void onError(final CommunicationException e) {
        System.out.println("PKP:" + e.getPKP());
    }
    @Override
    public void onTimeout(final CommunicationTimeoutException cause) {
       System.out.println("PKP:" + e.getPKP());
    }
});

Additional resources

Professional support

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

Request signing

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, some test keys have been published. Those keys are used in integration tests of this demo app.

The signing itself complies with WS-Security. There is a WSS4JOutInterceptor configured, which handles signing, key embedding, hashing algorithms selection and so one.

Response verification

Response signature

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.

For production

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 from http://www.ica.cz/HCA-root-en and http://www.ica.cz/HCA-qualificate

For playground

You can download it here or go to http://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 the EETServiceFactory#getInstance method call.

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

CommunicationMode EndpointType Valid message? Is response signed?
REAL PRODUCTION true yes (prod.cert)
REAL PRODUCTION false no
REAL PLAYGROUND true yes (test cert)
REAL PLAYGROUND false no
TEST PRODUCTION true no
TEST PRODUCTION false no
TEST PLAYGROUND true no
TEST PLAYGROUND false no

see the original table from documentation

Validation

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

Certificate revocation

The client application should verify, that EET public certificate has not been revoked. To do that, either CRL or OCSP should be used. I.CA is the EET's certificate authority. They provide CRL on http://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 this news 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 the MerlinWithCRLDistributionPointsExtension implementation for details.

WS-Policy

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 see #1. See also diff 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.

Installation

Maven

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

Manually

Download latest release eet-client-X.Y.jar from Github Releases. Add it to your classpath, together with all dependencies included in eet-client-X.Y-dependencies.zip archive, located also in Github 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.

Java version

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
  • OpenJDK 8
  • OpenJDK 10
  • OpenJDK 11

For following JDK versions please stay on 3.0.0 release:

  • 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!

Java Cryptography Extension (JCE) Unlimited Strength

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 for Java 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.

How do I know, that I need to install JCE?

You will see in logs exceptions like:

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

Certificate expiration

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 all keys up-to-date and get new versions before they expire.

Server certificates

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 use ServerKey.trustingEmbeddedCertificates(); for obtaining server keys, all you need to do is to update this eet-client library version in time, before the first certificate expires. If you provide certificates on your own, you don't have to update the lib, only the certificate itself.

Client Keys

Client keys you have got following this 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 this library perspective, it is this call: ClientKey.fromInputStream(someStream, "your-password").

Warning format

The eet-client library will warn you 30 days ahead that some of your certificates is going to expire. You will see in logs 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
##################

Development, debugging, logging

Application logging

This client has extended logging of both internal information and webservice communication. Logs are persisted inside logs/ 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 own log4j2 configuration file and provide path to it in the following system property:

-Dlog4j.configurationFile=log4j2-custom.xml

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

SSL and handshake logging

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 on Debugging SSL/TLS Connections

Certificates and keys debugging

Add following system property to your java command

    -Djava.security.debug=certpath

More on Troubleshooting Security

Request duration logging

Every request is measured and the library collects time logs. They are stored as timing.csv inside logs 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_1
2016-11-11T15:35:23+01:00;253;https://pg.eet.cz:443/eet/services/EETServiceSOAP/v3;id_2
2016-11-11T15:35:23+01:00;247;https://pg.eet.cz:443/eet/services/EETServiceSOAP/v3;id_3
2016-11-11T15:35:23+01:00;244;https://pg.eet.cz:443/eet/services/EETServiceSOAP/v3;id_4
2016-11-11T15:35:24+01:00;242;https://pg.eet.cz:443/eet/services/EETServiceSOAP/v3;id_5

News, discussions

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

Similar projects

TODO and to decide

  • 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?

License

MIT License

Copyright (c) 2016 Tomas Dvorak

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, 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 THE
SOFTWARE.

(See a human readable explanation of the MIT license).