Ockam empowers you to build secure-by-design apps that can trust data-in-motion.

With Ockam:

• Impossible connections become possible. Establish secure channels between systems in private networks that previously could not be connected because it is either too difficult or insecure.

• All public endpoints become private. Connect your applications and databases without exposing anything publicly.

At its core, Ockam is a toolkit for developers to build applications that can create end-to-end encrypted, mutually authenticated, secure communication channels:

• From anywhere to anywhere: Ockam works across any network, cloud, or on prem infrastructure.

• Over any transport topology: Ockam is compatible with every transport layer including TCP, UDP, Kafka, or even Bluetooth.

• Without no infrastructure, network, or application changes: Ockam works at the application layer, so you don’t need to make complex changes.

• While ensuring the risky things are impossible to get wrong: Ockam’s protocols do the heavy lifting to establish end-to-end encrypted, mutually authenticated secure channels

Why Ockam is so unique

Traditionally, connections made over TCP are secured with TLS. However, the security guarantees of a TLS secure channel only apply for the length of the underlying TCP connection. It is not possible to connect two systems in different private networks over a single TCP connection. Thus, connecting these two systems requires exposing one of them over the Internet, and breaking the security guarantees of TLS.

Ockam works differently. Our secure channel protocol sits on top of an application layer routing protocol. This routing protocol can hand over messages from one transport layer connection to another. This can be done over any transport protocol, with any number of transport layer hops: TCP to TCP to TCP, TCP to UDP to TCP, UDP to Bluetooth to TCP to Kafka, etc.

Over these transport layer connections, Ockam sets up an end-to-end encrypted, mutually authenticated connection. This unlocks the ability to create secure channels between systems that live in entirely private networks, without exposing either end to the Internet.

Since Ockam’s routing protocol is at the application layer, complex network and infrastructure changes are not required to make these connections. Rather than a months-long infrastructure project, you can connect private systems in minutes while ensuring the risky things are impossible to get wrong. NATs are traversed; Keys are stored in vaults; Credentials are short-lived; Messages are authenticated; Data-integrity is guaranteed; Senders are protected from key compromise impersonation; Encryption keys are ratcheted; Nonces are never reused; Strong forward secrecy is ensured; Sessions recover from network failures; and a lot more.

Ockam is easy to use

The magic of Ockam is it's simplicity. All you need to do is subscribe to Ockam Orchestrator, and then deploy one of the following distributions next to the applications you'd like to connect:

• Ockam Programming Libraries (Rust …)

• Ockam Command

• Ockam Docker Images

• RedPanda Connect

• Managed Ockam Nodes from the AWS Marketplace

• Snowflake Native Apps

• Lambda/Serverless Functions

Ockam empowers you to build secure-by-design apps that can trust data-in-motion.

You can use Ockam to create end-to-end encrypted and mutually authenticated channels. Ockam secure channels authenticate using cryptographic identities and credentials. They give your apps granular control over all trust and access decisions. This control makes it easy to enforce fine-grained, attribute-based authorization policies – at scale.

These core capabilities are composed to enable private and secure communication in a wide variety of application architectures. For example, with one simple command, an app in your cloud can create an encrypted portal to a micro-service in another cloud. The service doesn’t need to be exposed to the Internet. You don’t have to change anything about networks or firewalls.

# Create a TCP Portal Inlet to a Postgres server that is running in
# a remote private VPC in another cloud.
ockam tcp-inlet create --from 15432 --via postgres

# Access the Postgres server on localhost.
psql --host localhost --port 15432

Similarly, using another simple command a kafka producer can publish end-to-end encrypted messages for a specific kafka consumer. Kafka brokers in the middle can’t see, manipulate, or accidentally leak sensitive enterprise data. This minimizes risk to sensitive business data and makes it easy to comply with data governance policies.

Encrypted Portals

Portals carry various application protocols over end-to-end encrypted Ockam secure channels.

For example: a TCP Portal carries TCP over Ockam, a Kafka Portal carries Kafka Protocol over Ockam, etc. Since portals work with existing application protocols you can use them through companion Ockam Nodes, that run adjacent to your application, without changing any of your application’s code.

A tcp portal makes a remote tcp server virtually adjacent to the server’s clients. It has two parts: an inlet and an outlet. The outlet runs adjacent to the tcp server and inlets run adjacent to tcp clients. An inlet and the outlet work together to create a portal that makes the remote tcp server appear on localhost adjacent to a client. This client can then interact with this localhost server exactly like it would with the remote server. All communication between inlets and outlets is end-to-end encrypted.

You can use Ockam Command to start nodes with one or more inlets or outlets. The underlying protocols handle the hard parts :

• NATs are traversed

• Keys are stored in vaults

• Credentials are short-lived

• Messages are authenticated

• Data-integrity is guaranteed

• Senders are protected from key compromise impersonation

• Encryption keys are ratcheted

• Nonces are never reused

• Strong forward secrecy is ensured and has been validated by an Audit by Trail of Bits

• Sessions recover from network failures

• ...and lots more!

How Ockam is different from a Network layer connector

Create an Ockam Portal between any application, to any database, in any environment.

In each example, we connect a nodejs app in one private network with a database in another private network.

Each company’s network is private, isolated, and doesn't expose ports. To learn how end-to-end trust is established, please read: “”

Please select an example to dig in:

In each example, we will connect a nodejs app in one private network with a postgres database in another private network.

Each company’s network is private, isolated, and doesn't expose ports. To learn how end-to-end trust is established, please read: “”

Please select an example to dig in:

This section contains hands-on examples that use to create encrypted portals to InfluxDB databases running in various environments.

In each example, we connect a nodejs app in one private network with a InfluxDB database in another private network. To understand how end-to-end trust is established, and how the portal works even though the two networks are isolated with no exposed ports, please read: “”

Please select an example to dig in:

In each example, we connect a nodejs app in one private network with a MongoDB database in another private network.

Each company’s network is private, isolated, and doesn't expose ports. To learn how end-to-end trust is established, please read: “”

Please select an example to dig in:

Try one of these demos yourself, or get a video walk through.

Create an Ockam Portal from any application, to any code repo, in any environment.

In each example, we connect a nodejs app in one company's private network with a git repository managed by gitlab in another company's private network.

Each company’s network is private, isolated, and doesn't expose ports. To learn how end-to-end trust is established, please read: “”

Please select an example to dig in:

Nodes and Workers

Create an Ockam Portal from any application, to any API, in any environment.

In each example, we connect a client app in one private network with am API service in another private network.

Each company’s network is private, isolated, and doesn't expose ports. To learn how end-to-end trust is established, please read: “How does Ockam work?”

Please select an example to dig in:

Create an Ockam Portal from any application, to any AI model, in any environment.

In each example, we connect a nodejs app in one private network with an AI service in another private network.

Each company’s network is private, isolated, and doesn't expose ports. To learn how end-to-end trust is established, please read: “How does Ockam work?”

Please select an example to dig in:

Create an Ockam Portal to send end-to-end encrypted messages through Apache Kafka.

Ockam encrypts messages from a Producer to a specific Consumer. Only that specific Consumer can decrypt these messages. This guarantees that your data cannot be observed or tampered as it passes through Kafka. Operators of the Kafka cluster only see end-to-end encrypted data. Any compromise of an operator's infrastructure cannot compromise your business data.

To learn how end-to-end trust is established, please read: “How does Ockam work?”

Please select an example to dig in:

Create an Ockam Portal to send end-to-end encrypted messages through Redpanda.

Ockam encrypts messages from a Producer all-of-the-way to a specific Consumer. Only that specific Consumer can decrypt these messages. This guarantees that your data cannot be observed or tampered with as it passes through Redpanda or the network where it is hosted. The operators of Redpanda can only see encrypted data in the network and in service that they operate. Thus, a compromise of the operator's infrastructure will not compromise the data stream's security, privacy, or integrity.

To learn how end-to-end trust is established, please read: “How does Ockam work?”

Please select an example to dig in:

Create an Ockam Portal to send end-to-end encrypted messages through Confluent Cloud.

Ockam encrypts messages from a Producer all-of-the-way to a specific Consumer. Only that specific Consumer can decrypt these messages. This guarantees that your data cannot be observed or tampered with as it passes through Confluent Cloud or the network where it is hosted. The operators of Confluent Cloud can only see encrypted data in the network and in service that they operate. Thus, a compromise of the operator's infrastructure will not compromise the data stream's security, privacy, or integrity.

To learn how end-to-end trust is established, please read: “How does Ockam work?”

Please select an example to dig in:

Create an Ockam Portal to send end-to-end encrypted messages through Warpstream Cloud.

Ockam encrypts messages from a Producer all-of-the-way to a specific Consumer. Only that specific Consumer can decrypt these messages. This guarantees that your data cannot be observed or tampered with as it passes through Warpstream Cloud or the network where it is hosted. The operators of Warpstream Cloud can only see encrypted data in the network and in service that they operate. Thus, a compromise of the operator's infrastructure will not compromise the data stream's security, privacy, or integrity.

To learn how end-to-end trust is established, please read: “How does Ockam work?”

Please select an example to dig in:

Create an Ockam Portal to send end-to-end encrypted messages through Instaclustr.

Ockam encrypts messages from a Producer all-of-the-way to a specific Consumer. Only that specific Consumer can decrypt these messages. This guarantees that your data cannot be observed or tampered with as it passes through Instaclustr or the network where it is hosted. The operators of Instaclustr can only see encrypted data in the network and in service that they operate. Thus, a compromise of the operator's infrastructure will not compromise the data stream's security, privacy, or integrity.

To learn how end-to-end trust is established, please read: “How does Ockam work?”

Please select an example to dig in:

Let’s build a simple example together. We will create an encrypted from a psql microservice in Azure to a Postgres Database in AWS.

When you get done with this page you will understand

1. the basic building blocks of Ockam,

2. the first steps you should take in your architecture, and

3. how to build an end-to-end encrypted portal between two private services.

Create an Orchestrator Project

and pick a subscription plan through the guided workflow on Ockam.io. After you complete this step you will have a Project in Ockam Orchestrator. A Project offers two services: a Membership and a service. More on both of those later.

Set up Command on your local dev machine

Run the following commands to install Ockam Command on your dev machine.

The `enroll` command does a lot! All at once it...

1. creates an Ockam Node on your machine.

2. generates a private key as your local Node’s cryptographic.

3. creates a local

4. guides you to sign in to your new Ockam Orchestrator Project.

5. asks your Project’s Membership Authority to issue and sign a for this Node.

6. makes you the administrator of your Project.

7. creates a Secure Channel between your local Ockam Node and your Project in Orchestrator.

Congrats! Your dev machine Node has a secure, encrypted Ockam Portal connection to your Project Node inside of Ockam Orchestrator over a Secure Channel!

Install Ockam Command and create an Ockam Node in AWS

The process is repeated in AWS through the same set of commands.

You now have an Ockam Node running in your VPC. As before, this Node will have

1. a set of private key Identifiers, stored in a local Vault

2. a Membership Credential that will allow this Ockam Node to join your Project in Orchestrator.

Create a Portal Outlet in this Ockam Node

An Outlet is created in the Ockam Node and a raw TCP connection is created to the postgres server on localhost port 5432.

Create a Secure Channel to Orchestrator, and create a Relay in your Project

This command

1. initiates an outgoing tcp connection from the Ockam Node in AWS to your Project in Ockam Orchestrator.

