ockam_api

Ockam is a library for building devices that communicate securely, privately and trustfully with cloud services and other devices.

This crate supports the creation of a fully-featured Ockam Node (see NodeManager in src/nodes/service.rs).

Configuration

A NodeManager maintains its configuration as a list of directories and files stored under the OCKAM_HOME directory (~/.ockam) by default: shell root ├─ credentials │ ├─ c1.json │ ├─ c2.json │ └─ ... ├─ defaults │ ├── credential -> ... │ ├── identity -> ... │ ├── node -> ... │ └── vault -> ... ├─ identities │ ├─ data │ │ ├─ authenticated-storage.lmdb │ │ └─ authenticated-storage.lmdb-lock │ ├─ identity1.json │ ├─ identity2.json │ └─ ... ├─ nodes │ ├─ node1 │ │ ├─ default_identity -> ... │ │ ├─ default_vault -> ... │ │ ├─ policies-storage.lmdb │ │ ├─ policies-storage.lmdb-lock │ │ ├─ setup.json │ │ ├─ stderr.log │ │ ├─ stdout.log │ │ └─ version.log │ ├─ node2 │ └─ ... ├─ projects │ └─ default.json ├─ trust_contexts │ └─ default.json └─ vaults ├─ vault1.json ├─ vault2.json ├─ ... └─ data ├─ vault1.lmdb ├─ vault1.lmdb-lock ├─ vault2.lmdb ├─ vault2.lmdb-lock └─ ...

credentials

Each file stored under the credentials directory contains the credential for a given identity. Those files are created with the ockam credential store command. They are then read during the creation of a secure channel to send the credentials to the other party

defaults

This directory contains symlinks to other files or directories in order to specify which node, identity, credential or vault must be considered as a default when running a command expecting those inputs

identities

This directory contains one file per identity and a data directory. An identity file is created with the ockam identity create command or created by default for some commands (in that case the defaults/identity symlink points to that identity). The identity file contains:

• the identity identifier
• the enrollment status for that identity

The data directory contains a LMDB database with other information about identities: - the credential attributes that have been verified for this identity. Those attributes are generally used in ABAC rules that are specified on secure channels. For example when sending messages via a secure channel and using the Orchestrator the project attribute will be checked and the LMDB database accessed

• the list of key changes for each identity. These key changes are created (or updated) when an identity is created either by using the command line or by using the identity service. The key changes are accessed in order to get the latest public key associated to a given identity when checking its signature during the creation of a secure channel. They are also accessed to retrieve the key id associated to that key and then use a Vault to create a signature for an identity

Note: for each .lmdb file there is a corresponding lmdb-lock file which is used to control the exclusive access to the LMDB database even if several OS processes are trying to modify it. For example when several nodes are started using the same NodeManager.

nodes

This directory contains:

• symlinks to default values for the node: identity and vault
• a database for ABAC policies
• a setup file containing some configuration information for the node (is it an authority node?, what is the TCP listener address?,...). That file is created when a node is created and read again if the node is restarted
• log files: for system errors and system outputs. The stdout.log file is where almost all the node logs are written
• a version number for the configuration

projects

This directory contains a list of files, one per project that was created, either the default project or via the ockam project create command. A project file contains:

• the project identifier and the space it belongs to
• the authority used by that project (identity, route)
• the configuration for the project plugins

trust_context

This directory contains a list of files, one per trust context. A trust context can created with the ockam trust_context create command. It can then be referred to during the creation of a secure channel as a way to specify which authority can attest to the validity of which attributes

vaults

This directory contains one file per vault that is either created by default or with the ockam vault create command. That file contains the configuration for the vault, which for now consists only in declaring if the vault is backed by an AWS KMS or not.

The rest of the vault data is stored in an LMDB database under the data directory with one .lmdb file per vault. A vault contains secrets which are generally used during the creation of secure channels to sign or encrypt data involved in the handshake.

Usage

Add this to your Cargo.toml:

[dependencies] ockam_api = "0.37.0"

License

This code is licensed under the terms of the Apache License 2.0.