Merge pull request #6 from krisleonard-mcafee/master

Add proxy support and migrate to paho.mqtt.java 1.2.1

.gitmodules

@@ -1,4 +1,4 @@
 [submodule "paho.mqtt.java"]
 	path = paho.mqtt.java
 	url = https://github.com/opendxl-community/paho.mqtt.java.git
-	branch = opendxl-modifications
+	branch = opendxl-modifications-merge-1.2.1

.travis.yml

@@ -10,17 +10,40 @@ jdk:
   - oraclejdk8
 
 before_install:
+  - sudo apt-get update
+  - sudo apt-get install -y apache2-utils
   - docker pull opendxl/opendxl-broker
-  - docker run -d -p 127.0.0.1:8883:8883 -p 127.0.0.1:8443:8443 -p 127.0.0.1:443:443 opendxl/opendxl-broker
+  - docker pull sameersbn/squid
+  - docker run -d -p 8883:8883 -p 8443:8443 -p 443:443 opendxl/opendxl-broker
+  - docker ps -a
+  - mkdir squid-proxy-cache
+  - htpasswd -b -c ${TRAVIS_BUILD_DIR}/testing/passwords proxyuser proxypassword
+  - cat ${TRAVIS_BUILD_DIR}/testing/passwords
+  - docker run --name squid -d --restart=always --publish 3128:3128 --volume ${TRAVIS_BUILD_DIR}/testing/squid.conf:/etc/squid/squid.conf --volume ${TRAVIS_BUILD_DIR}/testing/passwords:/etc/squid/passwords --volume ${TRAVIS_BUILD_DIR}/squid-proxy-cache:/var/spool/squid sameersbn/squid
   - docker ps -a
 
 script:
-  - java -jar ./build/libs/dxlclient*all.jar provisionconfig clientconfig 127.0.0.1 client -u admin -p password
+  - ip4=$(/sbin/ip -o -4 addr list eth0 | awk '{print $4}' | cut -d/ -f1)
+  - docker ps
+  - java -Dhttps.proxyHost=${ip4} -Dhttps.proxyPort=3128 -Dhttps.proxyUser=proxyuser -Dhttps.proxyPassword=proxypassword -jar ./build/libs/dxlclient*all.jar provisionconfig clientconfig ${ip4} client -u admin -p password
   - sed -i -e "s/127.0.0.1;127.0.0.1/127.0.0.1/g" -e "/local/d" -e "/docker/d" clientconfig/dxlclient.config
   - cat clientconfig/dxlclient.config
   - echo Running tests with MQTT
   - ./gradlew test --info --console=plain
-  - sed -i -e "s/= false/= true/g" -e "s/;8883/;443/g" -e "s/Brokers/BrokersWebSockets/g"  clientconfig/dxlclient.config
+  - sed -i -e "s/= false/= true/g" clientconfig/dxlclient.config
+  - cat clientconfig/dxlclient.config
+  - echo Running tests with WebSockets and no proxy
+  - ./gradlew cleanTest test --info --console=plain
+  - echo Updating dxlclient.config to include proxy information
+  - echo "[Proxy]" >> clientconfig/dxlclient.config
+  - echo "Address=${ip4}" >> clientconfig/dxlclient.config
+  - echo "Port=3128" >> clientconfig/dxlclient.config
+  - echo "User=proxyuser" >> clientconfig/dxlclient.config
+  - echo "Password=proxypassword" >> clientconfig/dxlclient.config
   - cat clientconfig/dxlclient.config
-  - echo Running tests with WebSockets
+  - echo Running Proxy Usage Verification Test
+  - ./gradlew proxyUsageVerificationTest
+  - docker exec -it squid tail /var/log/squid/access.log
+  - echo Running tests with WebSockets and authenticated proxy
   - ./gradlew cleanTest test --info --console=plain
+  - docker exec -it squid tail /var/log/squid/access.log

build.gradle

@@ -256,8 +256,17 @@ assemble.dependsOn(replaceVersionInREADME)
 
 test {
     systemProperty 'clientConfig', "${rootDir}/clientconfig/dxlclient.config"
+
+    // Exclude the Proxy Usage Verification Test
+    exclude "**/ProxyUsageVerificationTest.class"
 //    filter {
 //        //specific test method
 //        includeTestsMatching "com.opendxl.client.RegisterServiceTest"
 //    }
 }