2. creates a over the tcp connection.

3. creates a Relay in your Project at the address: postgres

Notice that we didn’t have to change anything in the AWS network settings. It’s possible because Bank Corp’s network allows outgoing tcp connections to the Internet. We use this port to create the Secure Channel.

Create an Ockam Node in Azure

Create a Portal Inlet in this Node in Azure

This command

1. creates a tcp Portal Inlet.

2. creates a tcp listener on localhost port 15432.

3. creates an outgoing tcp connection to your Project.

4. creates a to your Project over this tcp connection.

5. creates an end-to-end Secure Channel from the Inlet to the Outlet in Bank Corp’s VPC via the Relay in your Project at address: postgres

Congrats! The psql microservice at Analysis Corp and the Postgres database at Bank Corp are connected with an Ockam Portal.

Local Query

The psql service now has an end-to-end encrypted, mutually authenticated, secure channel connection with the postgres database on localhost:15432

All of the data-in-motion is end-to-end with strong forward secrecy as it moves through the Internet. The communication channel is and. Keys and Credentials are automatically rotated. Access to connect with postgres can be easily revoked.

There’s so much more….

This is just one simple example. Ockam’s stack of work together to ensure security, privacy, and trust in data. They can be combined and composed in all sorts of ways.

In the next section we will dive into all sorts of ways to build portals across different infrastructures, networks, and applications.

The Trick behind Ockam's Magic, by our Founders

Create an Ockam Portal to send end-to-end encrypted messages through Kafka - from any producer, to any consumer, through any Kafka API compatible data streaming platform.

encrypts messages from a Producer to a specific Consumer. Only that specific Consumer can decrypt these messages. This guarantees that your data cannot be observed or tampered as it passes through Kafka. Operators of the Kafka cluster only see end-to-end encrypted data. Any compromise of an operator's infrastructure cannot compromise your business data.

To learn how end-to-end trust is established, please read: “”

Please select an example to dig in:

Ockam Command is our command line interface to build secure by design applications that can trust all data in motion. It makes it easy to orchestrate end-to-end encryption, mutual authentication, key management, credential management, and authorization policy enforcement – at a massive scale.

No more having to design error-prone ad-hoc ways to distribute sensitive credentials and roots of trust. Ockam's integrated approach takes away this complexity and gives you simple tools for:

End-to-end data authenticity, integrity, and privacy in any communication topology

• Create end-to-end encrypted, authenticated secure channels over any transport topology.

• Create secure channels over multi-hop, multi-protocol routes over TCP, UDP, WebSockets, BLE, etc.

• Provision encrypted relays for applications distributed across many edge, cloud and data-center private networks.

• Make any protocol secure by tunneling it through mutually authenticated and encrypted portals.

• Bring end-to-end encryption to enterprise messaging, pub/sub and event streams - Kafka, Kinesis, RabbitMQ, etc.

Identity-based, policy driven, application layer trust – granular authentication and authorization

• Generate cryptographically provable unique identities.

• Store private keys in safe vaults - hardware secure enclaves and cloud key management systems.

• Operate scalable credential authorities to issue lightweight, short-lived, revocable, attribute-based credentials.

• Onboard fleets of self-sovereign application identities using secure enrollment protocols.

• Rotate and revoke keys and credentials – at scale, across fleets.

• Define and enforce project-wide attribute-based access control policies. Choose ABAC, RBAC or ACLs.

• Integrate with enterprise identity providers and policy providers for seamless employee access.

A step by step introduction

Ockam Command provides the above collection of composable building blocks that are accessible through various sub-commands. In a step-by-step guide let's walk through various Ockam sub-commands to understand how you can use them to build end-to-end trustful communication for any application in any communication topology.

Install Ockam Command

If you haven't already, the first step is to install Ockam Command:

Check that everything was installed correctly by enrolling with Ockam Orchestrator. This will create a and for you in Ockam Orchestrator.

Next, let's dive in and learn how to use .

In order to make decisions about trust, we must authenticate senders of messages.

Vaults

Ockam authenticate by cryptographically proving possession of specific secret keys. Ockam Vaults safely store these secret keys in cryptographic hardware and cloud key management systems.

You can create a vault as follows:

This command will, by default, create a file system based vault, where your secret keys are stored at a specific file path.

Vaults are designed to be used in a way that secret keys never have to leave a vault. There is a growing base of Ockam Vault implementations in the that safely store secret keys in specific KMSs, HSMs, Secure Enclaves etc.

Identities

Ockam Identities are unique, cryptographically verifiable digital identities.

You can create new identities, by typing:

The secret keys belonging to this identity are stored in the specified vault. This can be any type of vault - File Vault, AWS KMS, Azure KeyVault, YubiKey etc. If no vault is specified, the default vault is used. If a default vault doesn't exist yet, a new file systems based vault is created, set as default, and then used to generate secret keys.

To ensure privacy and eliminate the possibility of correlation of behavior across trust contexts, we've made it easy to generate and use different identities and identifiers for separate trust contexts.

Secret Keys

Each Ockam Identity starts its life by generating a secret key and its corresponding public key. Secret keys, must remain secret, while public keys can be shared with the world.

Ockam Identities support two types of Elliptic Curve secret keys that live in vaults - Curve25519 or NIST P-256.

Identifiers

Each Ockam Identity has a unique public identifier, called the Ockam Identifier of this identity:

This Identifier is generated by hashing the first public key of the Identity.

Change History

Ockam Identities can periodically rotate their keys to indicate that the latest public key is the one that should be used for authentication. Each Ockam Identity maintains a self-signed change history of key rotation events, you can see this full history by running:

Identifier Authentication

Authentication, within Ockam, starts by proving control of a specific Ockam Identifier. To prove control of a specific Identifier, the prover must present the identifier, the full signed change history of the identifier, and a signature on a challenge using the secret key corresponding to the latest public key in the identifier's change history.

Next, let's combine everything we've learnt so far to create mutually authenticated and end-to-end encrypted that guarantee data authenticity, integrity, and confidentiality.

Ockam Rust crates are a library of tools to build secure by design applications for any environment – from highly scalable cloud infrastructure to tiny battery operated microcontroller based devices. They make it easy to orchestrate end-to-end encryption, mutual authentication, key management, credential management, and authorization policy enforcement – at massive scale.

No more having to think about creating unique cryptographic keys and issuing credentials to your fleet of application entities. No more designing ways to safely store secrets in hardware and securely distribute roots of trust.

End-to-end data authenticity, integrity, and privacy in any communication topology

• Create end-to-end encrypted, authenticated secure channels over any transport topology.

• Create secure channels over multi-hop, multi-protocol routes over TCP, UDP, WebSockets, BLE, etc.

• Provision encrypted relays for applications distributed across many edge, cloud and data-center private networks.

• Make any protocol secure by tunneling it through mutually authenticated and encrypted portals.

• Bring end-to-end encryption to enterprise messaging, pub/sub and event streams - Kafka, Kinesis, RabbitMQ etc.

Identity-based, policy driven, application layer trust – granular authentication and authorization

• Generate cryptographically provable unique identities.

• Store private keys in safe vaults - hardware secure enclaves and cloud key management systems.

• Operate scalable credential authorities to issue lightweight, short-lived, revokable, attribute-based credentials.

• Onboard fleets of self-sovereign application identities using secure enrollment protocols.

• Rotate and revoke keys and credentials – at scale, across fleets.

• Define and enforce project-wide attribute based access control policies. Chose ABAC, RBAC or ACLs.

• Integrate with enterprise identity providers and policy providers for seamless employee access.

A step by step introduction

Ockam Rust crates provide the above collection of composable building blocks. In a step-by-step hands-on guide let’s walk through each building block to understand how you can use them to build end-to-end trustful communication for any application in any communication topology.

The first step is to install Rust and create a cargo project called hello_ockam We’ll use this project to try out various examples.

Ockam is composed of a collection of cryptographic and messaging protocols. These protocols make it possible to create private and secure by design applications that provide end-to-end application layer trust it data. The following pages explain, in detail, how each of the protocols work:

• Nodes and Workers

• Routing and Transports

• Keys and Vaults

• Identities and Credentials

• Secure Channels

• Access Controls and Policies

Ockam has been audited and verified by experts

In October of 2023, a team of security and cryptography experts, from Trail of Bits, conducted an extensive review of Ockam’s protocols. Trail of Bits is renowned for their comprehensive third-party audits of the security of many other critical projects, including Kubernetes and the Linux kernel.

The auditors from Trail of Bits conducted in-depth, manual analysis, and formal modeling of the security properties of Ockam’s protocols. After this review was complete, they highlighted:

Ockam’s protocols use robust cryptographic primitives according to industry best practices. None of the identified issues pose an immediate risk to the confidentiality and integrity of data handled by the system in the context of the two in-scope use cases. The majority of identified issues relate to information that should be added to the design documentation, such as threat model details and increased specification for certain aspects.

— Trail of Bits

Download the unabridged audit by Trail of Bits:

In this hands-on example we send end-to-end encrypted messages through Aiven Cloud.

encrypts messages from a Producer all-of-the-way to a specific Consumer. Only that specific Consumer can decrypt these messages. This guarantees that your data cannot be observed or tampered with as it passes through Aiven Cloud or the network where it is hosted. The operators of Aiven Cloud can only see encrypted data in the network and in service that they operate. Thus, a compromise of the operator's infrastructure will not compromise the data stream's security, privacy, or integrity.

To learn how end-to-end trust is established, please read: “”

Run

This example requires Aiven CLI, Bash, JQ, Git, Curl, Docker, and Docker Compose. Please set up these tools for your operating system, then run the following commands:

If everything runs as expected, you'll see the message: The example run was successful 🥳

Walkthrough

The , that you ran above, and its are full of comments and meant to be read. The example setup is only a few simple steps, so please take some time to read and explore.

Administrator

• The calls the which invokes the to create an new identity, sign in to Ockam Orchestrator, set up a new Ockam project, make you the administrator of this project, and get a project membership .

• The run function then using the Aiven CLI.

• An Ockam relay is then started which creates an encrypted Kafka relay that transmits Kafka messages over a secure portal.

• We then , each valid for 10 minutes, and can be redeemed only once. The are meant for the Consumer and Producer, in the Ockam node that will run in Application Team’s network.

• In a typical production setup, an administrator or provisioning pipeline generates enrollment tickets and gives them to nodes that are being provisioned. In our example, the run function is acting on your behalf as the administrator of the Ockam project. It creates a Kafka relay using a pre-baked Ockam Kafka addon which will host the Aiven Kafka server and , passing them their tickets using environment variables.

• For the Application team, the run function takes the enrollment tickets, sets them as the value of an , and to create the Application Teams’s networks.

Application Teams

• Application Teams’s is used when run.sh invokes docker-compose. It creates an for Application Teams. In this network, docker compose starts a and a .

• The Kafka consumer node container is created using and this . The consumer enrollment ticket from run.sh is via environment variable.

• When the Kafka consumer node container starts in the Application Teams network, it runs . The entrypoint and then calls the which starts the Kafka inlet and listens and traffic connection on localhost port 9092 through Ockam relay.

• Next, the entrypoint at the end executes the , which launches a Kafka consumer waiting for messages in the demo topic. Once the messages are received, they are printed out.

• In the producer container, the process is analogous, once the Ockam kafka-producer inlet is set up, the launches a Kafka producer that sends messages.

