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

• enroll
• space
• space-admin
• project
• sidecar
• share
• node
• worker
• message
• relay
• tcp-listener
• tcp-connection
• tcp-outlet
• tcp-inlet
• influxdb-inlet
• influxdb-outlet
• kafka-inlet
• kafka-outlet
• secure-channel-listener
• secure-channel
• vault
• identity
• credential
• authority
• policy
• lease
• status
• reset
• completion
• environment
• flow-control

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.