+
+// Task for verifying proxy usage
+task proxyUsageVerificationTest(type:Test) {
+    systemProperty 'clientConfig', "${rootDir}/clientconfig/dxlclient.config"
+    include "**/ProxyUsageVerificationTest.class"
+}

clientconfig/dxlclient.config.template

@@ -18,3 +18,13 @@ unique_broker_id_1=unique_broker_id_1;@BROKER_PORT@;@BROKER_HOSTNAME@;@BROKER_IP
 
 [BrokersWebSockets]
 unique_websocket_broker_id_1=unique_websocket_broker_id_1;@BROKER_WEBSOCKET_PORT@;@BROKER_HOSTNAME@;@BROKER_IP@
+
+# The [Proxy] section is optional and only applies to WebSocket connections. This section
+# will not be used when the OpenDXL Java Client connects to a DXL Broker via MQTT. It should be used when the
+# OpenDXL Java Client WebSocket connection to a DXL Broker must be routed through a proxy. The user and password
+# settings are not required if the proxy does not require authentication.
+[Proxy]
+Address=<Proxy host name or IP address>
+Port=<Proxy port>
+User=<User name required for authentication with the Proxy>
+Password=<Password required for authentication with the Proxy>

config/checkstyle/checkstyle.xml

@@ -66,6 +66,11 @@
         <!-- See http://checkstyle.sf.net/config_sizes.html -->
         <module name="LineLength">
             <property name="max" value="120"/>
+            <!--
+            Ignore Javadoc comments since references to other elements (@see
+            tag, etc.) may get rather long and should not be truncated.
+            -->
+            <property name="ignorePattern" value="^\s*\*\s*[^\s]+.+$"/>
         </module>
         <module name="MethodLength">
             <property name="max" value="200"/>

docs/advancedcliprovisioning.rst

@@ -8,6 +8,19 @@ Refer to :doc:`basiccliprovisioning` for basic usage details.
 
 .. _subject-attributes-label:
 
+Routing provisioning operation through a proxy
+**********************************************
+
+If the remote call to a provisioning server (ePO or OpenDXL Broker) must be routed through a proxy, then use standard Java system
+properties to declare the https proxy host, port, user name, and password. (`<https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html>`_)
+
+For example:
+
+    .. parsed-literal::
+
+        java -Dhttps.proxyHost=proxy.mycompany.com -Dhttps.proxyPort=3128 -Dhttps.proxyUser=proxyUser -Dhttps.proxyPassword=proxyPassword -jar dxlclient-\ |version|\-all.jar provisionconfig config myserver client1
+
+
 Additional Certificate Signing Request (CSR) Information
 ********************************************************
 

docs/conf.py

@@ -3,7 +3,7 @@
 from recommonmark.parser import CommonMarkParser
 
 project = u'OpenDXL Java SDK'
-copyright = u'2018, McAfee LLC'
+copyright = u'2019, McAfee LLC'
 
 with open('../VERSION', 'r') as content_file:
     VERSION = content_file.read()

docs/epoexternalcertissuance.rst

@@ -51,6 +51,12 @@ The following steps walk through the process of populating this file:
            unique_websocket_broker_id_1=unique_websocket_broker_id_1;broker_websocket_port_1;broker_hostname_1;broker_ip_1
            unique_websocket_broker_id_2=unique_websocket_broker_id_2;broker_websocket_port_2;broker_hostname_2;broker_ip_2
 
+           [Proxy]
+           Address=<Proxy host name or IP address>
+           Port=<Proxy port>
+           User=<User name required for authentication with the Proxy>
+           Password=<Password required for authentication with the Proxy>
+
 2. Optionally update the ``UseWebSockets`` value to indicate if the OpenDXL Java Client should connect to DXL Brokers
    via WebSockets. This flag will override the default behavior which is the following:
 
@@ -85,6 +91,12 @@ The following steps walk through the process of populating this file:
            unique_websocket_broker_id_1=unique_websocket_broker_id_1;broker_websocket_port_1;broker_hostname_1;broker_ip_1
            unique_websocket_broker_id_2=unique_websocket_broker_id_2;broker_websocket_port_2;broker_hostname_2;broker_ip_2
 
+           [Proxy]
+           Address=<Proxy host name or IP address>
+           Port=<Proxy port>
+           User=<User name required for authentication with the Proxy>
+           Password=<Password required for authentication with the Proxy>
+
 4. Update the ``BrokerCertChain`` value to point to the Broker Certificates file (``brokercerts.crt``)
    that was created when exporting the Broker Certificates.
 