• You can view the Aiven website to see the encrypted messages as they are being sent by the producer.

Recap

We sent end-to-end encrypted messages through Aiven cloud.

Messages are encrypted with strong forward secrecy as soon as they leave a Producer, and only the intended Consumer can decrypt those messages. Aiven Cloud and other Consumers can only see encrypted messages.

All communication is mutually authenticated and authorized. Keys and credentials are automatically rotated. Access can be easily revoked.

Cleanup

To delete all containers and images:

Let's connect a nodejs app in one kubernetes cluster with a postgres database in another private kubernetes cluster.

Each company’s network is private, isolated, and doesn't expose ports. To learn how end-to-end trust is established, please read: “How does Ockam work?”

Run

This example requires Bash, Git, Curl, Kind, and Kubectl. Please set up these tools for your operating system, then run the following commands:

# Clone the Ockam repo from Github.
git clone --depth 1 https://github.com/build-trust/ockam && cd ockam

# Navigate to this example’s directory.
cd examples/command/portals/databases/postgres/kubernetes

# Run the example, use Ctrl-C to exit at any point.
./run.sh

If everything runs as expected, you'll see the message: The example run was successful 🥳

Walkthrough

The run.sh script, that you ran above, and its accompanying files are full of comments and meant to be read. The example setup is only a few simple steps, so please take some time to read and explore.

Administrator

• The run.sh script calls the run function which invokes the enroll command to create an new identity, sign into Ockam Orchestrator, set up a new Ockam project, make you the administrator of this project, and get a project membership credential.

• The run function then generates two new enrollment tickets. The tickets are valid for 10 minutes. Each ticket can be redeemed only once and assigns attributes to its redeemer. The first ticket is meant for the Ockam node that will run in Bank Corp.’s kubernetes cluster. The second ticket is for the Ockam node that will run in Analysis Corp.’s kubernetes cluster.

• In a typical production setup an administrator or provisioning pipeline generates enrollment tickets and gives them to nodes that are being provisioned. In our example, the run function is acting on your behalf as the administrator of the Ockam project. It uses kubernetes secrets to give tickets to Ockam nodes that are being provisioned in Bank Corp.’s and Analysis Corp.’s kubernetes clusters.

• The run function takes the enrollment tickets, sets them as kubernetes secrets, and uses kind with kubectl to create Bank Corp.’s and Analysis Corp.’s kubernetes clusters.

Bank Corp

• Bank Corp.’s kubernetes manifest defines a pod and containers to run in Bank Corp’s isolated kubernetes cluster. The run.sh script invokes kind to create the cluster, prepares container images and calls kubectl apply to start the pod and its containers.

• One of the containers defined in Bank Corp.’s kubernetes manifest runs a PostgreSQL database makes it available on localhost:5432 inside its pod.

• Another container defined inside that same pod runs an Ockam node as a companion to the postgres container. The Ockam node container is created using this dockerfile and this entrypoint script. The enrollment ticket from run.sh is passed to the container.

• When the Ockam node container starts in the Bank Corp cluster, it runs its entrypoint. The entrypoint script creates a new identity and uses the enrollment ticket to enroll with your project and get a project membership credential that attests to the attribute postgres-outlet=true. The run function assigned this attribute to the enrollment ticket.

• The entrypoint script then creates a node that uses this identity and membership credential to authenticate and create a relay in the project, back to the node, at relay address: postgres. The run function gave the enrollment ticket permission to use this relay address.

• Next, the entrypoint sets an access control policy that only allows project members that possesses a credential with attribute postgres-inlet="true" to connect to tcp portal outlets on this node. It then creates tcp portal outlet to postgres at localhost:5432.

Analysis Corp

• Analysis Corp.’s kubernetes manifest defines a pod and containers to run in Analysis Corp.’s isolated kubernetes cluster. The run.sh script invokes kind to create the cluster, prepares container images and calls kubectl apply to start the pod and its containers. The manifest defines a pod with two containers an Ockam node container and an app container.

• The Ockam node container is created using this dockerfile and this entrypoint script. The enrollment ticket from run.sh is passed to the container.

• When the Ockam node container starts in the Analysis Corp network, it runs its entrypoint. The entrypoint script creates a new identity and uses the enrollment ticket to enroll with your project and get a project membership credential that attests to the attribute postgres-inlet=true. The run function assigned this attribute to the enrollment ticket.

• The entrypoint script then creates a node that uses this identity and membership credential. It then sets an access control policy that only allows project members that possesses a credential with attribute postgres-outlet="true" to connect to tcp portal inlets on this node.

• Next, the entrypoint creates tcp portal inlet that makes the remote postgres available on all localhost IPs at 0.0.0.0:15432. This makes postgres available at localhost:15432 within Analysis Corp’s pod that also has the app container.

• The app container is created using this dockerfile which runs this app.js file on startup. The app.js file is a nodejs app, it connects with postgres on localhost:15432, then creates a table in the database, inserts some data into the table, queries it back, and prints it.

Recap

We connected a nodejs app in one kubernetes cluster with a postgres database in another kubernetes cluster over an end-to-end encrypted portal.

Sensitive business data in the postgres database is only accessible to Bank Corp. and Analysis Corp. All data is encrypted with strong forward secrecy as it moves through the Internet. The communication channel is mutually authenticated and authorized. Keys and credentials are automatically rotated. Access to connect with postgres can be easily revoked.

Analysis Corp. does not get unfettered access to Bank Corp.’s cluster. It gets access only to run queries on the postgres server. Bank Corp. does not get unfettered access to Analysis Corp.’s cluster. It gets access only to respond to queries over a tcp connection. Bank Corp. cannot initiate connections.

All access controls are secure-by-default. Only project members, with valid credentials, can connect with each other. NAT’s are traversed using a relay and outgoing tcp connections. Bank Corp. or Analysis Corp. don’t expose any listening endpoints on the Internet. Their kubernetes clusters are completely closed and protected from any attacks from the Internet.

Cleanup

To delete all containers and images:

./run.sh cleanup

Let's connect a nodejs app in one one private kubernetes cluster with a mongodb database in another private kubernetes cluster. The example uses docker and docker compose to create these virtual networks.

Each company’s network is private, isolated, and doesn't expose ports. To learn how end-to-end trust is established, please read: “How does Ockam work?”

Run

This example requires Bash, Git, Curl, Kind, and Kubectl. Please set up these tools for your operating system, then run the following commands:

# Clone the Ockam repo from Github.
git clone --depth 1 https://github.com/build-trust/ockam && cd ockam

# Navigate to this example’s directory.
cd examples/command/portals/databases/mongodb/kubernetes

# Run the example, use Ctrl-C to exit at any point.
./run.sh

If everything runs as expected, you'll see the message: The example run was successful 🥳

Walkthrough

The run.sh script, that you ran above, and its accompanying files are full of comments and meant to be read. The example setup is only a few simple steps, so please take some time to read and explore.

Administrator

• The run.sh script calls the run function which invokes the enroll command to create an new identity, sign into Ockam Orchestrator, set up a new Ockam project, make you the administrator of this project, and get a project membership credential.

• The run function then generates two new enrollment tickets. The tickets are valid for 10 minutes. Each ticket can be redeemed only once and assigns attributes to its redeemer. The first ticket is meant for the Ockam node that will run in Bank Corp.’s kubernetes cluster. The second ticket is for the Ockam node that will run in Analysis Corp.’s kubernetes cluster.

• In a typical production setup an administrator or provisioning pipeline generates enrollment tickets and gives them to nodes that are being provisioned. In our example, the run function is acting on your behalf as the administrator of the Ockam project. It uses kubernetes secrets to give tickets to Ockam nodes that are being provisioned in Bank Corp.’s and Analysis Corp.’s kubernetes clusters.

• The run function takes the enrollment tickets, sets them as kubernetes secrets, and uses kind with kubectl to create Bank Corp.’s and Analysis Corp.’s kubernetes clusters.

Bank Corp

• Bank Corp.’s kubernetes manifest defines a pod and containers to run in Bank Corp’s isolated kubernetes cluster. The run.sh script invokes kind to create the cluster, prepares container images and calls kubectl apply to start the pod and its containers.

• One of the containers defined in Bank Corp.’s kubernetes manifest runs a MongoDB database makes it available on localhost:5432 inside its pod.

• Another container defined inside that same pod runs an Ockam node as a companion to the mongodb container. The Ockam node container is created using this dockerfile and this entrypoint script. The enrollment ticket from run.sh is passed to the container.

• When the Ockam node container starts in the Bank Corp cluster, it runs its entrypoint. The entrypoint script creates a new identity and uses the enrollment ticket to enroll with your project and get a project membership credential that attests to the attribute mongodb-outlet=true. The run function assigned this attribute to the enrollment ticket.

• The entrypoint script then creates a node that uses this identity and membership credential to authenticate and create a relay in the project, back to the node, at relay address: mongodb. The run function gave the enrollment ticket permission to use this relay address.

• Next, the entrypoint sets an access control policy that only allows project members that possesses a credential with attribute mongodb-inlet="true" to connect to tcp portal outlets on this node. It then creates tcp portal outlet to mongodb at localhost:5432.

Analysis Corp

• Analysis Corp.’s kubernetes manifest defines a pod and containers to run in Analysis Corp.’s isolated kubernetes cluster. The run.sh script invokes kind to create the cluster, prepares container images and calls kubectl apply to start the pod and its containers. The manifest defines a pod with two containers an Ockam node container and an app container.

• The Ockam node container is created using this dockerfile and this entrypoint script. The enrollment ticket from run.sh is passed to the container.

• When the Ockam node container starts in the Analysis Corp network, it runs its entrypoint. The entrypoint script creates a new identity and uses the enrollment ticket to enroll with your project and get a project membership credential that attests to the attribute mongodb-inlet=true. The run function assigned this attribute to the enrollment ticket.

• The entrypoint script then creates a node that uses this identity and membership credential. It then sets an access control policy that only allows project members that possesses a credential with attribute mongodb-outlet="true" to connect to tcp portal inlets on this node.

• Next, the entrypoint creates tcp portal inlet that makes the remote mongodb available on all localhost IPs at 0.0.0.0:15432. This makes mongodb available at localhost:15432 within Analysis Corp’s pod that also has the app container.

• The app container is created using this dockerfile which runs this app.js file on startup. The app.js file is a nodejs app, it connects with mongodb on localhost:15432, then creates a table in the database, inserts some data into the table, queries it back, and prints it.

Recap

We connected a nodejs app in one kubernetes cluster with a mongodb database in another kubernetes cluster over an end-to-end encrypted portal.

Sensitive business data in the mongodb database is only accessible to Bank Corp. and Analysis Corp. All data is encrypted with strong forward secrecy as it moves through the Internet. The communication channel is mutually authenticated and authorized. Keys and credentials are automatically rotated. Access to connect with mongodb can be easily revoked.

Analysis Corp. does not get unfettered access to Bank Corp.’s cluster. It gets access only to run queries on the mongodb server. Bank Corp. does not get unfettered access to Analysis Corp.’s cluster. It gets access only to respond to queries over a tcp connection. Bank Corp. cannot initiate connections.

All access controls are secure-by-default. Only project members, with valid credentials, can connect with each other. NAT’s are traversed using a relay and outgoing tcp connections. Bank Corp. or Analysis Corp. don’t expose any listening endpoints on the Internet. Their kubernetes clusters are completely closed and protected from any attacks from the Internet.

