Limax Project

5.8 Data exchange between Providers

5.8.4 Client development

All kinds of clients support tunnel data forwarding.
- C++/C#/Java client, with Java version as example
  
  When implementing limax.endpoint.EndpointListener, implement limax.endpoint.TunnelSupport interface at the same time.
```
public interface TunnelSupport {
    void onTunnel(int providerid, int label, Octets data) throws Exception;
    void registerTunnelSender(TunnelSender sender);
}

public interface TunnelSender {
    void send(int providerid, int label, Octets data)
            throws InstantiationException, SizePolicyException, CodecException, ClassCastException;
}
```
  Implement onTunnel to receive the tunnel data sent from the server. The Limax framework determines that an Endpoint can connect to multiple Providers at the same time, and providerid here is used to distinguish. The onTunnel can be implemented as instant forwarding, or temporarily storing data (temporary storage duration can not exceed the validity of the configuration), then forwarding later.
  
  When Endpoint is initialized, registerTunnelSender will be called back. It must be implemented that the registerTunnelSender saves the tunnelSender of the current Endpoint, and then forwards the tunnel data on this tunnelSender.
  
  Usually, the client needs to use two Endpoint, EA and EB to separately connect to Provider on both sides of the tunnel. When EA.onTunnel receives the tunnel data, it is forwarded through EB.tunnelSender.
  
  It must be noted here that the providerid in the TunnelSupport.onTunnel is the id of the source Provider, and the providerid in the TunnelSender.send is the id of the destination Provider, which can not be directly forwared as label and data.
  
  Then Endpoint of TunnelSupport is not supported, ignoring the received tunnel data.
- Script client, with Javascript example
  
  When creating a Limax instance, the script client passes a function as the third parameter to support the tunnel data receiving.
```
var limax = Limax(function(ctx) {
ctx.onerror = function(e) {
    print('limax error', e);
}
ctx.onclose = function(e) {
    print('limax close', e);
}
ctx.onopen = function() {
    .........................
}
}, cache, function(pvid, label, data) {
});
```
  The Limax instance itself is a function that directly execute limax(pvid, label, data); to send tunnel data.
