Documentation!

0. Client

Ebbflow provides a Client that you can use to easily server your endpoint with, see details of that here!!

1. Endpoint Basics

1a. How it works for Clients/Customers of your endpoint

It works by routing your endpoint to ebbflow through DNS using an A record, or CNAME record for non-root domains. Clients will request your website, e.g. example.com, and DNS will direct them to ebbflow. Then ebbflow sees the customer is requesting example.com, and routes the client connection to one of your server connections.

1b. How it works for Servers Hosting your endpoint

Servers host endpoints by establishing a TLS connection to ebbflow, using SNI to indicate which endpoint to host, and using TLS Client Authentication to prove to ebbflow that you are allowed to serve the given endpoint.

In practice, this connection is done using the client (see instructions there), OR manually.

To manaully serve an endpoint, and what the client does, is to establish a TLS connection to ebbflow.io:7070. Additionally, you must do two things:

2. Security Information

2a. TLS, when is the data encrypted?

When using Managed or Hosted endpoints, data is encrypted from client-Ebbflow, decrypted, then re-encrypted to be passed between Ebbflow-server. This is due to there being one TLS connection between Client and Ebbflow, and another between Ebbflow and your server. There is a short time in the middle where the data is not encrypted, but the data on lives in the memory of the Ebbflow server process and is not inspected at all.

Alternatively, you can use a Passthrough endpoint. In this case, Ebbflow just peeks at the ClientHello of the Client (never any data), and then forwards ALL bytes through the Ebbflow-Server TLS connection. This means that Ebbflow's servers are never able to view the plaintext communications. The side-effect is that the data that is passed through the Ebbflow-Server TLS connection is TLS data itself, so the data received through this connection must be treated as TLS data. This results in having to host the TLS certificate of your endpoint on each server.

In the future, the client will be able to host your on-server certificates, but as of now, you must perform the TLS handshake from the data the ebbflow client receives and hits your web-server with.

3. Creating an Endpoint

To create an endpoint, you must be logged in. Head to the create endpoint page and make the first choice - what type of Client certificate management you want.

3a. Choosing an Endpoint Type

There are three types of endpoints, Managed, Hosted, and Passthrough
3a1. Managed
Ebbflow will provision a Let's Encrypt signed certificate for your endpoint. This certificate will be presented to clients, as the TLS connection is terminated at Ebbflow. The client request will be passed to your server inside of the Ebbflow-Client (or manually created) TLS connection.
3a2. Hosted
You provide Ebbflow with your certificate key and cert which Ebbflow will present to clients. The Client TLS connection is termianted at Ebbflow, and the request is passed to your server inside the Ebbflow-Client (or manually created) TLS conneciton.
3a3. Passthrough
Ebbflow will NOT terminate the TLS connection, it will simply forward the client's TLS handshake through to your server. It just peeks at the SNI in the ClientHello to know where to route to, then starts forwarding all traffic back and forth. This means that the data as encrypted all the way from client to your server and ebbflow CANNOT see the data in its servers.

3b. Providing a CA Cert

You must provide Ebbflow with the certificate of a CA which will be used to verify the servers behind your endpoint. Servers will be performing TLS client authentication to Ebbflow, and Ebbflow will only trust servers which authenticate with credentials that match the CA you provide. This CA can be self-signed.

3c. Configuring DNS

3c1. Directing customers to Ebbflow

You must change the DNS records of the endpoint you want to host to point to ebbflow. If you are hosting a root domain, e.g. example.com (no subdomains), then you must use the A record to point to ebbflow's IP address: 34.210.53.235. If you are not using a root record and are using a subdomain, then you can use a CNAME to point to ebbflow.io

Note: Wildcard DNS records are not supported.

3c2. Verifying your endpoint to Ebbflow

Instructions are located in the Endpoint Detail page for one of your endpoints. Verification is needed so you cannot squat a domain in case the owner of that domain later adopts Ebbflow. Also, it allows you to verify that your traffic is set up to hit Ebbflow properly.