Cleanup

To delete all containers and images:

./run.sh cleanup

Let's connect a nodejs app in one private network with a postgres database in another private network.

Each company’s network is private, isolated, and doesn't expose ports. To learn how end-to-end trust is established, please read: “How does Ockam work?”

Run

This example requires Bash, Git, Curl, Docker, and Docker Compose. Please set up these tools for your operating system, then run the following commands:

# Clone the Ockam repo from Github.
git clone --depth 1 https://github.com/build-trust/ockam && cd ockam

# Navigate to this example’s directory.
cd examples/command/portals/databases/postgres/docker

# Run the example, use Ctrl-C to exit at any point.
./run.sh

If everything runs as expected, you'll see the message: The example run was successful 🥳

Walkthrough

The run.sh script, that you ran above, and its accompanying files are full of comments and meant to be read. The example setup is only a few simple steps, so please take some time to read and explore.

Administrator

• The run.sh script calls the run function which invokes the enroll command to create an new identity, sign into Ockam Orchestrator, set up a new Ockam project, make you the administrator of this project, and get a project membership credential.

• The run function then generates two new enrollment tickets. The tickets are valid for 10 minutes. Each ticket can be redeemed only once and assigns attributes to its redeemer. The first ticket is meant for the Ockam node that will run in Bank Corp.’s network. The second ticket is meant for the Ockam node that will run in Analysis Corp.’s network.

• In a typical production setup an administrator or provisioning pipeline generates enrollment tickets and gives them to nodes that are being provisioned. In our example, the run function is acting on your behalf as the administrator of the Ockam project. It uses environment variables to give tickets to and provision Ockam nodes in Bank Corp.’s and Analysis Corp.’s network.

• The run function takes the enrollment tickets, sets them as the value of an environment variable, and invokes docker-compose to create Bank Corp.’s and Analysis Corp.’s networks.

Bank Corp

# Create a dedicated and isolated virtual network for bank_corp.
networks:
  bank_corp:
    driver: bridge

• Bank Corp.’s docker-compose configuration is used when run.sh invokes docker-compose. It creates an isolated virtual network for Bank Corp.

• In this network, docker compose starts a container with a PostgreSQL database. This container becomes available at postgres:5432 in the Bank Corp network.

• Once the postgres container is ready, docker compose starts an Ockam node in a container as a companion to the postgres container. The Ockam node container is created using this dockerfile and this entrypoint script. The enrollment ticket from run.sh is passed to the container.

• When the Ockam node container starts in the Bank Corp network, it runs its entrypoint. The entrypoint script creates a new identity and uses the enrollment ticket to enroll with your project and get a project membership credential that attests to the attribute postgres-outlet=true. The run function assigned this attribute to the enrollment ticket.

• The entrypoint script then creates a node that uses this identity and membership credential to authenticate and create a relay in the project, back to the node, at relay address: postgres. The run function gave the enrollment ticket permission to use this relay address.

• Next, the entrypoint sets an access control policy that only allows project members that possesses a credential with attribute postgres-inlet="true" to connect to tcp portal outlets on this node. It then creates tcp portal outlet to postgres at postgres:5432.

Analysis Corp

# Create a dedicated and isolated virtual network for analysis_corp.
networks:
  analysis_corp:
    driver: bridge

• Analysis Corp.’s docker-compose configuration is used when run.sh invokes docker-compose. It creates an isolated virtual network for Analysis Corp. In this network, docker compose starts an Ockam node container and an app container.

• The Ockam node container is created using this dockerfile and this entrypoint script. The enrollment ticket from run.sh is passed to the container.

• When the Ockam node container starts in the Analysis Corp network, it runs its entrypoint. The entrypoint script creates a new identity and uses the enrollment ticket to enroll with your project and get a project membership credential that attests to the attribute postgres-inlet=true. The run function assigned this attribute to the enrollment ticket.

• The entrypoint script then creates a node that uses this identity and membership credential. It then sets an access control policy that only allows project members that possesses a credential with attribute postgres-outlet="true" to connect to tcp portal inlets on this node.

• Next, the entrypoint creates tcp portal inlet that makes the remote postgres available on all localhost IPs at 0.0.0.0:15432. This makes postgres available at ockam:15432 within Analysis Corp’s virtual private network.

• Once the Ockam node container is ready, docker compose starts an app container. The app container is created using this dockerfile which runs this app.js file on startup.

• The app.js file is a nodejs app, it connects with postgres on ockam:15432, then creates a table in the database, inserts some data into the table, queries it back, and prints it.

Recap

We connected a nodejs app in one virtual private network with a postgres database in another virtual private network over an end-to-end encrypted portal.

Sensitive business data in the postgres database is only accessible to Bank Corp. and Analysis Corp. All data is encrypted with strong forward secrecy as it moves through the Internet. The communication channel is mutually authenticated and authorized. Keys and credentials are automatically rotated. Access to connect with postgres can be easily revoked.

Analysis Corp. does not get unfettered access to Bank Corp.’s network. It gets access only to run queries on the postgres server. Bank Corp. does not get unfettered access to Analysis Corp.’s network. It gets access only to respond to queries over a tcp connection. Bank Corp. cannot initiate connections.

All access controls are secure-by-default. Only project members, with valid credentials, can connect with each other. NAT’s are traversed using a relay and outgoing tcp connections. Bank Corp. or Analysis Corp. don’t expose any listening endpoints on the Internet. Their networks are completely closed and protected from any attacks from the Internet.

Cleanup

To delete all containers and images:

./run.sh cleanup

Let's connect a nodejs app in one virtual private network with a MongoDB database in another virtual private network. The example uses docker and docker compose to create these virtual networks.

Each company’s network is private, isolated, and doesn't expose ports. To learn how end-to-end trust is established, please read: “How does Ockam work?”

Run

This example requires Bash, Git, Curl, Docker, and Docker Compose. Please set up these tools for your operating system, then run the following commands:

# Clone the Ockam repo from Github.
git clone --depth 1 https://github.com/build-trust/ockam && cd ockam

# Navigate to this example’s directory.
cd examples/command/portals/databases/mongodb/docker

# Run the example, use Ctrl-C to exit at any point.
./run.sh

If everything runs as expected, you'll see the message: The example run was successful 🥳

Walkthrough

The run.sh script, that you ran above, and its accompanying files are full of comments and meant to be read. The example setup is only a few simple steps, so please take some time to read and explore.

Administrator

• The run.sh script calls the run function which invokes the enroll command to create an new identity, sign into Ockam Orchestrator, set up a new Ockam project, make you the administrator of this project, and get a project membership credential.

• The run function then generates two new enrollment tickets. The tickets are valid for 10 minutes. Each ticket can be redeemed only once and assigns attributes to its redeemer. The first ticket is meant for the Ockam node that will run in Bank Corp.’s network. The second ticket is meant for the Ockam node that will run in Analysis Corp.’s network.

• In a typical production setup an administrator or provisioning pipeline generates enrollment tickets and gives them to nodes that are being provisioned. In our example, the run function is acting on your behalf as the administrator of the Ockam project. It uses environment variables to give tickets to and provision Ockam nodes in Bank Corp.’s and Analysis Corp.’s network.

• The run function takes the enrollment tickets, sets them as the value of an environment variable, and invokes docker-compose to create Bank Corp.’s and Analysis Corp.’s networks.

Bank Corp

# Create a dedicated and isolated virtual network for bank_corp.
networks:
  bank_corp:
    driver: bridge

• Bank Corp.’s docker-compose configuration is used when run.sh invokes docker-compose. It creates an isolated virtual network for Bank Corp.

• In this network, docker compose starts a container with a MongoDB database. This container becomes available at mongodb:27017 in the Bank Corp network.

• Once the mongodb container is ready, docker compose starts an Ockam node in a container as a companion to the mongodb container. The Ockam node container is created using this dockerfile and this entrypoint script. The enrollment ticket from run.sh is passed to the container.

• When the Ockam node container starts in the Bank Corp network, it runs its entrypoint. The entrypoint script creates a new identity and uses the enrollment ticket to enroll with your project and get a project membership credential that attests to the attribute mongodb-outlet=true. The run function assigned this attribute to the enrollment ticket.

• The entrypoint script then creates a node that uses this identity and membership credential to authenticate and create a relay in the project, back to the node, at relay address: mongodb. The run function gave the enrollment ticket permission to use this relay address.

• Next, the entrypoint sets an access control policy that only allows project members that possesses a credential with attribute mongodb-inlet="true" to connect to tcp portal outlets on this node. It then creates tcp portal outlet to mongodb at mongodb:27017.

Analysis Corp

# Create a dedicated and isolated virtual network for analysis_corp.
networks:
  analysis_corp:
    driver: bridge

• Analysis Corp.’s docker-compose configuration is used when run.sh invokes docker-compose. It creates an isolated virtual network for Analysis Corp. In this network, docker compose starts an Ockam node container and an app container.

• The Ockam node container is created using this dockerfile and this entrypoint script. The enrollment ticket from run.sh is passed to the container.

• When the Ockam node container starts in the Analysis Corp network, it runs its entrypoint. The entrypoint script creates a new identity and uses the enrollment ticket to enroll with your project and get a project membership credential that attests to the attribute mongodb-inlet=true. The run function assigned this attribute to the enrollment ticket.

• The entrypoint script then creates a node that uses this identity and membership credential. It then sets an access control policy that only allows project members that possesses a credential with attribute mongodb-outlet="true" to connect to tcp portal inlets on this node.

• Next, the entrypoint creates tcp portal inlet that makes the remote mongodb available on all localhost IPs at 0.0.0.0:17017. This makes mongodb available at ockam:17017 within Analysis Corp’s virtual private network.

• Once the Ockam node container is ready, docker compose starts an app container. The app container is created using this dockerfile which runs this app.js file on startup.

• The app.js file is a nodejs app, it connects with mongodb on ockam:17017, then inserts some data, queries it back, and prints it.

Recap

We connected a nodejs app in one virtual private network with a MongoDB database in another virtual private network over an end-to-end encrypted portal.

Sensitive business data in the MongoDB database is only accessible to Bank Corp. and Analysis Corp. All data is encrypted with strong forward secrecy as it moves through the Internet. The communication channel is mutually authenticated and authorized. Keys and credentials are automatically rotated. Access to connect with MongoDB can be easily revoked.

Analysis Corp. does not get unfettered access to Bank Corp.’s network. It gets access only to run queries on the MongoDB server. Bank Corp. does not get unfettered access to Analysis Corp.’s network. It gets access only to respond to queries over a tcp connection. Bank Corp. cannot initiate connections.

All access controls are secure-by-default. Only project members, with valid credentials, can connect with each other. NAT’s are traversed using a relay and outgoing tcp connections. Bank Corp. or Analysis Corp. don’t expose any listening endpoints on the Internet. Their networks are completely closed and protected from any attacks from the Internet.

Cleanup

To delete all containers and images:

./run.sh cleanup

Let's connect a nodejs app in one Amazon VPC with an Amazon RDS managed Postgres database in another Amazon VPC.

Each company’s network is private, isolated, and doesn't expose ports. To learn how end-to-end trust is established, please read: “How does Ockam work?”

Run

This example requires Bash, Git, and AWS CLI. Please set up these tools for your operating system. In particular you need to login to your AWS account with aws sso login.

