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: “How does Ockam work?”

Please select an example to dig in:

Let’s build a simple example together. We will create an encrypted Ockam Portal 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

Sign up for Ockam 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 Authority and a Relay 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.

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

ockam enroll

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

1. creates an Ockam Node on your machine.

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

3. creates a local Vault to store keys.

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

5. asks your Project’s Membership Authority to issue and sign a membership Credential 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

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

ockam enroll

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

ockam tcp-outlet create --to 5432

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

ockam relay create postgres

This command

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

2. creates a Secure Channel 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

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

ockam enroll

Create a Portal Inlet in this Node in Azure

ockam tcp-inlet create --from 15432 --via postgres

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 Secure Channel 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

psql --host localhost --port 15432

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

There’s so much more….

This is just one simple example. Ockam’s stack of protocols 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

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

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.

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.

• 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

• Sessions recover from network failures

• ...and lots more!

How Ockam is different from a Network layer connector

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

Please select an example to dig in:

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

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: “How does Ockam work?”

Please select an example to dig in:

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

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 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 Amazon VPC with a Amazon Timestream managed InfluxDB database in another Amazon VPC. We’ll create an end-to-end encrypted Ockam Portal to InfluxDB.

To understand the details of 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: “How does Ockam work?”

Run

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

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/influxdb/amazon_timestream/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 Metrics Corp.’s network. The second ticket is meant for the Ockam node that will run in Datastream 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 Metrics Corp.'s network and Datastream Corp.'s network.

Metrics Corp

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

• It creates a VPC and tags it.

• It creates an Internet gateway and attaches it to the VPC.

• It creates a route table and a route to the Internet via the gateway.

• It creates a subnet and associates it with the route table.

• It creates a security group which allows:

  • TCP egress to the Internet.

  • Ingress to InfluxDB from within the subnet.

  • SSH ingress to provision EC2 instances.

Then, the metrics_corp/run.sh script creates a InfluxDB database using Timestream. Next the script creates an EC2 instance. This instance runs an Ockam TCP Outlet.

• It selects an AMI.

• It then starts an instance using this AMI 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.

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

• It tags the created instance and waits for it to be available.

When EC2 starts the instance, it executes the run_ockam.sh script:

• It installs the Influxdb client and configures it.

• It generates an InfluxDB auth token to send to Datastream Corp and saves it to file.

• It installs the ockam command.

• It uses the enrollment ticket to create a default identity and make it a project member.

• It then creates an Ockam node with:

  • A TCP outlet.

  • An access control policy associated to the outlet. The policy authorizes only identities with a credential attesting to the attribute influxdb-inlet="true".

  • A a relay that can forward TCP traffic to the TCP outlet.

Datastream Corp

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

• It creates a VPC and tags it.

• It creates an Internet gateway and attaches it to the VPC.

• It creates a route table and a route to the Internet via the gateway.

• It creates a subnet and associates it with the route table.

• It creates a security group that allows:

  • TCP egress to the Internet,

  • SSH ingress to provision EC2 instances.

Next, the script creates an EC2 instance. This instance runs an Ockam TCP Inlet.

• It selects an AMI.

• It then starts an instance using that AMI and a start script based on run_ockam.sh in which the:

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

When EC2 starts the instance, it executes the run_ockam.sh script:

• It installs ockam command.

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

• It then creates an Ockam node with:

  • A TCP inlet.

  • An access control policy associated with the inlet. The policy authorizes identities with a credential attesting to the attribute influxdb-outlet="true".

Next datastream_corp/run.sh waits for the instance to be ready and provisions it using SSH:

• It copies app.js and token.txt into the instance using SCP

• It then runs a script, using SSH, which:

  • Installs nodejs.

  • Installs the InfluxDB client library.

  • Starts the nodejs application.

Finally, the nodejs application is started:

• It connects to the Ockam inlet at localhost:8086.

• It inserts a few system metrics into a bucket and retrieves them back to show that the connection with the InfluxDB database is working.

Recap

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

Sensitive business data in the InfluxDB database is only accessible to Metrics Corp. and Datastream 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 InfluxDB can be easily revoked.

Datastream Corp. does not get unfettered access to Metrics Corp.’s network. It gets access only to query InfluxDB. Metrics Corp. does not get unfettered access to Datastream Corp.’s network. It gets access only to respond to queries over a tcp connection. Metrics 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. Metrics Corp. or Datastream 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

This section contains hands-on examples that use Ockam 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: “How does Ockam work?”

Please select an example to dig in:

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:

Let's connect a nodejs app in one AWS VPC with a nodejs API in another AWS VPC. The example uses AWS CLI to create these VPCs.

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.