- Mixed client using ScriptEngineHandle (Java / javscript, C # / javascript, C # / Lua, C ++ / javascript, C ++ / Lua, various forms of minimalist client), with Java/javascript example
  
  Use the constructor with the TunnelReceiver parameter to create the corresponding ScriptHandle to receive the tunnel data.
```
new JavascriptHandle(new ScriptEngineManager().getEngineByName("javascript"),
    new InputStreamReader(Main.class.getResourceAsStream("example.js")), 
    null, 
    null,
    new TunnelReceiver() {
        @Override
        public void onTunnel(int providerid, int label, String data) {
            System.out.println(providerid + " " + label + " " + data);
        }
});
```
  The data here comes from the script system, so the type is String, which is the Base64 encoding result for Octets-type tunnel data.
  
  Observe the definition of the ScriptEngineHandle interface.
```
public interface ScriptEngineHandle {
    .......................
    void tunnel(int providerid, int label, String data) throws Exception;
    void tunnel(int providerid, int label, Octets data) throws Exception;
}
```
  The tunnel method on the ScriptEngineHandle can be called directly to send the tunnel data. The tunnel data from the scripting system is sent by using the method with the String parameter, and the tunnel data from TunnelSupport is sent by using the method with the Octets parameter.
  
  Notice:
  
  1. If the client's EndpointListener implements the TunnelSupport interface and uses the ScriptEngineHandle that supports the TunnelReceiver, the same tunnel data can be received in both places.
  
  2. If the client's EndpointListener recorded TunnelSender and used ScriptEngineHandle when implementing TunnelSupport, the both places can be used to send the tunnel data.

5.8.5 Operation management
- Configuration file
  
  In the Provider configuration file, add a Tunnel node in the Provider node.
```
<Provider ...>
    <Tunnel compressor="ZIP" keyProtector="HMACSHA256" defaultExpire="86400000" defaultGroup="prjA">
        <PKIX location="pkcs12:/work/keyalloc.p12" passphrase="123456" revocationCheckerOptions="SOFT_FAIL"/>
        <SharedKey group="prjA" key="123456" /> 
        <SharedKey group="prjB" key="123456" /> 
        <Expire group="prjA" value="3600"/>
    </Tunnel>
    <Manager .../>
    <Manager .../>
    ...
<'/Provider>
```
  4 attributes of Tunnel node:
  
  compressor : source data compression method, the optional values are NONE, RFC2118 and ZIP. The default is NONE. Please refer the appendix "External data".
  
  keyProtector : source data protection algorithm, the optional values are HMACSHA224, HMACSHA256, HMACSHA384, HMACSHA512, TripleDESCBC, and AESCBC128. The default is HMACSHA256. Please refer the appendix "External data".
  
  defaultExpire : tunnel data default expiration time, with milliseconds as unit. The default is 3600000. The expiration time must be configured less than key lifetime. Please refer the appendix "Key distribution system".
  
  defaultGroup : default trust domain.
  
  Tunnel node supports two kinds of nodes, PKIX and SharedKey. PKIX node has high priority. SharedKey node configured with PKIX node is ignored.
  
  Multiple PKIX nodes are configured. The first node is valid. The PKIX node is configured with Key distribution system client to require the Key distribution network to allocate Key to protect tunnel data.
  
  5 attributes of PKIX node:
  
  location : the location of provider certificate package.
  
  passphrase : the active password of location private key. In the actual operation, this attribute should not be filled, but should be entered as server launching.
  
  trustsPath : the trusted certificate path. The location includes the ROOTCA derivated from this certificate. If it needs to trust the other ROOTCA (or the current ROOTCA will expire soon, the new ROOTCA should be placed here), it should configure the trustsPath. The trustsPath can be a file or a directory. If it is a directory, traverse one level, and get the file. The file allows any certificate format, including CER, DER, PKCS7, PKCS12, and KeyStore, from which the ROOTCA is obtained, ignoring all errors.
  
  revocationCheckerOptions：the option that the server checks the certificate recovery status of the peer. The optional values are DISABLE, NO_FALLBACK, ONLY_END_ENTITY, PREFER_CRLS, and SOFT_FAIL. Case is not sensitive. The definitions of the last four parameters refer to java.security.cert.PKIXRevocationChecker.Option. The DISABLE has the highest priority. If the DISABLE is configured, the other configuration has no meaning.
  
  httpsHost : specify the particular entrance server IP or domain name in the key distribution system. If not configure this attribute, the domain name provided by the provider certificate is used.
  
  After the PKIX node configuration is initialized, a set of trusted domains is extracted from the Provider certificate to verify the defaultGroup configuration. If defaultGroup is configured, the defaultGroup must exist in the set, or a runtime exception is thrown. If no defaultGroup is configured, one is selected from the set as defaultGroup.
  
  In the condition without PKIX node, the configuration of the SharedKey node is used. Multiple SharedKey nodes are allowed, statically configuring trust domain and corresponding key. SharedKey configuration mode does not use Key distribution system for debugging environment, or extremely simple application scenarios.
  
  2 attributes of SharedKey node:
  
  group : the name of trusted domain
  
  key : the key of trusted domain
  
  After all SharedKey configurations are initialized, a set of static trusted domain is generated. If defaultGroup is configured, defaultGroup must exist in the set, or a runtime exception is thrown. If no defaultGroup is configured, one is selected from the set as defaultGroup.
  
  2 attributes of Expire node:
  
  group: trusted domain name
  
  value: expiration time
  
  The Expire node allows fine configuration for the tunnel data expiration time of a particular trusted domain.
- Runtime considerations
  
  1. Run the ntp service, synchronize provider clock.
  
  2. Configure the correct dns service.
  
  3. Configure the trustsPath according to the requirement of CA, add the extra ROOTCA provided by CA.
  
  4. Turn on the firewall, and allow the 443 destination port to ensure the connectivity between the CAServer and Key distribution network.

5.8.6 Advanced topic
- Application data organization
  
  1. The data exchange framework between Provider does not consider the specific application data, focusing on forwarding Octets.
  
  2. The Provider in the trusted domain should design a private exchangeable data structure, and it is the ideal way to use xml description to generate the public bean to exchange.
  
  3. If there are multiple public beans, the type field should be designed to distinguish. In simple case, consider to use label to distinguish type.
  
  4. Using JSON to represent user data is a variable option. The JSON string can unifiedly getBytes by UTF8, then wrap to Octets.
  
  5. In the case that the size of application data may be larger, the configuration of compressor is preferred.
- The size of tunnel data
  
  1. The tunnel data is sent via a specific protocol.
  
  2. For the consideration of server’s anti-attack, the virtual machine parameter limax.net.Engine.limitProtocolSize limits the maximum size of protocol as 1M. The size of tunnel data can not exceed this constraint. Otherwise, there is error when destination server resolves the protocol.
  
  3. The client trusts the server, so the client does not limit the size of data.
  
  4. For large amounts of data, consider the way of multiple sending.
- Whose data is tunneled
  
  1. Carefully plan its’ own negotiation process of application, and decide whose data is tunneled.
  
  2. In most cases, forward the user’s own data through the tunnel.
  
  3. In certain case, it can be transmitted through third parties that have no conflicts of interest. At this time, the actual sessionid is packaged into the application data. After decoding to obtain this sessionid, for thread-safe handling, View.schedule(sessionid, task) should be used to schedule subsequent tasks to the thread corresponding to sessionid.
  
  4. For the consideration to avoid the firewall, a dedicated client can be designed and deployed in the network with good connectivity to forward the data between Providers.

Prev Next

5.8 Data exchange between Providers

5.8.4 Client development

5.8.5 Operation management

5.8.6 Advanced topic