Then run the following commands:

# Clone the Ockam repo from Github.
git clone --depth 1 https://github.com/build-trust/ockam && cd ockam

# Navigate to this example’s directory.
cd examples/command/portals/databases/postgres/amazon_rds/aws_cli

# Run the example, use Ctrl-C to exit at any point.
./run.sh

If everything runs as expected, you'll see the message: The example run was successful 🥳

Walkthrough

The run.sh script, that you ran above, and its accompanying files are full of comments and meant to be read. The example setup is only a few simple steps, so please take some time to read and explore.

Administrator

• The run.sh script calls the run function which invokes the enroll command to create an new identity, sign into Ockam Orchestrator, set up a new Ockam project, make you the administrator of this project, and get a project membership credential.

• The run function then generates two new enrollment tickets. The tickets are valid for 10 minutes. Each ticket can be redeemed only once and assigns attributes to its redeemer. The first ticket is meant for the Ockam node that will run in Bank Corp.’s network. The second ticket is meant for the Ockam node that will run in Analysis Corp.’s network.

• In a typical production setup an administrator or provisioning pipeline generates enrollment tickets and gives them to nodes that are being provisioned. In our example, the run function is acting on your behalf as the administrator of the Ockam project.

• The run function passes the enrollment tickets as variables of the run scripts provisioning Bank Corp.'s network and Analysis Corp.'s network.

Bank Corp

First, the bank_corp/run.sh script creates a network to host the database:

• We create a VPC and tag it.

• We create an Internet gateway and attach it to the VPC.

• We create a route table and create a route to the Internet via the gateway.

• We create two subnets, located in two distinct availability zones, and associated to the route table.

• We finally create a security group so that there is:

  • One TCP egress to the Internet,

  • And one ingress to Postgres from within our two subnets.

Then, the bank_corp/run.sh script creates a RDS database:

• This requires a subnet group.

• Once the subnet group is created, we create a database cluster an a database instance.

• Finally the address of the database is saved in an environment variable.

We are now ready to create an EC2 instance where the Ockam outlet node will run:

• We select an AMI.

• We start an instance using the AMI above and a start script based on run_ockam.sh where:

  • ENROLLMENT_TICKET is replaced by the enrollment ticket created by the administrator and given as a parameter to run.sh.

  • POSTGRES_ADDRESS is replaced by the database address that we previously saved.

• We tag the created instance and wait for it to be available.

When the instance is started, the run_ockam.sh script is executed:

• The ockam executable is installed.

• The enrollment ticket is used to create a default identity and make it a project member.

• We then create an Ockam node:

  • With a TCP outlet.

  • A policy associated to the outlet. The policy authorizes identities with a credential containing the attribute postgres-inlet="true".

  • With a relay capable of forwarding the TCP traffic to the TCP outlet.

Analysis Corp

First, the analysis_corp/run.sh script creates a network to host the nodejs application:

• We create a VPC and tag it.

• We create an Internet gateway and attach it to the VPC.

• We create a route table and create a route to the Internet via the gateway.

• We create a subnet, and associated to the route table.

• We finally create a security group so that there is:

  • One TCP egress to the Internet,

  • And One SSH ingress to download and install the nodejs application.

We are now ready to create an EC2 instance where the Ockam inlet node will run:

• We select an AMI.

• We start an instance using the AMI above and a start script based on run_ockam.sh where:

  • ENROLLMENT_TICKET is replaced by the enrollment ticket created by the administrator and given as a parameter to run.sh.

The instance is started and the run_ockam.sh script is executed:

• The ockam executable is installed.

• The enrollment ticket is used to create a default identity and make it a project member.

• We then create an Ockam node:

  • With a TCP inlet.

  • A policy associated to the inlet. The policy authorizes identities with a credential containing the attribute postgres-outlet="true".

We finally wait for the instance to be ready and install the nodejs application:

• The app.js file copied to the instance (this uses the previously created key.pem file to identify).

• We can then SSH to the instance and:

  • Install nodejs.

  • Install the Postgres client library.

  • Start the nodejs application.

Once the nodejs application is started:

• It will connect to the Ockam inlet at port 12345.

• It creates a database table and runs some SQL queries to check that the connection with the Postgres database works.

Recap

We connected a nodejs app in one virtual private network with a postgres database in another virtual private network over an end-to-end encrypted portal.

Sensitive business data in the postgres database is only accessible to Bank Corp. and Analysis Corp. All data is encrypted with strong forward secrecy as it moves through the Internet. The communication channel is mutually authenticated and authorized. Keys and credentials are automatically rotated. Access to connect with postgres can be easily revoked.

Analysis Corp. does not get unfettered access to Bank Corp.’s network. It gets access only to run queries on the postgres server. Bank Corp. does not get unfettered access to Analysis Corp.’s network. It gets access only to respond to queries over a tcp connection. Bank Corp. cannot initiate connections.

All access controls are secure-by-default. Only project members, with valid credentials, can connect with each other. NAT’s are traversed using a relay and outgoing tcp connections. Bank Corp. or Analysis Corp. don’t expose any listening endpoints on the Internet. Their networks are completely closed and protected from any attacks from the Internet.

Cleanup

To delete all AWS resources:

./run.sh cleanup

In this hands-on example we send end-to-end encrypted messages through Confluent Cloud.

Ockam encrypts messages from a Producer all-of-the-way to a specific Consumer. Only that specific Consumer can decrypt these messages. This guarantees that your data cannot be observed or tampered with as it passes through Confluent Cloud or the network where it is hosted. The operators of Confluent Cloud can only see encrypted data in the network and in service that they operate. Thus, a compromise of the operator's infrastructure will not compromise the data stream's security, privacy, or integrity.

To learn how end-to-end trust is established, please read: “How does Ockam work?”

Run

This example requires Bash, Confluent CLI, JQ, Git, Curl, Docker, and Docker Compose. Please set up these tools for your operating system, login to Confluent using your Confluent CLI so that clusters can be created and deleted, then run the following commands:

# Clone the Ockam repo from Github.
git clone --depth 1 https://github.com/build-trust/ockam && cd ockam

# Navigate to this example’s directory.
cd examples/command/portals/kafka/confluent/

# Run the example, use Ctrl-C to exit at any point.
./run.sh

If everything runs as expected, you'll see the message: The example run was successful 🥳

Walkthrough

The run.sh script, that you ran above, and its accompanying files are full of comments and meant to be read. The example setup is only a few simple steps, so please take some time to read and explore.

Administrator

• The run.sh script calls the run function which invokes the enroll command to create an new identity, sign in to Ockam Orchestrator, set up a new Ockam project, make you the administrator of this project, and get a project membership credential.

• The run function then creates a new Kafka cluster using the Confluent CLI.

• An Ockam relay is then started using the ockam confluent addon which creates an encrypted relay that transmits Kafka messages over a secure portal.

• We then generate two new enrollment tickets, each valid for 10 minutes, and can be redeemed only once. The two tickets are meant for the Consumer and Producer, in the Ockam node that will run in Application Team’s network.

• In a typical production setup, an administrator or provisioning pipeline generates enrollment tickets and gives them to nodes that are being provisioned. In our example, the run function is acting on your behalf as the administrator of the Ockam project. It creates a Kafka relay using a pre-baked Ockam confluent addon which will host the Confluent Kafka server and Application Team’s network, passing them their tickets using environment variables.

• For the Application team, the run function takes the enrollment tickets, sets them as the value of an environment variable, passes the Confluent authentication variables and invokes docker-compose to create the Application Teams’s networks.

Application Teams

# Create a dedicated and isolated virtual network for application_team.
networks:
  application_team:
      driver: bridge

• Application Teams’s docker-compose configuration is used when run.sh invokes docker-compose. It creates an isolated virtual network for Application Teams. In this network, docker compose starts a Kafka Consumer container and a Kafka Producer container.

• The Kafka consumer node container is created using this dockerfile and this entrypoint script. The consumer enrollment ticket from run.sh is passed to the container via environment variable.

• When the Kafka consumer node container starts in the Application Teams network, it runs its entrypoint. The entrypoint enrolls with your project and then calls the Ockam kafka-consumer command which starts the Kafka inlet and listens and traffic connection on localhost port 9092 through Ockam relay.

• Next, the entrypoint at the end executes the command present in the docker-compose configuration, which launches a Kafka consumer waiting for messages in the demo topic. Once the messages are received, they are printed out.

• In the producer container, the process is analogous, once the Ockam kafka-producer inlet is set up, the command within docker-compose configuration launches a Kafka producer that sends messages.

• You can view the Confluent website to see the encrypted messages as they are being sent by the producer.

Recap

We sent end-to-end encrypted messages through Confluent cloud.

Messages are encrypted with strong forward secrecy as soon as they leave a Producer, and only the intended Consumer can decrypt those messages. Confluent Cloud and other Consumers can only see encrypted messages.

All communication is mutually authenticated and authorized. Keys and credentials are automatically rotated. Access can be easily revoked.

Cleanup

To delete all containers and images:

./run.sh cleanup

In this hands-on example we send end-to-end encrypted messages through Warpstream Cloud.

Ockam encrypts messages from a Producer all-of-the-way to a specific Consumer. Only that specific Consumer can decrypt these messages. This guarantees that your data cannot be observed or tampered with as it passes through Warpstream Cloud or the network where it is hosted. The operators of Warpstream Cloud can only see encrypted data in the network and in service that they operate. Thus, a compromise of the operator's infrastructure will not compromise the data stream's security, privacy, or integrity.

To learn how end-to-end trust is established, please read: “How does Ockam work?”

Run

This example requires Bash, Git, Curl, Docker, and Docker Compose. Please set up these tools for your operating system. It's also necessary to include your warpstream application key as an environment variable when running the example, example can be run as following:

# Clone the Ockam repo from Github.
git clone --depth 1 https://github.com/build-trust/ockam && cd ockam

# Navigate to this example’s directory.
cd examples/command/portals/kafka/warpstream/

# Run the example by calling the run.sh script and passing your warpstream application key as an argument, use Ctrl-C to exit at any point.
./run.sh _warpstream_application_key_

If everything runs as expected, you'll see the message: The example run was successful 🥳

Walkthrough

The run.sh script, that you ran above, and its accompanying files are full of comments and meant to be read. The example setup is only a few simple steps, so please take some time to read and explore.

Administrator

• The run.sh script calls the run function which invokes the enroll command to create a new identity, sign in to Ockam Orchestrator, set up a new Ockam project, make you the administrator of this project, and get a project membership credential.

• The run function then creates a new Kafka cluster by using your Warpstream's application key.

• An Ockam relay is then started using the Ockam Kafka addon which creates an encrypted relay that transmits Kafka messages over a secure portal.

• We then generate two new enrollment tickets, each valid for 10 minutes, and can be redeemed only once. The two tickets are meant for the Consumer and Producer, in the Ockam node that will run in Application Team’s network.

• In a typical production setup, an administrator or provisioning pipeline generates enrollment tickets and gives them to nodes that are being provisioned. In our example, the run function is acting on your behalf as the administrator of the Ockam project. It creates a Kafka relay using a pre-baked Ockam Kafka addon which will host the Warpstream Kafka server and Application Team’s network, passing them their tickets using environment variables.

• For the Application team, the run function takes the enrollment tickets, sets them as the value of an environment variable, passes the Warpstream authentication variables and invokes docker-compose to create the Application Teams’s networks.

