Ockam Routing

Ockam is a suite of programming libraries, command line tools, and managed cloud services to orchestrate end-to-end encryption, mutual authentication, key management, credential management, and authorization policy enforcement — all at massive scale. Ockam's end-to-end secure channels guarantee authenticity, integrity, and confidentiality of all data-in-motion at the application layer.

One of the key features that makes this possible is Ockam Routing. Routing allows us to create secure channels over multi-hop, multi-protocol routes which can span various network topologies (servers behind NAT firewalls with no external ports open, etc) and transport protocols (TCP, UDP, WebSockets, BLE, etc).

In this blog post we will explore the Ockam Rust Library and see how routing works in Ockam. We will work with Rust code and look at some code examples that demonstrate the simple case, and more advanced use cases.

Mitigating risk

Before we get started, let's quickly discuss the pitfalls of using existing approaches to securing communications within applications. Security is not something that most of us think about when we are building systems and are focused on getting things working and shipping.

Traditional secure communication implementations are typically tightly coupled with transport protocols in a way that all their security is limited to the length and duration of one underlying transport connection.

1. For example, most TLS implementations are tightly coupled with the underlying TCP connection. If your application's data and requests travel over two TCP connection hops (TCP → TCP), then all TLS guarantees break at the bridge between the two networks. This bridge, gateway, or load balancer then becomes a point of weakness for application data.
2. Traditional secure communication protocols are also unable to protect your application's data if it travels over multiple different transport protocols. They can't guarantee data authenticity or data integrity if your application's communication path is UDP → TCP or BLE → TCP.

In other words using traditional secure communication implementations you may be opening the doors to losing trust in the data that your apps are working on. Here are some aspects of your apps that may be at risk:

1. Lack of trust in the data your app receives.
   • Who sent it to my app?
   • Is it actually the data they sent my app?
   • Missing authentication, data integrity.
2. Lack of trust in the data your app sends.
   • Who am I sending the data to?
   • Would someone else, other than them, be able to see it?

Our journey

In this blog post we will create two examples of Ockam nodes communicating with each other using Ockam Routing and Ockam Transports. We will use the Rust library to create these Ockam nodes and setup routing. Ockam Routing and transports enable other Ockam protocols to provide end-to-end guarantees like trust, security, privacy, reliable delivery, and ordering at the application layer.

• Ockam Routing: is a simple and lightweight message-based protocol that makes it possible to bidirectionally exchange messages over a large variety of communication topologies: TCP -> TCP or TCP -> TCP -> TCP or BLE -> UDP -> TCP or BLE -> TCP -> TCP or TCP -> Kafka -> TCP or any other topology you can imagine.
• Ockam Transports: adapt Ockam Routing to various transport protocols.

An Ockam node is any running application that can communicate with other applications using various Ockam protocols like Routing, Relays, and Portals, Secure Channels, etc.

An Ockam node can be defined as any independent process which provides an API supporting the Ockam Routing protocol. We can create Ockam nodes using the Ockam command line interface (CLI) (ockam command) or using various Ockam programming libraries like our Rust and Elixir libraries. We will be using the Rust library in this blog post.

Let's dive in

Simple example

For our first example, we will create a simple Ockam node that will send a message over some hops (in the same node) to a worker (in the same node) that just echoes the message back. There are no TCP transports involved and all the messages are being passed back and forth inside the same node. This will give us a feel for building workers and routing at a basic level.

When a worker is started on a node, it is given one or more addresses. The node maintains a mailbox for each address and whenever a message arrives for a specific address it delivers that message to the corresponding registered worker.

We will need to create a Rust source file with a main() program, and two other Rust source files with two workers: Hopper and Echoer. We can then send a string message and see if we can get it echoed back.

Before we begin let's consider routing. When we send a message inside of a node it carries with it 2 metadata fields, onward_route and return_route, where a route is simply a list of addresses. Each worker gets an address in a node.

So, if we wanted to send a message from the app address to the echoer address, with 3 hops in the middle, we can build a route like the following.

Here's the Rust code to build this route.

Let's add some source code to make this happen next. The first thing we will do is add one more dependency to this empty hello_ockam project. The colored crate will give us colorized console output which will make the output from our examples so much easier to read and understand.

