Skip to content

Latest commit

 

History

History
90 lines (59 loc) · 3.35 KB

security.md

File metadata and controls

90 lines (59 loc) · 3.35 KB

Tun Mesh Security Model

This app has the following security design goals:

  • Be secure by default.
  • Do not require onerous or difficult to implement settings.
  • Do not support insecure configurations.

General Architecture

The Tun Mesh application is deployed as a single process, for ease of deployment. This application forks subprocesses at logical breakpoints, but is otherwise a monolith.

The application provides a listening API on the network. This API:

  • Serves incoming health check traffic from the orchestration platform
  • Serves monitoring requests with Prometheus support is enabled
  • Provides general monitoring and information APIs
  • Provides endpoints for the main interaction between nodes in the cluster.

Nodes bootstrap into the cluster on startup, and then maintain the cluster via registrations containing node listening addresses. Nodes attempt to maintain communications with all other nodes in the mesh.

Tunneled traffic is currently sent over the API.

API Privacy

A TLS certificate for the API is required. This TLS provides privacy for all API traffic, including all traffic sent over the mesh.

As the API is multi-purpose, serving both inter-cluster communications and external health and monitoring endpoints, mutual TLS is not supported.

TLS/SSL versions below TLS 1.2 are not supported.

API Security

Health and Monitoring Endpoints

General health, monitoring, and informational endpoints are unsecured by design. These endpoints do not expose any sensitive information. These endpoints are intended to be access by clients where adding authentication is likely onerous or impossible.

/tunmesh/ API Endpoints

Endpoints for use within the cluster are secured with JSON Web Tokens. All tokens are symmetric HS256 signed tokens.

The application supports two types of token:

Cluster Token

The cluster token is the master token within the cluster. This token is based on a shared secret set in the config, and is used to allow new nodes to join the cluster. Nodes within this app are expected to be dynamic, with the orchestration platform creating and removing nodes as needed with no interaction from administrators.

The shared secret is the root of trust within the cluster. A shared secret was chosen as:

  • It is easy to generate in orchestration tooling, to encourage use by default.
  • It is agnostic to the various orchestration platforms that could be used.
  • It doesn't require any special handling when instances are stopped and started.

This token is used when:

  • Registering new nodes into the cluster
  • Re-registering failed nodes back into the cluster to allow self-healing
  • Generating session auth

Session Token

The application generates a unique session token for each link within the mesh. The session tokens are based on a shared secret unique to a single direction between two nodes. Session shared secrets are regenerated automatically, by default once an hour.

Session tokens are used for:

  • Tunneled traffic
  • Re-registering into the cluster

When negotiating a new session secret the secret is sent encrypted over the API using a unique RSA public/private keypair generated by the receiving node on startup. The main API TLS encryption is not relied upon for integrity of the session tokens.

API request flows

See api_flows.md