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]

The enroll command enrolls your Ockam Identity with Ockam Orchestrator.

It involves multiple steps. In the first step, if you specify an Identity using the --identity argument, the command uses it. If you don't specify an Identity, it checks if you have a default Identity. If you have one, the command uses this default Identity. If you do not have a default Identity, the command generates a new Identity in your default Vault. If you do not have a default Vault, the command creates a new one on your file system, makes it the default Vault, and uses it to store the private keys of your new Identity.

You will also need to use your web browser to type in a one-time code in order to activate the machine you are using to run the enroll command. You will then be required to log in to your Orchestrator account to complete activating this machine. To do so, you can choose to authenticate using GitHub or create a new email and password. If you choose the latter, then you will need to verify your email address.

Orchestrator is a SaaS product that allows remote relays, add-ons integration like Confluent, Okta, etc. If this is your first time signing in, the Orchestrator creates a new dedicated Space and Project for you. A Project offers two services: a Membership Authority and a Relay service.

The enroll command then asks this Project’s Membership Authority to sign and issue a Credential that attests that your Identifier is a member of this Project. Since your account in Orchestrator is the creator and hence first administrator on this new Project, the Membership Authority issues this Credential. The command stores the Credential for later use and exits.