# 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/apis/nodejs/amazon_ec2/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 60 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 Monitoring Corp.’s network. The second ticket is meant for the Ockam node that will run in Travel App 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 Monitoring Corp.’s network and Travel App Corp.’s network.

Monitoring Corp

First, the monitoring_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 a subnet, and associate it with the route table.

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

  • One TCP egress to the Internet,

  • And one SSH ingress to install nodejs and run the API service.

Then, the monitoring_corp/run.sh script creates 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 the

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

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

Next, 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 outlet.

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

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

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

• The api.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 dependencies.

  • Run the nodejs api application.

Travel App Corp

First, the travel_app_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 associate it with 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.

Then, we 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 the

  ENROLLMENT_TICKET is replaced by the enrollment ticket 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 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 monitoring-api-outlet="true".

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

• The client.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.

  • Run the nodejs client application.

Recap

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

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

Travel App Corp. does not get unfettered access to Monitoring Corp.’s network. It only gets access to the API service. Monitoring Corp. does not get unfettered access to Travel App Corp.’s network. It gets access only to respond to requests over a tcp connection. Monitoring 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. Neither Monitoring Corp. nor Travel 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:

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

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: “How does Ockam work?”

Please select an example to dig in:

Let's connect a python app in one AWS VPC with a python API in another AWS VPC. The example uses AWS CLI to create these VPCs.

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.

# 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/apis/python/amazon_ec2/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 60 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 Monitoring Corp.’s network. The second ticket is meant for the Ockam node that will run in Travel App 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 Monitoring Corp.’s network and Travel App Corp.’s network.

Monitoring Corp

First, the monitoring_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 a subnet, and associate it with the route table.

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

  • One TCP egress to the Internet,

  • And one SSH ingress to install python and run the API service.

Then, the monitoring_corp/run.sh script creates 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 the

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

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

Next, 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 outlet.

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

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

Finally, we wait for the instance to be ready and run the python api application:

• The app.py 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 python.

  • Install dependencies.

  • Run the python flask api application.

Travel App Corp

First, the travel_app_corp/run.sh script creates a network to host the python 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 associate it with 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 python application.

Then, we 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 the

  ENROLLMENT_TICKET is replaced by the enrollment ticket 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 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 monitoring-api-outlet="true".

Finally, we wait for the instance to be ready and run the python client application:

• The client.py 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 python.

  • Install dependencies.

  • Run the python client application.

Recap

We connected a python app in one AWS VPC with a python API service in another AWS VPC over an end-to-end encrypted portal.

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

Travel App Corp. does not get unfettered access to Monitoring Corp.’s network. It only gets access to the API service. Monitoring Corp. does not get unfettered access to Travel App Corp.’s network. It gets access only to respond to requests over a tcp connection. Monitoring 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. Neither Monitoring Corp. nor Travel 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:

./run.sh cleanup

Let's connect a nodejs app in one virtual private network with an application serving a self hosted model in another virtual private network. The example uses the AWS CLI 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, and the 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/ai/amazon_ec2

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

If everything runs as expected, you'll see the answer to the question: "What is Ockham's Razor?".

Walkthrough

The run.sh script 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 AI Corp.’s network. The second ticket is meant for the Ockam node that will run in Health 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 AI Corp.'s network and Health Corp.'s network.

AI Corp

First, the ai_corp/run.sh script creates a network to host the application exposing the LLaMA model API:

• 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, with associate it 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 install the model and its application.

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

• We select an AMI.

• We create a key pair in order to access the EC2 instance via SSH.

• Before creating the EC2 instance we check that the AWS region we are using proposes this kind of instance type. Indeed, we need properly sized instance in order to run a large language model, and those instances are not available in all regions. If the instance is not available in the current region, we return the list of all the regions where that instance type is available.

• We start an instance using the selected AMI and right instance type. Starting the instance executes a start script based on ai_corp/run_ockam.sh where:

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

• 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 ai-inlet="true".

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

Health Corp

First, the health_corp/run.sh script creates a network to host the client.js application which will connect to the LLaMA model:

• 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 associate it 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 client 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.

  • Connected to the ai relay.

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

We finally wait for the instance to be ready and install the client.js application:

• The client.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.

  • Start the client.js application.

Once the client.js application is started:

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

• It sends a query and waits for a response from the model.

• The response is then printed on the console.

Recap

We connected a nodejs application in one virtual private network with an application serving a LLaMA model in another virtual private network over an end-to-end encrypted portal.

Sensitive business data coming from the model is only accessible to AI Corp. and Health 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 the model API can be easily revoked.

Health Corp. does not get unfettered access to AI Corp.’s network. It gets access only to run API queries. AI Corp. does not get unfettered access to Health Corp.’s network. It gets access only to respond to queries over a TCP connection. AI 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. AI Corp. or Health 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

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:

Let's connect a python app in one virtual private network with an Azure OpenAI model configured with private endpoint in another virtual private network. You will use the Azure CLI to create these virtual networks and resources.

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?”

Create an Orchestrator Project

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

2. Run the following commands to install Ockam Command and enroll with the Ockam Orchestrator. This step creates a Project in Ockam Orchestrator.

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

ockam enroll

Run

This example requires Bash, Git, Curl, and the Azure CLI. Please set up these tools for your operating system. In particular you need to login to your Azure with az 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/ai/azure_openai

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

If everything runs as expected, you'll see the answer to the question: "What is Ockham's Razor?".

Walkthrough

The run.sh script 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 60 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 AI Corp.’s network. The second ticket is meant for the Ockam node that will run in Health 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 AI Corp.'s network and Health Corp.'s network.

AI Corp

First, the ai_corp/run.sh script creates a network to host the application exposing the Azure OpenAI Service Endpoint

• Network Infrastructure:

  • We create an Azure Resource Group to contain all resources.

  • We create a Virtual Network (VNet) with a subnet to host the services.

• Azure OpenAI Service Configuration:

  • We deploy an Azure OpenAI Service instance.

  • We set up a private endpoint for secure access:

    • Create a private endpoint connection.

    • Establish a private DNS zone.

    • Link the DNS zone to the virtual network.

    • Configure DNS records for private endpoint resolution.

    • Disable public network access and Update network ACLs to deny public access.

• OpenAI Model Deployment:

  • We deploy the specified model (gpt-4o-mini) on the OpenAI service.

  • We retrieve the API key for authentication.

  • We create an environment file (.env.azure) containing:

    • The Azure OpenAI endpoint URL.

    • The API key for authentication.

• Virtual Machine Deployment:

  • We process the Ockam setup script (run_ockam.sh) by replacing variables:

    • Replaces SERVICE_NAME and TICKET placeholders.

  • We create a Red Hat Enterprise Linux VM:

    • Place it in the configured VNet/subnet.

    • Generate SSH keys for access.

    • Inject the processed Ockam setup script as custom data.

    • The default Network Security Group (NSG) is configured with basic rules: inbound SSH access (port 22), internal virtual network communication, Azure Load Balancer access, and a final deny rule for all other inbound traffic. For outbound, it allows virtual network and internet traffic, with a final deny rule for all other outbound traffic.

Health Corp

First, the health_corp/run.sh script creates a network to host the client.py application which will connect to the Azure OpenAI model:

• Network Infrastructure Setup:

  • We create an Azure Resource Group to contain all resources.

  • We create a Virtual Network (VNet) with a subnet to host the services.

• VM Deployment and Ockam Setup:

  • We process the run_ockam.sh script by replacing:

    • ${SERVICE_NAME} with the configured service name.

    • ${TICKET} with the provided enrollment ticket.

  • We create a Red Hat Enterprise Linux 8 VM where the Ockam inlet node will run:

    • Use latest RHEL 8 LVM Gen2 image.

    • Generate SSH keys automatically.

    • Inject the processed Ockam setup script as custom data.

• Client Application Deployment:

  • We wait for VM to be accessible.

  • We copy required files to the VM:

    • Transfers client.py to the VM.

    • Copies .env.azure configuration file containing OpenAI credentials.

  • We set up the Python environment:

    • Install Python 3.9 and pip.

    • Install the OpenAI SDK.

  • We execute the client application.

• Client Application Operation:

  • The client.py application:

    • Connects to the Azure OpenAI service using credentials from .env.azure.

    • Sends queries to the model.

    • Receives and displays responses on the console.

Recap

We connected a Python application in one virtual network with an application serving an Azure OpenAI model in another virtual network over an end-to-end encrypted portal.

Sensitive business data coming from the Azure OpenAI model is only accessible to AI Corp. and Health 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 the model API can be easily revoked.

Health Corp. does not get unfettered access to AI Corp.'s network. It gets access only to run API queries to the Azure OpenAI service. AI Corp. does not get unfettered access to Health Corp.'s network. It gets access only to respond to queries over a TCP connection. AI Corp. cannot initiate connections.

All access controls are secure-by-default. Only project members, with valid credentials, can connect with each other. NATs are traversed using a relay and outgoing TCP connections. AI Corp. or Health Corp. don't expose any listening endpoints on the Internet. Their Azure virtual networks are completely closed and protected from any attacks from the Internet through Network Security Groups (NSGs) that only allow essential communications.

Cleanup

To delete all Azure resources:

./run.sh cleanup