@@ -110,6 +122,12 @@ The following steps walk through the process of populating this file:
            unique_websocket_broker_id_1=unique_websocket_broker_id_1;broker_websocket_port_1;broker_hostname_1;broker_ip_1
            unique_websocket_broker_id_2=unique_websocket_broker_id_2;broker_websocket_port_2;broker_hostname_2;broker_ip_2
 
+           [Proxy]
+           Address=<Proxy host name or IP address>
+           Port=<Proxy port>
+           User=<User name required for authentication with the Proxy>
+           Password=<Password required for authentication with the Proxy>
+
 5. Update the ``[Brokers]`` and ``[BrokersWebSockets]`` sections to include the contents of the broker
    list file (``brokerlist.properties``) that was created when exporting the Broker List.
 
@@ -135,4 +153,41 @@ The following steps walk through the process of populating this file:
            {5d73b77f-8c4b-4ae0-b437-febd12facfd4}={5d73b77f-8c4b-4ae0-b437-febd12facfd4};443;mybroker.mcafee.com;192.168.1.12
            {24397e4d-645f-4f2f-974f-f98c55bdddf7}={24397e4d-645f-4f2f-974f-f98c55bdddf7};443;mybroker2.mcafee.com;192.168.1.13
 
-6. At this point you can run the samples included with the Java SDK.
+           [Proxy]
+           Address=<Proxy host name or IP address>
+           Port=<Proxy port>
+           User=<User name required for authentication with the Proxy>
+           Password=<Password required for authentication with the Proxy>
+
+6. Optionally update the ``[Proxy]`` section to have the required host name or IP address, port, user name, and 
+   password of the proxy that WebSocket connections to DXL Brokers will be routed through. These settings are only
+   used when the OpenDXL Java Client will make WebSocket connections to DXL Brokers. The ``User`` and ``Password``
+   values not required if the proxy does not require authentication.
+
+   After completing this step the contents of the configuration file should look similar to:
+
+       .. parsed-literal::
+
+          [General]
+          UseWebSockets=false
+
+          [Certs]
+          BrokerCertChain=c:\\certificates\\brokercerts.crt
+          CertFile=c:\\certificates\\client.crt
+          PrivateKey=c:\\certificates\\client.key
+
+          [Brokers]
+          {5d73b77f-8c4b-4ae0-b437-febd12facfd4}={5d73b77f-8c4b-4ae0-b437-febd12facfd4};8883;mybroker.mcafee.com;192.168.1.12
+          {24397e4d-645f-4f2f-974f-f98c55bdddf7}={24397e4d-645f-4f2f-974f-f98c55bdddf7};8883;mybroker2.mcafee.com;192.168.1.13
+
+          [BrokersWebSockets]
+          {5d73b77f-8c4b-4ae0-b437-febd12facfd4}={5d73b77f-8c4b-4ae0-b437-febd12facfd4};443;mybroker.mcafee.com;192.168.1.12
+          {24397e4d-645f-4f2f-974f-f98c55bdddf7}={24397e4d-645f-4f2f-974f-f98c55bdddf7};443;mybroker2.mcafee.com;192.168.1.13
+
+          [Proxy]
+          Address=proxy.mycompany.com
+          Port=3128
+          User=proxyUser
+          Password=proxyPassword
+
+7. At this point you can run the samples included with the Java SDK.

docs/index.rst

@@ -50,6 +50,13 @@ External Certificate Authority (CA)
 
         epoexternalcertissuance
 
+WebSocket and Proxy Support
+    .. toctree::
+        :maxdepth: 1
+
+        websocketsupport
+        proxysupport
+
 API Documentation
 -----------------
 

docs/proxysupport.rst