Application Teams

# Create a dedicated and isolated virtual network for application_team.
networks:
  application_team:
      driver: bridge

• Application Teams’s docker-compose configuration is used when run.sh invokes docker-compose. It creates an isolated virtual network for Application Teams. In this network, docker compose starts a Kafka Consumer container and a Kafka Producer container.

• The Kafka consumer node container is created using this dockerfile and this entrypoint script. The consumer enrollment ticket from run.sh is passed to the container via environment variable.

• When the Kafka consumer node container starts in the Application Teams network, it runs its entrypoint. The entrypoint enrolls with your project and then calls the Ockam kafka-consumer command which starts the Kafka inlet and listens and traffic connection on localhost port 9092 through Ockam relay.

• Next, the entrypoint at the end executes the command present in the docker-compose configuration, which launches a Kafka consumer waiting for messages in the demo topic. Once the messages are received, they are printed out.

• In the producer container, the process is analogous, once the Ockam kafka-producer inlet is set up, the command within docker-compose configuration launches a Kafka producer that sends messages.

Recap

We sent end-to-end encrypted messages through Warpstream cloud.

Messages are encrypted with strong forward secrecy as soon as they leave a Producer, and only the intended Consumer can decrypt those messages. Warpstream Cloud and other Consumers can only see encrypted messages.

All communication is mutually authenticated and authorized. Keys and credentials are automatically rotated. Access can be easily revoked.

Cleanup

To delete all containers and images:

./run.sh cleanup _warpstream_application_key

In the previous section, we learned how Ockam Routing and Transports create a foundation for end-to-end application layer protocols. When discussing Transports, we put together a specific example communication topology – a transport bridge.

Bridges

Node n1 wishes to access a service on node n3, but it can't directly connect to n3. This can happen for many reasons, maybe because n3 is in a separate IP subnet, or it could be that the communication from n1 to n2 uses UDP while from n2 to n3 uses TCP or other similar constraints. The topology makes n2 a bridge or gateway between these two separate networks to enable end-to-end protocols between n1 and n3 even though they are not directly connected.

Relays

It is common, however, to encounter communication topologies where the machine that provides a service is unwilling or is not allowed to open a listening port or expose a bridge node to other networks. This is a common security best practice in enterprise environments, home networks, OT networks, and VPCs across clouds. Application developers may not have control over these choices from the infrastructure / operations layer. This is where relays are useful.

Relays make it possible to establish end-to-end protocols with services operating in a remote private network, without requiring a remote service to expose listening ports to an outside hostile network like the Internet.

Delete any existing nodes and then try this new example:

» ockam node create n2 --tcp-listener-address=127.0.0.1:7000

» ockam node create n3
» ockam service start hop --at n3
» ockam relay create n3 --at /node/n2 --to /node/n3
     ✔︎ Now relaying messages from /node/n2/service/25716d6f86340c3f594e99dede6232df → /node/n3/service/forward_to_n3

» ockam node create n1
» ockam tcp-connection create --from n1 --to 127.0.0.1:7000
» ockam message send hello --from n1 --to /worker/603b62d245c9119d584ba3d874eb8108/service/forward_to_n3/service/uppercase
HELLO

In this example, the direction of the second TCP connection is reversed in comparison to our first example that used a bridge. n2 is the only node that has to listen for TCP connections.

Node n2 is running a relay service. n3 makes an outgoing TCP connection to n2 and requests a forwarding address from the relay service. n3 then becomes reachable via n2 at the address /service/forward_to_n3.

Node n1 connects with n2 and routes messages to n3 via its forwarding relay.

The message in the above example took the following route. This is very similar to our earlier example except for the direction of the second TCP connection. The relay worker remembers the route to back to n3. n1 just has to get the message to the forwarding relay and everything just works.

Using this simple topology rearrangement, Ockam Routing makes it possible to establish end-to-end protocols between applications that are running in completely private networks.

We can traverse NATs and pierce through network boundaries. And since this is all built using a very simple application layer routing protocol, we can have any number of transport connection hops in any transport protocol, and we can mix-match bridges with relays to create end-to-end protocols in any communication topology.

Portals

Portals make existing protocols work over Ockam Routing without changing any code in the existing applications.

Continuing from our Relays example, create a Python-based web server to represent a sample web service. This web service is listening on 127.0.0.1:9000.

» python3 -m http.server --bind 127.0.0.1 9000

» ockam tcp-outlet create --at n3 --from /service/outlet --to 127.0.0.1:9000
» ockam tcp-inlet create --at n1 --from 127.0.0.1:6000 \
    --to /worker/603b62d245c9119d584ba3d874eb8108/service/forward_to_n3/service/hop/service/outlet

» curl --head 127.0.0.1:6000
HTTP/1.0 200 OK
...

Then create a TCP Portal Outlet that makes 127.0.0.1:9000 available on worker address /service/outlet on n3. We already have a forwarding relay for n3 on n2 at service/forward_to_n3.

We then create a TCP Portal Inlet on n1 that will listen for TCP connections to 127.0.0.1:6000. For every new connection, the inlet creates a portal following the --to route all the way to the outlet. As it receives TCP data, it chunks and wraps them into Ockam Routing messages and sends them along the supplied route. The outlet receives Ockam Routing messages, unwraps them to extract TCP data and sends that data along to the target web service on 127.0.0.1:9000. It all just seamlessly works.

The HTTP requests from curl enter the inlet on n1, travel to n2, and are relayed back to n3 via its forwarding relay to reach the outlet and onward to the Python-based web service. Responses take the same return route back to curl.

The TCP Inlet/Outlet work for a large number of TCP-based protocols like HTTP. It is also simple to implement portals for other transport protocols. There is a growing base of Ockam Portal Add-Ons in our GitHub Repository.

Recap

Ockam Routing and Transports combined with the ability to model Bridges and Relays make it possible to create end-to-end, application layer protocols in any communication topology - across networks, clouds, and boundaries.

Portals take this powerful capability a huge step forward by making it possible to apply these end-to-end protocols and their guarantees to existing applications, without changing any code!

This lays the foundation to make both new and existing applications - end-to-end encrypted and secure-by-design.

Next, let's learn how to create cryptographic identities and store secret keys in safe vaults.

Let's connect a nodejs app in one AWS VPC with a MongoDB database that resides in another AWS VPC. The example uses docker and docker compose to create these virtual networks.

Each company’s network is private, isolated, and doesn't expose ports. To learn how end-to-end trust is established, please read: “”

Run

This example requires Bash, Git, Curl, and AWS CLI. Please set up these tools for your operating system, then run the following commands:

If everything runs as expected, you'll see the message: The example run was successful 🥳

Walkthrough

The , that you ran above, and its are full of comments and meant to be read. The example setup is only a few simple steps, so please take some time to read and explore.

Administrator

• The calls the which invokes the to create a new identity, sign into Ockam Orchestrator, set up a new Ockam project, make you the administrator of this project, and get a project membership .

• The run function then . The tickets are valid for 10 minutes. Each ticket can be redeemed only once and assigns to its redeemer. The is meant for the Ockam node that will run in Bank Corp.’s network. The is meant for the Ockam node that will run in Analysis Corp.’s network.

• In a typical production setup, an administrator or provisioning pipeline generates enrollment tickets and gives them to nodes that are being provisioned. In our example, the run function is acting on your behalf as the administrator of the Ockam project. It passes the enrollment tickets as a to provision Ockam nodes in Bank Corp network and also passes the enrollment key as an to provision Ockam nodes in Analysis Corp.’s network.

• For Bank Corp, the run function calls a which will create an Amazon VPC that will host our MongoDB instance over a closed network this will be hosted by Bank Corp.

• For Analysis Corp, we will also call a which will run a nodejs app that will write to our mongoDB data hosted by Bank Corp.

Bank Corp

First, the bank_corp/run.sh script creates a network to host the database:

• We and tag it.

• We and attach it to the VPC.

• We and to the Internet via the gateway.

• We , and associate it with the route table.

• We finally so that there is:

  • ,

  • No Outbound connection is allowed for this VPC

Then, the bank_corp/run.sh script creates an EC2 instance where the Ockam outlet node will run:

• We .

• We above and a start script based on run_ockam.sh where the

  created by the administrator and given as a parameter to run.sh.

• We and .

Next, the instance is started and the run_ockam.sh script is executed:

• The .

• The .

• We then create an Ockam node:

  • With .

  • A . The policy authorizes identities with a credential containing the attribute monitoring-api-inlet="true".

  • With capable of forwarding the TCP traffic to the TCP outlet.

Analysis Corp

First, the analysis_corp/run.sh script creates a network to host the nodejs application:

• We and tag it.

• We and attach it to the VPC.

• We and to the Internet via the gateway.

• We , and associate it with the route table.

• We finally so that there is:

  • ,

  • And to download and install the nodejs application.

Then, we create an EC2 instance where the Ockam inlet node will run:

• We .

• We above and a start script based on run_ockam.sh where the

  created by the administrator and given as a parameter to run.sh.

Next, the instance is started and the run_ockam.sh script is executed:

• The .

• The .

• We then create an Ockam node:

  • With .

  • A . The policy authorizes identities with a credential containing the attribute monitoring-api-outlet="true".

Finally, we wait for the instance to be ready and run the nodejs app application:

• The is (this uses the previously created key.pem file to identify).

• We can then and:

  • .

  • .

Recap

We connected a nodejs app in one AWS VPC with a MongoDB database in another AWS VPC over an end-to-end encrypted portal.

Non-public access to MongoDB database are only accessible to enrolled members of the project with the appropriate attributes. The communication channel is and . Keys and credentials are automatically rotated. Access to the API can be easily revoked.

Analysis Corp. does not get unfettered access to Banking Corp.’s network. It only gets access to run queries on the MongoDB server. Bank Corp. does not get unfettered access to Travel App Corp.’s network. It gets access only to respond to requests over a tcp connection. Bank Corp. cannot initiate connections.

All are secure-by-default. Only project members, with valid credentials, can connect with each other. NAT’s are traversed using a relay and outgoing tcp connections. Neither Bank Corp. nor Analysis App Corp. expose any listening endpoints to the Internet. Their networks are completely closed and protected from any attacks from the Internet.

Cleanup

To delete all AWS resources created by this example:

In this hands-on example we send end-to-end encrypted messages through Redpanda.

encrypts messages from a Producer all-of-the-way to a specific Consumer. Only that specific Consumer can decrypt these messages. This guarantees that your data cannot be observed or tampered with as it passes through Redpanda or the network where it is hosted. The operators of Redpanda can only see encrypted data in the network and in service that they operate. Thus, a compromise of the operator's infrastructure will not compromise the data stream's security, privacy, or integrity.

To learn how end-to-end trust is established, please read: “”

Run

This example requires Bash, Git, Curl, Docker, and Docker Compose. Please set up these tools for your operating system, then run the following commands:

If everything runs as expected, you'll see the message: The example run was successful 🥳

Walkthrough

The , that you ran above, and its are full of comments and meant to be read. The example setup is only a few simple steps, so please take some time to read and explore.

Administrator

• The calls the which invokes the to create an new identity, sign in to Ockam Orchestrator, set up a new Ockam project, make you the administrator of this project, and get a project membership .