Let's connect a nodejs app in one virtual private network with an application serving an Amazon Bedrock model in another virtual private network. The example uses the AWS CLI 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, and the 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/ai/amazon_bedrock

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

If everything runs as expected, you'll see the answer to the question: "What is Ockham's Razor?".

Walkthrough

The run.sh script 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 AI Corp.’s network. The second ticket is meant for the Ockam node that will run in Health 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 AI Corp.'s network and Health Corp.'s network.

AI Corp

First, the ai_corp/run.sh script creates a network to host the application exposing the Bedrock model API:

• We create a VPC and tag it.

• We enable DNS attributes and hostnames for the VPC. This will be used to create the private link below.

• 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, with associate it to the route table.

• We create a security group so that there is:

  • One TCP egress to the Internet,

  • And one SSH ingress to install the server application accessing the model.

• We finally create a private link to the Amazon Bedrock service to allow the Bedrock client inside the server application to access the Bedrock model.

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

• We select an AMI.

• We create a key pair in order to access the EC2 instance via SSH.

• We start an instance using the selected AMI. Starting the instance executes a start script based on ai_corp/run_ockam.sh where:

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

• We tag the created instance

• We create an IAM profile with a role allowing the EC2 instance to access the Bedrock API

• We 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 ai-inlet="true".

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

Health Corp

First, the health_corp/run.sh script creates a network to host the client.js application which will connect to the Bedrock model:

• 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 associate it 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 client 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.

  • Forwarding messages to the ai relay

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

We finally wait for the instance to be ready and install the client.js application:

• The client.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.

  • Start the client.js application.

Once the client.js application is started:

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

• It sends a query and waits for a response from the model.

• The response is then printed on the console.

Recap

We connected a nodejs application in one virtual private network with an application serving an Amazon Bedrock model in another virtual private network over an end-to-end encrypted portal.

Sensitive business data coming from the model is only accessible to AI Corp. and Health 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 the model API can be easily revoked.

Health Corp. does not get unfettered access to AI Corp.’s network. It gets access only to run API queries. AI Corp. does not get unfettered access to Health Corp.’s network. It gets access only to respond to queries over a TCP connection. AI 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. AI Corp. or Health 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

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: “How does Ockam work?”

Run

This example requires Bash, Git, Curl, and AWS CLI. 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/amazon_vpc

# 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 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 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 passes the enrollment tickets as a function argument to provision Ockam nodes in Bank Corp network and also passes the enrollment key as an function argument to provision Ockam nodes in Analysis Corp.’s network.

• For Bank Corp, the run function calls a run.sh script 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 run.sh script 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 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 associate it with the route table.

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

  • One TCP egress to the Internet,

  • 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 select an AMI.

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

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

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

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

• MongoDB is installed using yum package installer

• 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 monitoring-api-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 associate it with 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.

Then, we 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 the

  ENROLLMENT_TICKET is replaced by the enrollment ticket 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 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 monitoring-api-outlet="true".

Finally, we wait for the instance to be ready and run the nodejs app 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.

  • Run the nodejs client application.

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 mutually authenticated and authorized. 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 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. 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:

./run.sh cleanup

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

Please select an example to dig in:

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

Please select an example to dig in:

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.

Please select an example to dig in:

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

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

Administrator

Kafka Operator

Application Team

Recap

We sent end-to-end encrypted messages through Apache Kafka.

Messages are encrypted with strong forward secrecy as soon as they leave a Producer, and only the intended Consumer can decrypt those messages. Kafka brokers 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:

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

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

Administrator

Redpanda Operator

Application Team

• 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:

Let's connect a nodejs app in one company's Amazon VPC with a CodeRepository hosted on a Gitlab Server in another company's Amazon VPC. The example uses AWS CLI to create these VPCs.

Run

Then run the following commands:

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

Walkthrough

Administrator

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

Bank Corp

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

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

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

• • Password can be used to access the gitlab console from local machine

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

• We then create an Ockam node:

Analysis Corp

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

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

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

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

• We then create an Ockam node:

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

Once the nodejs application is started:

Recap

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

Analysis Corp. does not get unfettered access to Bank Corp.’s network. It gets access only to the codebase hosted on the Gitlab 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.

Cleanup

To delete all AWS resources:

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

Please select an example to dig in:

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

Please select an example to dig in:

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

Run

This example requires Bash, Git, jq, 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

Administrator

• • Upon logged in to Instaclustr console, Account API keys can be created from the console by going to gear icon to the top right > Account Settings > API Keys. Create a Provisioning API key and note it down.

  • Alternative to entering the username and API key, you can export them as environment variables INSTACLUSTR_USER_NAME and INSTACLUSTR_API_KEY

Instaclustr Operator