Ockam Command Manual

ockam

ockam [OPTIONS] <COMMAND>

Orchestrate end-to-end encryption, mutual authentication, key management, credential management, and authorization policy enforcement — at scale.

Modern applications are distributed and have an unwieldy number of interconnections that must trustfully exchange data. Ockam makes it simple to build secure by-design applications that have granular control over every trust and access decision.

Subcommands

Examples

Let's walk through a simple example to create an end-to-end encrypted, mutually authenticated, secure and private cloud relay – for any application.

First let's enroll with Ockam Orchestrator where we'll create a managed cloud based relay that will move end-to-end encrypted data between distributed parts of our application.

# Create a cryptographic identity and enroll with Ockam Orchestrator.
# This will sign you up for an account with Ockam Orchestrator and setup a
# hobby space and project for you.
$ ockam enroll

You can also create encrypted relays outside the orchestrator. See ockam relay --help.

Application Service

Next let's prepare the service side of our application.

# Start our application service, listening on a local ip and port, that clients
# would access through the cloud relay. We'll use a simple http server for our
# first example but this could be some other application service.
$ python3 -m http.server --bind 127.0.0.1 5000

# Setup an ockam node, called blue, as a sidecar next to our application service.
$ ockam node create blue

# Create a tcp outlet on the blue node to send raw tcp traffic to the application service.
$ ockam tcp-outlet create --at /node/blue --to 127.0.0.1:5000

# Then create a relay at your default orchestrator project to blue.
$ ockam relay create blue --to /node/blue

Application Client

Now on the client side

# Setup an ockam node, called green, as a sidecar next to our application service.
$ ockam node create green

# Then create an end-to-end encrypted secure channel with blue, through the cloud relay.
# Then tunnel traffic from a local tcp inlet through this end-to-end secure channel.
$ ockam secure-channel create --from /node/green \\
    --to /project/default/service/forward_to_blue/service/api \\
        | ockam tcp-inlet create --at /node/green --from 127.0.0.1:7000 --to -/service/outlet

# Access the application service though the end-to-end encrypted, secure relay.
$ curl 127.0.0.1:7000

We just created end-to-end encrypted, mutually authenticated, and authorized secure communication between a tcp client and server. This client and server can be running in separate private networks / NATs. We didn't have to expose our server by opening a port on the Internet or punching a hole in our firewall.

The two sides authenticated and authorized each other's known, cryptographically provable identifiers. In later examples we'll see how we can build granular, attribute-based access control with authorization policies.

ockam enroll

ockam enroll [OPTIONS]

When you run this command for the first time, it creates a space for you in Ockam Orchestrator, the SaaS service. This is where you host your projects, as well as a default project for you within this space.

It also generates a unique cryptographically provable identity and saves the corresponding key in a vault. This identity is issued a membership credential that will be used to manage the resources in your project. Optionally, you can pass an existing identity.