• The run function then , each valid for 10 minutes, and can be redeemed only once. The is meant for the Ockam node that will run in Redpanda Operator’s network. The are meant for the Consumer and Producer, in the Ockam node that will run in Application Team’s network.

• In a typical production setup, an administrator or provisioning pipeline generates enrollment tickets and gives them to nodes that are being provisioned. In our example, the run function is acting on your behalf as the administrator of the Ockam project. It provisions Ockam nodes in and , passing them their tickets using environment variables.

• The run function takes the enrollment tickets, sets them as the value of an , and to create Redpanda Operator’s and Application Team’s networks.

Redpanda Operator

• Redpanda Operator’s is used when run.sh invokes docker-compose. It creates an for Redpanda Operator.

• In this network, docker compose starts a . This container becomes available at redpanda:9092 in the Redpanda Operator network.

• In the same network, docker compose also starts a , connecting directly to redpanda:9092. The console will be reachable throughout the example at http://127.0.0.1:8080.

• Once the Redpanda container , docker compose starts an as a companion to the Redpanda container described by ockam.yaml, . The node will automatically create an identity, using the ticket , and set up Kafka outlet.

• The Ockam node then uses this identity and membership credential to authenticate and create a relay in the project, back to the node, at relay: redpanda. The run function to use this relay address.

Application Team

• Application Team’s is used when run.sh invokes docker-compose. It creates an for the Application Team. In this network, docker compose starts a and a .

• The Kafka consumer node container is created using and this . The consumer enrollment ticket from run.sh is via environment variable.

• When the Kafka consumer node container starts in the Application Team's network, it runs . The entrypoint creates the Ockam node described by ockam.yaml, . The node will automatically create an identity, , and setup Kafka inlet.

• Next, the entrypoint at the end executes the , which launches a Kafka consumer waiting for messages in the demo topic. Once the messages are received, they are printed out.

• In the producer container, the process is analogous, once the Ockam node is set up the launches a Kafka producer that sends messages.

• You can view the Redpanda console available at http://127.0.0.1:8080 to see the encrypted messages

Recap

We sent end-to-end encrypted messages through Redpanda.

Messages are encrypted with strong forward secrecy as soon as they leave a Producer, and only the intended Consumer can decrypt those messages. Redpanda and other Consumers can only see encrypted messages.

All communication is mutually authenticated and authorized. Keys and credentials are automatically rotated. Access can be easily revoked.

Cleanup

To delete all containers and images:

Credentials

An Ockam Credential is a signed attestation by an Issuer about the Attributes of Subject. The Issuer and Subject are both Ockam . Attributes is a list of name and value pairs.

Issuing Credentials

Any Ockam Identity can issue credentials about another Ockam Identity.

The Issuer can include specific attributes in the attestation:

Verifying Credentials

Storing Credentials

Trust Anchors

Trust and authorization decisions must be anchored in some pre-existing knowledge.

Anchoring Trust in an Access Control List (ACL) of Identifiers

In the previous section about Ockam we ran an example of using pre-existing knowledge of Ockam . In this example n1 knows i2 and n2 know i1:

Anchoring Trust in a Credential Issuer

Managed Authorities

Let's connect a nodejs app in one Amazon VPC with an Amazon RDS managed Postgres database in another Amazon VPC.

Each company’s network is private, isolated, and doesn't expose ports. To learn how end-to-end trust is established, please read: “How does Ockam work?”

Run

This example requires Bash, Git, and AWS CLI. Please set up these tools for your operating system. In particular you need to login to your AWS account with aws sso login.

Then run the following commands:

# Clone the Ockam repo from Github.
git clone --depth 1 https://github.com/build-trust/ockam && cd ockam

# Navigate to this example’s directory.
cd examples/command/portals/databases/postgres/amazon_aurora/aws_cli

# Run the example, use Ctrl-C to exit at any point.
./run.sh

If everything runs as expected, you'll see the message: The example run was successful 🥳

Walkthrough

The run.sh script, that you ran above, and its accompanying files are full of comments and meant to be read. The example setup is only a few simple steps, so please take some time to read and explore.

Administrator

• The run.sh script calls the run function which invokes the enroll command to create an new identity, sign into Ockam Orchestrator, set up a new Ockam project, make you the administrator of this project, and get a project membership credential.

• The run function then generates two new enrollment tickets. The tickets are valid for 10 minutes. Each ticket can be redeemed only once and assigns attributes to its redeemer. The first ticket is meant for the Ockam node that will run in Bank Corp.’s network. The second ticket is meant for the Ockam node that will run in Analysis Corp.’s network.

• In a typical production setup an administrator or provisioning pipeline generates enrollment tickets and gives them to nodes that are being provisioned. In our example, the run function is acting on your behalf as the administrator of the Ockam project.

• The run function passes the enrollment tickets as variables of the run scripts provisioning Bank Corp.'s network and Analysis Corp.'s network.

Bank Corp

First, the bank_corp/run.sh script creates a network to host the database:

• We create a VPC and tag it.

• We create an Internet gateway and attach it to the VPC.

• We create a route table and create a route to the Internet via the gateway.

• We create two subnets, located in two distinct availability zones, and associated to the route table.

• We finally create a security group so that there is:

  • One TCP egress to the Internet,

  • And one ingress to Postgres from within our two subnets.

Then, the bank_corp/run.sh script creates an Aurora database:

• This requires a subnet group.

• Once the subnet group is created, we create a database cluster an a database instance.

• Finally the address of the database is saved in an environment variable.

We are now ready to create an EC2 instance where the Ockam outlet node will run:

• We select an AMI.

• We start an instance using the AMI above and a start script based on run_ockam.sh where:

  • ENROLLMENT_TICKET is replaced by the enrollment ticket created by the administrator and given as a parameter to run.sh.

  • POSTGRES_ADDRESS is replaced by the database address that we previously saved.

• We tag the created instance and wait for it to be available.

When the instance is started, the run_ockam.sh script is executed:

• The ockam executable is installed.

• The enrollment ticket is used to create a default identity and make it a project member.

• We then create an Ockam node:

  • With a TCP outlet.

  • A policy associated to the outlet. The policy authorizes identities with a credential containing the attribute postgres-inlet="true".

  • With a relay capable of forwarding the TCP traffic to the TCP outlet.

Analysis Corp

First, the analysis_corp/run.sh script creates a network to host the nodejs application:

• We create a VPC and tag it.

• We create an Internet gateway and attach it to the VPC.

• We create a route table and create a route to the Internet via the gateway.

• We create a subnet, and associated to the route table.

• We finally create a security group so that there is:

  • One TCP egress to the Internet,

  • And One SSH ingress to download and install the nodejs application.

We are now ready to create an EC2 instance where the Ockam inlet node will run:

• We select an AMI.

• We start an instance using the AMI above and a start script based on run_ockam.sh where:

  • ENROLLMENT_TICKET is replaced by the enrollment ticket created by the administrator and given as a parameter to run.sh.

The instance is started and the run_ockam.sh script is executed:

• The ockam executable is installed.

• The enrollment ticket is used to create a default identity and make it a project member.

• We then create an Ockam node:

  • With a TCP inlet.

  • A policy associated to the inlet. The policy authorizes identities with a credential containing the attribute postgres-outlet="true".

We finally wait for the instance to be ready and install the nodejs application:

• The app.js file is copied to the instance (this uses the previously created key.pem file to identify).

• We can then SSH to the instance and:

  • Install nodejs.

  • Install the Postgres client library.

  • Start the nodejs application.

Once the nodejs application is started:

• It will connect to the Ockam inlet at port 12345.

• It creates a database table and runs some SQL queries to check that the connection with the Postgres database works.

Recap

We connected a nodejs app in one virtual private network with a postgres database in another virtual private network over an end-to-end encrypted portal.

Sensitive business data in the postgres database is only accessible to Bank Corp. and Analysis Corp. All data is encrypted with strong forward secrecy as it moves through the Internet. The communication channel is mutually authenticated and authorized. Keys and credentials are automatically rotated. Access to connect with postgres can be easily revoked.

Analysis Corp. does not get unfettered access to Bank Corp.’s network. It gets access only to run queries on the postgres server. Bank Corp. does not get unfettered access to Analysis Corp.’s network. It gets access only to respond to queries over a tcp connection. Bank Corp. cannot initiate connections.

All access controls are secure-by-default. Only project members, with valid credentials, can connect with each other. NAT’s are traversed using a relay and outgoing tcp connections. Bank Corp. or Analysis Corp. don’t expose any listening endpoints on the Internet. Their networks are completely closed and protected from any attacks from the Internet.

Cleanup

To delete all AWS resources:

./run.sh cleanup

Data, within modern applications, routinely flows over complex, multi-hop, multi-protocol routes before reaching its end destination. It's common for application layer requests and data to move across network boundaries, beyond data centers, via shared or public networks, through queues and caches, from gateways and brokers to reach remote services and other distributed parts of an application.

Ockam is designed to enable end-to-end application layer guarantees in any communication topology.

For example, Ockam Secure Channels provide end-to-end guarantees of data authenticity, integrity, and privacy in any of the above communication topologies. In contrast, 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.

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.

To make matters worse, if you don't set up another mutually authenticated TLS connection on the second hop between the gateway and your destination server, then the entire second hop network – which may have thousands of applications and machines within it – becomes an attack vector to your application and its data. If any of these neighboring applications or machines are compromised, then your application and its data can also be easily compromised.

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.

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. 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.

Routing

Let's start by creating a node and sending a message to a service on that node.

» ockam reset -y
» ockam node create n1
» ockam message send 'Hello Ockam!' --to /node/n1/service/echo
Hello Ockam!

We get a reply back and the message flow looked like this.

To achieve this, Ockam Routing Protocol messages carry with them two metadata fields: onward_route and return_route. A route is an ordered list of addresses describing a message's path travel. All of this information is carried in a really compact binary format.

Pay very close attention to the Sender, Hop, and Replier rules in the sequence diagrams below. Note how onward_route and return_route are handled as the message travels.

The above was just one message hop. We can extend this to two hops:

» ockam service start hop --addr h1
» ockam message send hello --to /node/n1/service/h1/service/echo
hello

This very simple protocol can extend to any number of hops, try following command:

» ockam service start hop --addr h2
» ockam message send hello --to /node/n1/service/h1/service/h2/service/echo
hello

So far, we've routed messages between Workers on one Node. Next, let's see how we can route messages across nodes and machines using Ockam Routing adapters called Transports.

Transports

Ockam Transports adapt Ockam Routing for specific transport protocol, like TCP, UDP, WebSockets, Bluetooth etc. There is a growing base of Ockam Transport implementations in the Ockam GitHub Repository.

Let's start by exploring TCP transport. Create two new nodes: n2 and n3 and explicitly specify that they should listen on the local TCP addresses 127.0.0.1:7000 and 127.0.0.1:8000 respectively:

» ockam node create n2 --tcp-listener-address=127.0.0.1:7000
» ockam node create n3 --tcp-listener-address=127.0.0.1:8000

Next, let's create two TCP connections, one from n1 to n2 and the other from n2 to n3. Let's also add a hop for routing purposes:

» ockam service start hop --at n2
» ockam tcp-connection create --from n1 --to 127.0.0.1:7000
» ockam tcp-connection create --from n2 --to 127.0.0.1:8000

Note, from the output, that the TCP connection from n1 to n2 on n1 has worker address ac40f7edbf7aca346b5d44acf82d43ba and the TCP connection from n2 to n3 on n2 has the worker address 7d2f9587d725311311668075598e291e. We can combine this information to send a message over two TCP hops.