Then we add the echoer worker (in our hello_ockam project) by creating a new /src/echoer.rs file and copy / pasting the following code in it.

Next we add the hopper worker (in our hello_ockam project) by creating a new /src/hopper.rs file and copy / pasting the following code in it.

Note how this worker manipulates the onward_route & return_route fields of the message to send it to the next hop. We will actually see this in the console output when we run this code soon.

And finally let's add a main() to our hello_ockam project. This will be the entry point for our example.

Create an empty file /examples/03-routing-many.hops.rs (note this is in the examples/ folder and not src/ folder like the workers above).

Now it is time to run our program to see what it does! 🎉

In your terminal app, run the following command. Note that OCKAM_LOG=none is used to disable logging output from the Ockam library. This is done to make the output of the example easier to read.

And you should see something like the following. Our example program creates multiple hop workers (three hopper workers) between the app and the echoer and route our message through them 🚀.

Complex example

In this example, we will introduce TCP transports in between the hops. Instead of passing messages around between workers in the same node, we will spawn multiple nodes. Then we will have a few TCP transports (TCP socket client and listener combos) that will connect the nodes.

An Ockam transport is a plugin for Ockam Routing. It moves Ockam Routing messages using a specific transport protocol like TCP, UDP, WebSockets, Bluetooth, etc.

We will have three nodes:

1. node_initiator: The first node initiates sending the message over TCP to the middle node (port 3000).
2. node_middle: Then middle node simply forwards this message on to the last node over TCP again (port 4000 this time).
3. node_responder: And finally the responder node receives the message and sends a reply back to the initiator node.

The following diagram depicts what we will build next. In this example all these nodes are on the same machine, but they can easy just be nodes on different machines.

Let's start by creating a new file /examples/04-routing-over-two-transport-hops.rs (in the /examples/ folder and not /src/ folder). Then copy / paste the following code in that file.

This code won't actually compile, since there are 3 functions missing from this source file. We are just adding this file first in order to stage the rest of the code we will write next.

This main() function creates the three nodes like we see in the diagram above, and it also stops them after the example is done running.

Initiator node

So let's write the function that creates the initiator node first. Copy the following into the source file we created earlier (/examples/04-routing-over-two-transport-hops.rs), and paste it below the existing code there:

This (initiator) node will send a message to the responder using the following route.

Middle node

Let's create the middle node next, which will run the worker Forwarder on this address: forward_to_responder.

Copy and paste the following into the source file we created above (/examples/04-routing-over-two-transport-hops.rs).

• This middle node simply forwards whatever comes into its TCP listener (on 3000) to port 4000.
• This node has a Forwarder worker on address forward_to_responder, so that's how the initiator can reach this address specified in its route at the start of this example.

We will also need the Forwarder worker that we use in the middle node. Copy and paste the following into a new source file /src/forwarder.rs. This file goes in the src folder and not the examples folder.

Responder node

Finally, we will create the responder node. This node will run the worker echoer which actually echoes the message back to the initiator. Copy and paste the following into the source file above (/examples/04-routing-over-two-transport-hops.rs).

• This node has an Echoer worker on address echoer, so that's how the initiator can reach this address specified in its route at the start of this example.

Let's run this example to see what it does 🎉.

In your terminal app, run the following command. Note that OCKAM_LOG=none is used to disable logging output from the Ockam library. This is done to make the output of the example easier to read.

This should produce output similar to the following. Our example program creates a route that traverses multiple nodes and TCP transports from the app to the echoer and routes our message through them 🚀.

Next steps

Ockam Routing and transports are extremely powerful and flexible. They are one of the key features that enables Ockam Secure Channels to be implemented. By layering Ockam Secure Channels and other protocols over Ockam Routing, we can provide end-to-end guarantees over arbitrary transport topologies that span many networks and clouds.

In a future blog post we will be covering Ockam Secure Channels and how they can be used to provide end-to-end guarantees over arbitrary transport topologies. So stay tuned!

In the meantime here are some good jumping off points to learn more about Ockam:

• Deep dive into Ockam Routing.
• Install Ockam command line interface (CLI) (ockam command) on your computer and try to create end-to-end encrypted communication between two apps. That will give you a taste of the experience of using Ockam on the command line in addition to our Rust library.