README.md

@@ -5,7 +5,7 @@ Bumper is a standalone and self-hosted implementation of the central server used
 **Note:** The current master branch is unstable, and in active development.
 
 | Master Build Status | Status                                                                 |
-|--|--|
+| ------------------- | ---------------------------------------------------------------------- |
 | AppVeyor (Win32)    | ![AppVeyor](https://img.shields.io/appveyor/ci/bmartin5692/bumper.svg) |
 | TravisCI (Linux)    | ![Travis (.org)](https://img.shields.io/travis/bmartin5692/bumper.svg) |
 
@@ -21,7 +21,7 @@ Bumper needs users to assist with testing in order to ensure compatability as bu
 As work to reverse the protocols and provide a self-hosted central server is still in progress, Bumper has had limited testing.  There are a number of EcoVacs models that it hasn't been tested against.  Bumper should be compatible with most wifi-enabled robots that use either the Ecovacs Android/iOS app or the Ecovacs Home Android/iOS app, but has only been reported to work on the below:
 
 | Model           | Protocol Used | Bumper Version Tested | EcoVacs App Tested   |
-|--|--|--|--|
+| --------------- | ------------- | --------------------- | -------------------- |
 | Deebot 900/901  | MQTT          | master                | Ecovacs/Ecovacs Home |
 | Deebot 600      | MQTT          | master                | Ecovacs Home         |
 | Deebot Ozmo 601 | XMPP          | master                | Ecovacs              |
@@ -55,6 +55,7 @@ But seriously, there are a several reasons for eliminating the central server:
 ## Quick Start Usage
 
  - Download bumper then run `pipenv install` to install dependencies
+ - Generate certificates for Bumper - See the [Creating Certs](docs/Create_Certs.md) doc
  - Configure your Ecovacs vacuum using the official mobile app (if you haven't done this already)
  - Configure your DNS server as described in the [DNS Setup](docs/DNS_Setup.md) doc. 
  - Start bumper - see the [Starting Bumper](#starting-bumper) section.
@@ -69,7 +70,6 @@ But seriously, there are a several reasons for eliminating the central server:
 - Reboot your robot
 	- **Note:** Some models may require removing and re-inserting the battery pack.
 	- This doesn't seem to be required for models that don't have easily accessible batteries such as the 900/901.
-
 - If your configuration is correct, the robot will connect to Bumper within about 30 seconds. Bumper will output information about the connection status. 
 
 ## Thanks

docs/Create_Certs.md

@@ -0,0 +1,163 @@
+# Creating Certs
+
+Bumper requires specially crafted certificates to work properly.  In the spirit of security, Bumper will not ship with default certificates.  Users will need to generate and provide their own certificates.  
+
+Certificates should be placed in the `{bumper_home}/certs` directory.  If certificates are located elsewhere [environment variables](Env_Var.md) can be set that point to their location.
+
+Users can generate certificates in the following ways:
+
+| Method                                            | Description                                                                                                         |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |  |
+| [Create_Certs](#creating-certs-using-createcerts) | ***(Preferred)*** This is a utility that has been created to assist in generating the certificates required easily. |
+| [OpenSSL](#manually-create-certs-with-openssl)    | Users can manually create the same certificates as Create_Certs by utilizing OpenSSL.                               |
+| [Custom CA/Self](#using-a-custom-caself)          | If a user has their own CA the certificates can be generated there and used within Bumper.                          |
+
+**Certificate Requirements:**
+
+* A CA Cert must be provided that can be imported into devices (phones, browsers, etc).
+* Server certificate should include [SANs (Subject Alternate Names)](#subject-alternative-name) for all of the *.ecovacs, etc domains.
+
+## Creating certs using Create_Certs
+
+Create_Certs was created to ease creation of certificates specifically for Bumper.  Binaries are provided for Windows/Linux/OSX/RPi (ARMv5) in the Create_Certs directory.
+
+| Binary                   | Platform             |
+| ------------------------ | -------------------- |
+| create_certs_linux       | Linux                |
+| create_certs_osx         | macOS/x              |
+| create_certs_windows.exe | Windows              |
+| create_certs_rpi         | RaspberryPi (ARM v5) |
+
+Create_Certs is written in Go which allows cross-platform compiling. If the binaries don't work on your platform, install Go. 
+
+With Go installed you can:
+* Execute the go code - `go run create_certs/src/create_certs.go` 
+* Build a new binary for your platform - `go build create_certs/src/create_certs.go`
+
+### Usage
+
+Create_Certs will automatically create the required certificates in the directory it is executed from.  For best results change to the {bumper_home}/certs directory prior to executing, otherwise you'll need to move the certs after.
+
+1. `cd certs`
+2. Execute create_certs (using the binary fitting your platform) - `../create_certs/create_certs_{platform}`
+3. The certificates are generated and should be available in the current directory (certs)
+
+## Subject Alternative Name
+
+The server certificate requires a number of SAN (Subject Alternative Names) be added.  Create_Certs handles this automatically by loading any SANs listed in the `create_certs/Bumper_SAN.txt` file.  If creating certificates manually via OpenSSl/Custom CA these will need to be added.
+
+## Manually create certs with OpenSSL
+
+I get it, you don't trust create_certs and want to do it manually.  The easiest way to create the required certs is at https://certificatetools.com/.  In fact the below OpenSSL commands come straight from that site, post creation via the GUI.
+
+### Create a Root CA
+
+1. Create csrconfig.txt for use in later commands
+    csrconfig.txt
+    ````
+    [ req ]
+    default_md = sha256
+    prompt = no
+    req_extensions = req_ext
+    distinguished_name = req_distinguished_name
+    [ req_distinguished_name ]
+    commonName = Bumper CA
+    organizationName = Bumper
+    [ req_ext ]
+    keyUsage=critical,keyCertSign,cRLSign
+    basicConstraints=critical,CA:true,pathlen:1
+    ````
+
+1. Create certconfig.txt for use in later commands
+    certconfig.txt
+    ````
+    [ req ]
+    default_md = sha256
+    prompt = no
+    req_extensions = req_ext
+    distinguished_name = req_distinguished_name
+    [ req_distinguished_name ]
+    commonName = Bumper CA
+    organizationName = Bumper
+    [ req_ext ]
+    subjectKeyIdentifier = hash
+    authorityKeyIdentifier = keyid:always,issuer
+    keyUsage=critical,keyCertSign,cRLSign
+    basicConstraints=critical,CA:true,pathlen:1
+    ````
+
+1. Generate the RSA private key 
+`openssl genpkey -outform PEM -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out priv.key`
+
+1. Create the CSR
+`openssl req -new -nodes -key priv.key -config csrconfig.txt -out cert.csr`
+
+1. Self-sign your CSR
+`openssl req -x509 -nodes -in cert.csr -days 3650 -key priv.key -config certconfig.txt -extensions req_ext -out cert.crt`
+
+### Create the Server Certificate
+
+1. Create csrconfig.txt for use in later commands
+    csrconfig.txt
+    ````
+    [ req ]
+    default_md = sha256
+    prompt = no
+    req_extensions = req_ext
+    distinguished_name = req_distinguished_name
+    [ req_distinguished_name ]
+    commonName = Bumper Server
+    organizationName = Bumper
+    [ req_ext ]
+    keyUsage=critical,digitalSignature,keyEncipherment
+    extendedKeyUsage=serverAuth,clientAuth
+    basicConstraints=critical,CA:false
+    subjectAltName = @alt_names
+    [ alt_names ]
+    DNS.0 = ecovacs.com
+    DNS.1 = *.ecovacs.com
+    DNS.2 = ecouser.net
+    DNS.3 = *.ecouser.net
+    DNS.4 = ecovacs.net
+    DNS.5 = *.ecovacs.net
+    ````
+
+1. Create certconfig.txt for use in later commands
+    certconfig.txt
+    ````
+    [ req ]
+    default_md = sha256
+    prompt = no
+    req_extensions = req_ext
+    distinguished_name = req_distinguished_name
+    [ req_distinguished_name ]
+    commonName = Bumper Server
+    organizationName = Bumper
+    [ req_ext ]
+    subjectKeyIdentifier = hash
+    authorityKeyIdentifier = keyid:always,issuer
+    keyUsage=critical,digitalSignature,keyEncipherment
+    extendedKeyUsage=serverAuth,clientAuth
+    basicConstraints=critical,CA:false
+    subjectAltName = @alt_names
+    [ alt_names ]
+    DNS.0 = ecovacs.com
+    DNS.1 = *.ecovacs.com
+    DNS.2 = ecouser.net
+    DNS.3 = *.ecouser.net
+    DNS.4 = ecovacs.net
+    DNS.5 = *.ecovacs.net
+    ````
+
+1. Generate the RSA private key
+`openssl genpkey -outform PEM -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out priv.key`
+
+1. Create the CSR
+`openssl req -new -nodes -key priv.key -config csrconfig.txt -out cert.csr`
+
+1. Sign your CSR with a root CA cert
+`openssl x509 -req -in cert.csr -days 3650 -CA ca.crt -CAkey priv.key -extfile certconfig.txt -extensions req_ext -CAserial /tmp/tmp-10593TSH1OlVSxC7C -CAcreateserial -out cert.crt`
+
+## Using a Custom CA/Self
+
+This should work siimilar to the OpenSSL method.  Ensure the server certificate has the proper [SANs](#subject-alternative-name) in place.

docs/DNS_Setup.md

@@ -29,12 +29,22 @@ Not all domains have been documented at this point, and this list will be update
   - Example: If you see `eco-{countrycode}-api.ecovacs.com` and you live in the US/North America you would use: `eco-us-api.ecovacs.com`
 
 | Address                                 | Description                                    |
-|--|--|
+| --------------------------------------- | ---------------------------------------------- |
 | `lb-{countrycode}.ecovacs.net`          | Load-balancer that is checked by the app/robot |
+| `lb-{countrycode}.ecouser.net`          | Load-balancer that is checked by the app/robot |
+| `lbus.ecouser.net`                      | Load-balancer that is checked by the app/robot |
+| `lb{countrycode}.ecouser.net`           | Load-balancer that is checked by the app/robot |
 | `eco-{countrycode}-api.ecovacs.com`     | Used for Login                                 |
+| `gl-{countrycode}-api.ecovacs.com`      | Used by EcoVacs Home app                       |
+| `gl-{countrycode}-openapi.ecovacs.com`  | Used by EcoVacs Home app                       |
 | `portal-{countrycode}.ecouser.net`      | Used for Login and Rest API                    |
 | `portal-ww.ecouser.net`                 | Used for various Rest APIs                     |
 | `msg-{countrycode}.ecouser.net`         | Used for XMPP                                  |
+| `msg-ww.ecouser.net`                    | Used for XMPP                                  |
 | `mq-ww.ecouser.net`                     | Used for MQTT                                  |
+| `mq-{countrycode}.ecouser.net`          | Used for MQTT                                  |
 | `gl-{countrycode}-api.ecovacs.com`      | Used by Ecovacs Home app for API               |
 | `recommender.ecovacs.com`               | Used by Ecovacs Home app                       |
+| `bigdata-international.ecovacs.com`     | Telemetry/tracking                             |
+| `bigdata-northamerica.ecovacs.com`      | Telemetry/tracking                             |
+| `bigdata-{unknown regions}.ecovacs.com` | Telemetry/tracking                             |

docs/Env_Var.md

@@ -0,0 +1,14 @@
+# Environment Variables
+
+Bumper has a number of environment variables to help with custom deployments and configuration.  These should be set prior to executing Bumper.
+
+| Setting            | Value                              | Description                                                                                                                 |
+| ------------------ | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| BUMPER_LISTEN      | {ipv4 address}                     | IP address to start server listeners on                                                                                     |
+| BUMPER_ANNOUNCE_IP | {ipv4 address}                     | IP address to tell bots when they request the server location.  May need to be set in cases such as when LISTEN is 0.0.0.0. |
+| BUMPER_CA          | {full path to ca.crt location}     | The public CA certificate (ca.crt) to be loaded                                                                             |
+| BUMPER_CERT        | {full path to bumper.crt location} | The public server certificate (bumper.crt) to be used by the Bumper server                                                  |
+| BUMPER_KEY         | {full path to bumper.key location} | The private server key (bumper.key) to be used by the Bumper server                                                         |
+| BUMPER_LOGS        | {full path to logs directory}      | The directory where logs should be stored                                                                                   |
+| BUMPER_DATA        | {full path to data directory}      | The directory where persistent data should be stored (bumper.db)                                                            |
+| BUMPER_DEBUG       | true                               | Run Bumper with debug mode/logging                                                                                          |

docs/How_It_Works.md

@@ -5,7 +5,7 @@ Bumper runs multiple services to re-create what the central EcoVacs servers prov
 **Services**
 
 | Service     | Description                                      | Ports        | Source File     |
-|--|--|--|--|
+| ----------- | ------------------------------------------------ | ------------ | --------------- |
 | Web Servers | Provide authentication and for MQTT bots command | 443 and 8007 | `confserver.py` |
 | XMPP Server | For bots that utilize this protocol              | 5223         | `xmppserver.py` |
 | MQTT Server | For bots that utilize this protocol              | 8883         | `mqttserver.py` |