» ockam message send hello --from n1 --to /worker/ac40f7edbf7aca346b5d44acf82d43ba/service/hop/worker/7d2f9587d725311311668075598e291e/service/uppercase
HELLO

The message in the above command took the following route:

In this example, we ran a simple uppercase request and response protocol between n1 and n3, two nodes that weren't directly connected to each other. This simple combination of Ockam Routing and Transports the foundation of end-to-end protocols in Ockam.

We can have any number of TCP hops along the route to the uppercase service. We can also easily have some hops that use a completely different transport protocol, like UDP or Bluetooth. Transport protocols are pluggable, and there is a growing base of Ockam Transport Add-Ons in our GitHub Repository.

Recap

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.

Together they give us a simple yet extremely flexible foundation to describe end-to-end, application layer protocols that can operate in any communication topology.

Next, let's explore how Ockam Relays and Portals make it simple to connect existing applications across networks.

This guide contains instructions to launch within AWS environment, an

• Ockam Outlet Node

• Ockam Inlet Node

The walkthrough demonstrates running both outlet and inlet nodes and verify communication between them.

Read: “How does Ockam work?” to learn about end-to-end trust establishment.

Create an Orchestrator Project

Sign up for Ockam and pick a subscription plan through the guided workflow on Ockam.io.

Run the following commands to install Ockam Command and enroll with the Ockam Orchestrator.

curl --proto '=https' --tlsv1.2 -sSfL https://install.command.ockam.io | bash
source "$HOME/.ockam/env"

ockam enroll

Completing this step creates a Project in Ockam Orchestrator.

Control which identities are allowed to enroll themselves into your project by issuing unique one-time use enrollment tickets. Generate two enrollment tickets, one for the Outlet and one for the Inlet.

Generate enrollment tickets

# Enrollment ticket for Ockam Outlet Node
ockam project ticket --expires-in 10h --usage-count 1 \
  --attribute example-outlet \
  --relay outlet \
    > "outlet.ticket"

# Enrollment ticket for Ockam Inlet Node
ockam project ticket --expires-in 10h --usage-count 1 \
  --attribute example-inlet \
    > "inlet.ticket"
    

Setup Ockam Outlet Node

• Login to AWS Account you would like to use

• Subscribe to "Ockam - Node" in AWS Marketplace

• Navigate to AWS Marketplace -> Manage subscriptions. Select Ockam - Node from the list of subscriptions. Select Actions-> Launch Cloudformation stack

• Select the Region you want to deploy and click Continue to Launch. Under Actions, select Launch Cloudformation

• Create stack with below details

  • Stack name: example-outlet or any name you prefer

  • Network Configuration

    • Select suitable values for VPC ID and Subnet ID

      • Default instance type is m6a.8xlarge because of the predictable network bandwidth of 12.5 Gbps. Adjust instance type if you need to

  • Ockam Configuration

    • Enrollment ticket: Copy and paste the content of the outlet.ticket generated above

    • JSON Node Configuration: Copy and paste the below configuration.

{
    "relay": "outlet",
    "tcp-outlet": {
        "to": "localhost:7777",
        "allow": "example-inlet"
    }
}

• Click Next to launch the CloudFormation run.

• A successful CloudFormation stack run configures the Ockam outlet node on an EC2 machine.

• EC2 machine mounts an EFS volume created in the same subnet. Ockam state is stored in the EFS volume.

• Connect to the EC2 machine via AWS Session Manager. To view the log file, run sudo cat /var/log/cloud-init-output.log.

• View the Ockam node status in CloudWatch.

  • Navigate to Cloudwatch -> Log Group and select example-outet-ockam-status-logs. Select the Logstream for the EC2 instance.

  • Cloudformation template creates a subscription filter that sends data to a Cloudwatch alarm example-outlet-OckamNodeDownAlarm.Alarm will turn green upon ockam node successfully running.

• An Autoscaling group ensures atleast one EC2 instance is running at all times.

Set up a webhook on the ec2 machine to validate connectivity

• Run python3 /opt/webhook_receiver.py to start the webhook that will listen on port 7777. We will send traffic to this webhook after inlet is setup, so keep the terminal window open.

Setup Ockam Inlet Node

• Login to AWS Account you would like to use

• Subscribe to "Ockam - Node" in AWS Marketplace

• Navigate to AWS Marketplace -> Manage subscriptions. Select Ockam - Node from the list of subscriptions. Select Actions-> Launch Cloudformation stack

• Select the Region you want to deploy and click Continue to Launch. Under Actions, select Launch Cloudformation

• Create stack with below details

  • Stack name: example-inlet or any name you prefer

  • Network Configuration

    • Select suitable values for VPC ID and Subnet ID

      • Default instance type is m6a.8xlarge because of the predictable network bandwidth of 12.5 Gbps. Adjust instance type if you need to

  • Ockam Configuration

    • Enrollment ticket: Copy and paste the content of the outlet.ticket generated above

    • JSON Node Configuration: Copy and paste the below configuration.

{
    "tcp-inlet": {
      "from": "0.0.0.0:17777",
      "via": "outlet",
      "allow": "example-outlet"
    }
}

• Click Next to launch the CloudFormation run.

• A successful CloudFormation stack run configures the Ockam inlet node on an EC2 machine.

• EC2 machine mounts an EFS volume created in the same subnet. Ockam state is stored in the EFS volume.

• Connect to the EC2 machine via AWS Session Manager. To view the log file, run sudo cat /var/log/cloud-init-output.log.

• View the Ockam node status in CloudWatch.

  • Navigate to Cloudwatch -> Log Group and select example-inlet-ockam-status-logs. Select the Logstream for the EC2 instance.

  • Cloudformation template creates a subscription filter that sends data to a Cloudwatch alarm example-inlet-OckamNodeDownAlarm.Alarm will turn green upon ockam node successfully running.

• An Autoscaling group ensures atleast one EC2 instance is running at all times.

Validate Connectivity

• Connect to the EC2 machine via AWS Session Manager.

• Run the command below to post a request to the Inlet address. You must receive a response. Verify that the request reaches the webhook running on the Outlet machine.

curl -X POST http://localhost:17777/webhook -H "Content-Type: application/json" -d "{\"from\": \"$(hostname)\"}"

A Successful setup receives a response back

# Inlet EC2
sh-5.2$ curl -X POST http://localhost:17777/webhook -H "Content-Type: application/json" -d "{\"from\": \"$(hostname)\"}"
Webhook received

You will also see the request received in the Outlet EC2 machine

# Outlet EC2
sh-5.2$ python3 /opt/webhook_receiver.py
2024-07-24 19:56:32,984 - __main__ - INFO - Webhook server running on port 7777...
127.0.0.1 - - [24/Jul/2024 19:56:36] "POST /webhook HTTP/1.1" 200 -
2024-07-24 19:58:01,341 - __main__ - INFO - Received webhook: {"from": "REDACTED.REDACTED.compute.internal"}

You have now successfully created an Ockam Portal and verified secure communication 🎉.

Cleanup

• Delete the example-outletCloudFormation stack from the AWS Account.

• Delete the example-inlet CloudFormation stack from the AWS Account.

• Delete ockam configuration files from the machine that the administrator used to generate enrollment tickets.

ockam reset

Create an Ockam Portal to send end-to-end encrypted messages through Aiven.

Ockam encrypts messages from a Producer all-of-the-way to a specific Consumer. Only that specific Consumer can decrypt these messages. This guarantees that your data cannot be observed or tampered with as it passes through Aiven or the network where it is hosted. The operators of Aiven can only see encrypted data in the network and in service that they operate. Thus, a compromise of the operator's infrastructure will not compromise the data stream's security, privacy, or integrity.

To learn how end-to-end trust is established, please read: “How does Ockam work?”

Please select an example to dig in:

Now that we understand the basics of Nodes, Workers, and Routing ... let's create our first encrypted secure channel.

Establishing a secure channel requires establishing a shared secret key between the two entities that wish to communicate securely. This is usually achieved using a cryptographic key agreement protocol to safely derive a shared secret without transporting it over the network.

Running such protocols requires a stateful exchange of multiple messages and having a worker and routing system allows Ockam to hide the complexity of creating and maintaining a secure channel behind two simple functions:

• create_secure_channel_listener(...) which waits for requests to create a secure channel.

• create_secure_channel(...) which initiates the protocol to create a secure channel with a listener.

Responder node

Create a new file at:

Add the following code to this file:

Middle node

Create a new file at:

Add the following code to this file:

Initiator node

Create a new file at:

Add the following code to this file:

Run

Run the responder in a separate terminal tab and keep it running:

Run the middle node in a separate terminal tab and keep it running:

Run the initiator:

Note the message flow.

At Ockam's core is a collection of cryptographic and messaging protocols. These protocols enable private and secure by design applications that provide end-to-end application layer trust in data.

Ockam is designed to make these protocols easy and safe to use in any application environment – from highly scalable cloud services to tiny battery operated microcontroller based devices.

Many included protocols require multiple steps and have complicated internal state that must be managed with care. Protocol steps can often be initiated by any participant so it can be quite challenging to make these protocols simple to use, secure, and platform independent.

Ockam , , and help hide this complexity to provide simple interfaces for stateful and asynchronous message-based protocols.

Nodes

An Ockam Node is any program that can interact with other Ockam Nodes using various Ockam protocols like Ockam Routing and Ockam Secure Channels.

A typical Ockam Node is implemented as an asynchronous execution environment that can run very lightweight, concurrent, stateful actors called Ockam . Using Ockam , a node can deliver messages from one worker to another local worker. Using Ockam Transports, nodes can also route messages to workers on other remote nodes.

In the following code snippet we create a node in Rust and then immediately stop it:

A node requires an asynchronous runtime to concurrently execute workers. The default Ockam Node implementation in Rust uses tokio, a popular asynchronous runtime in the Rust ecosystem. There are also Ockam Node implementations that support various no_std embedded targets.

Nodes can be implemented in any language. The only requirement is that understand various Ockam protocols like Routing, Secure Channels, Identities etc.

Workers

Ockam run very lightweight, concurrent, and stateful actors called Ockam Workers. They are like processes on your operating system, except that they all live inside one node and are very lightweight so a node can have hundreds of thousands of them, depending on the capabilities of the machine hosting the node.

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 worker. In response to a message, a worker can: make local decisions, change internal state, create more workers, or send more messages.

Echoer worker

To create a worker, we create a struct that can optionally have some fields to store the worker's internal state. If the worker is stateless, it can be defined as a field-less unit struct.

This struct:

• Must implement the ockam::Worker trait.

• Must have the #[ockam::worker] attribute on the Worker trait implementation.

• Must define two associated types Context and Message

  • The Context type is set to ockam::Context.

  • The Message type must be set to the type of messages the worker wishes to handle.

App worker

When a new node starts and calls an async main function, it turns that function into a worker with address of "app". This makes it easy to send and receive messages from the main function (i.e the "app" worker).

In the code below, we start a new Echoer worker at address "echoer", send this "echoer" a message "Hello Ockam!" and then wait to receive a String reply back from the "echoer".

Message Flow

The message flow looked like this:

Next, let’s explore how Ockam’s Application Layer Routing enables us to create protocols that provide end-to-end guarantees.

Please select specific marketplace listings to view