diff --git a/README.md b/README.md index 8e338c0..1cf5f09 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,10 @@ 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)| +| 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) | Code Test Coverage: ![Codecov](https://img.shields.io/codecov/c/github/bmartin5692/bumper.svg) @@ -20,13 +20,13 @@ 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 | -| Deebot Ozmo 930 | XMPP | master | Ecovacs | -| Deebot M81 Pro | XMPP | v0.1.0 | Ecovacs | +| 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 | +| Deebot Ozmo 930 | XMPP | master | Ecovacs | +| Deebot M81 Pro | XMPP | v0.1.0 | Ecovacs | For more information about the protocols and how Bumper works, see the [How does it work?](docs/How_It_Works.md) page in the docs. If you test against another model and it works, please open an issue to report it. @@ -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 diff --git a/docs/Create_Certs.md b/docs/Create_Certs.md new file mode 100644 index 0000000..f4e757c --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/DNS_Setup.md b/docs/DNS_Setup.md index 65e4a42..e90d378 100644 --- a/docs/DNS_Setup.md +++ b/docs/DNS_Setup.md @@ -28,13 +28,23 @@ 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 | -| `eco-{countrycode}-api.ecovacs.com` | Used for Login | -| `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 | -| `mq-ww.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 | \ No newline at end of file +| 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 | diff --git a/docs/Env_Var.md b/docs/Env_Var.md new file mode 100644 index 0000000..f5b0697 --- /dev/null +++ b/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 | \ No newline at end of file diff --git a/docs/How_It_Works.md b/docs/How_It_Works.md index ed8eec1..978b46b 100644 --- a/docs/How_It_Works.md +++ b/docs/How_It_Works.md @@ -4,11 +4,11 @@ Bumper runs multiple services to re-create what the central EcoVacs servers prov **Services** -| Service | Description | Ports | Source File | -|--|--|--|--| +| 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` | +| XMPP Server | For bots that utilize this protocol | 5223 | `xmppserver.py` | +| MQTT Server | For bots that utilize this protocol | 8883 | `mqttserver.py` | **App/Authentication**