@@ -0,0 +1,41 @@
+Proxy Support
+=============
+
+To have the OpenDXL Java Client connect to DXL Brokers via a proxy set ``UseWebSockets`` setting to ``true`` and set
+the proxy host name or IP address, port, user name, and password in the ``dxlclient.config`` file under the
+``[Proxy]`` section. The ``[Proxy]`` is optional and if it does not exist or the values under it are blank in the
+``dxlclient.config``, then the OpenDXL Java Client will not use a proxy when connecting to the DXL Brokers listed under
+the ``[BrokersWebSockets]`` section. The ``User`` and ``Password`` settings are only required if the proxy requires
+authentication.
+
+       .. parsed-literal::
+
+          [General]
+          UseWebSockets=true
+
+          [Certs]
+          BrokerCertChain=c:\\certificates\\brokercerts.crt
+          CertFile=c:\\certificates\\client.crt
+          PrivateKey=c:\\certificates\\client.key
+
+          [Brokers]
+          {5d73b77f-8c4b-4ae0-b437-febd12facfd4}={5d73b77f-8c4b-4ae0-b437-febd12facfd4};8883;mybroker.mcafee.com;192.168.1.12
+          {24397e4d-645f-4f2f-974f-f98c55bdddf7}={24397e4d-645f-4f2f-974f-f98c55bdddf7};8883;mybroker2.mcafee.com;192.168.1.13
+
+          [BrokersWebSockets]
+          {5d73b77f-8c4b-4ae0-b437-febd12facfd4}={5d73b77f-8c4b-4ae0-b437-febd12facfd4};443;mybroker.mcafee.com;192.168.1.12
+          {24397e4d-645f-4f2f-974f-f98c55bdddf7}={24397e4d-645f-4f2f-974f-f98c55bdddf7};443;mybroker2.mcafee.com;192.168.1.13
+
+          [Proxy]
+          Address=proxy.mycompany.com
+          Port=3128
+          User=proxyUser
+          Password=proxyPassword
+
+.. note::
+
+    In order to use the ``[Proxy]`` section settings, the ``UseWebSockets`` setting must also be set to ``true``. The
+    OpenDXL Java Client will only use proxy settings when connecting to DXL Brokers via WebSockets.
+
+
+

docs/updatingconfigfromcli.rst

@@ -94,3 +94,16 @@ The name of the truststore file should be supplied along with the option:
 
         Ensure that the ``-all`` version of the dxlclient ``.jar`` file is specified.
 
+Routing client configuration update operation through a proxy
+*************************************************************
+
+If the remote call to a provisioning server (ePO or OpenDXL Broker) used during a client configuration update must be
+routed through a proxy, then use standard Java system properties to declare the https proxy host, port, user name,
+and password. (`<https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html>`_)
+
+For example:
+
+    .. parsed-literal::
+
+        java -Dhttps.proxyHost=proxy.mycompany.com -Dhttps.proxyPort=3128 -Dhttps.proxyUser=proxyUser -Dhttps.proxyPassword=proxyPassword -jar dxlclient-\ |version|\-all.jar updateconfig config myserver
+

docs/websocketsupport.rst

@@ -0,0 +1,36 @@
+WebSocket Support
+=================
+
+The OpenDXL Java Client will connect to DXL Brokers via WebSockets when the ``UseWebSockets`` setting is set to ``true``
+in the ``dxlclient.config`` file.
+
+       .. parsed-literal::
+
+          [General]
+          UseWebSockets=true
+
+          [Certs]
+          BrokerCertChain=c:\\certificates\\brokercerts.crt
+          CertFile=c:\\certificates\\client.crt
+          PrivateKey=c:\\certificates\\client.key
+
+          [Brokers]
+          {5d73b77f-8c4b-4ae0-b437-febd12facfd4}={5d73b77f-8c4b-4ae0-b437-febd12facfd4};8883;mybroker.mcafee.com;192.168.1.12
+          {24397e4d-645f-4f2f-974f-f98c55bdddf7}={24397e4d-645f-4f2f-974f-f98c55bdddf7};8883;mybroker2.mcafee.com;192.168.1.13
+
+          [BrokersWebSockets]
+          {5d73b77f-8c4b-4ae0-b437-febd12facfd4}={5d73b77f-8c4b-4ae0-b437-febd12facfd4};443;mybroker.mcafee.com;192.168.1.12
+          {24397e4d-645f-4f2f-974f-f98c55bdddf7}={24397e4d-645f-4f2f-974f-f98c55bdddf7};443;mybroker2.mcafee.com;192.168.1.13
+
+          [Proxy]
+          Address=proxy.mycompany.com
+          Port=3128
+          User=proxyUser
+          Password=proxyPassword
+
+
+When the ``UseWebSockets`` setting is set to ``true``, the OpenDXL Java Client will connect to the DXL Brokers
+listed in the ``[BrokersWebSockets]`` sections via WebSockets.
+
+If ``UseWebSockets`` setting is set to ``false`` or does not exist in the ``dxlclient.config`` file, then the
+OpenDXL Java Client will connect to the DXL Brokers listed in the ``[Brokers]`` section via MQTT.