> For the complete documentation index, see [llms.txt](https://docs.tessell.com/tessell/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tessell.com/tessell/faq/security-and-networking.md).

# Security and Networking

Common questions about how Tessell secures database connectivity and agent communication, and how network components such as NAT Gateways are used between the Data Plane and the Control Plane.

***

## Frequently Asked Questions

### Q: How are SSL certificates configured for databases?

**A:** As a DBaaS (Database as a Service) provider, Tessell prioritizes the security and privacy of customers' data. To ensure secure communication between client applications and the databases provisioned through the control plane, Tessell offers SSL (Secure Sockets Layer) connectivity options. Below is an overview of the SSL certificate management process.

**SSL certificate generation — root CA certificate**

* At the tenant level, Tessell generates a self-signed root CA (Certificate Authority) certificate. This root CA certificate serves as the highest level of trust within the SSL/TLS (Transport Layer Security) infrastructure.
* Each tenant receives a unique root CA certificate, ensuring isolation and security at the individual customer level.
* The root CA certificate has a predefined expiry time of **5 years**, providing long-term validity and stability for SSL connections.

**SSL certificate generation — CA certificates for DB services**

* For each managed database service provisioned through the control plane, Tessell generates a unique CA certificate signed by the corresponding tenant's root CA certificate.
* These CA certificates serve as intermediaries, allowing for the issuance of SSL certificates specific to each DB service.
* By generating individual CA certificates for each DB service, Tessell ensures granularity and security, enabling precise control over SSL connectivity.

**Implementation and benefits**

| Benefit                  | Details                                                                                                                                                                                                                |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Secure communication** | SSL certificates, issued by individual CA certificates, encrypt data transmitted between client applications and managed databases, protecting it from interception and unauthorized access.                           |
| **Authentication**       | The use of CA certificates enables mutual authentication between client applications and database services, ensuring the integrity of the communication channel.                                                       |
| **Isolation**            | Each tenant's SSL infrastructure is isolated, with unique root CA certificates generated per tenant. This ensures that certificates and private keys are not shared across tenants, enhancing security and compliance. |
| **Long-term validity**   | The root CA certificate's 5-year expiry time provides stability and continuity for SSL connections, minimizing the need for frequent certificate renewal and maintenance.                                              |
| **Customization**        | The SSL certificate management process is flexible, allowing for customization based on tenant requirements and security policies.                                                                                     |

By offering SSL connectivity options with individualized CA certificate management, Tessell upholds the highest standards of security and privacy for customers' data. This robust SSL infrastructure — self-signed root CA certificates and individually generated CA certificates for DB services — ensures encrypted communication and trustworthiness.

***

### Q: How do I set up cross-account KMS key usage for Tessell?

**A:** If you want Tessell to encrypt your database resources using a customer-managed KMS key from your own AWS account (bring-your-own-key, or BYOK), the key must grant cross-account access to Tessell's roles before it can be registered.

**Key policy** — Add the following statement to the KMS key's key policy, granting access to the Tessell roles in your account:

```json
{
  "Sid": "Allow Tessell to use this KMS key",
  "Effect": "Allow",
  "Principal": {
    "AWS": [
      "arn:aws:iam::<account-id>:role/AccountAccessRoleForTessell",
      "arn:aws:iam::<account-id>:role/TessellDbVmMgmtRole"
    ]
  },
  "Action": [
    "kms:Encrypt",
    "kms:Decrypt",
    "kms:ReEncrypt*",
    "kms:GenerateDataKey*",
    "kms:DescribeKey*",
    "kms:CreateGrant"
  ],
  "Resource": "*"
}
```

**Tag** — Add the following tag to the KMS key so Tessell recognizes it as eligible for import:

| Tag key                   | Tag value |
| ------------------------- | --------- |
| `ALLOW_IMPORT_TO_TESSELL` | `true`    |

> **Multi-Region Keys:** Each replica key has its own, separate key policy. If you're registering a multi-region key, the primary key instance must be registered first — the above key policy and tag must then be applied to every replica key you want Tessell to use. Once permissions are granted, Tessell registers replica key instances on demand.

Once the key policy and tag are in place, register the key from the **Security** app's **Encryption Keys** tab — either by selecting it from your registered AWS account, or by providing its Key ARN directly if the account isn't registered with Tessell. For the full step-by-step registration flow, see [Register an encryption key](/tessell/app-families/governance/security-doc.md#register-an-encryption-key).

***

### Q: What authentication and authorization mechanism does the Tessell agent use when sending data over NATS?

**A:** Tessell's NATS deployment uses **NKeys authentication**, a highly secure public-key signature system based on [Ed25519](https://ed25519.cr.yp.to/).

With NKeys, the server can verify identities without ever storing or seeing private keys. The authentication system requires a connecting client to provide its public key and digitally sign a challenge with its private key. The server generates a random challenge with every connection request, making it immune to playback attacks. The generated signature is validated against the provided public key, thus proving the client's identity. If the public key is known to the server, authentication succeeds.

Tessell has also built an additional authorization layer on TGS RPCs to prevent impersonation and provide access controls.

Furthermore, the NATS communication over the wire (Agent → NATS Server) is not only secure with NKeys authentication and an additional authorization layer, but also protected with the industry-standard TLS encryption. This ensures that your data remains private and secure.

Below are the authentication and encryption mechanisms for the other endpoints:

| Endpoint                                     | Authentication                                                              | Encryption                                                    |
| -------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------- |
| **Metric collection (monitoring endpoints)** | OIDC (OpenID Connect) based AuthN (Client Credentials Grant) using KeyCloak | TLS (HTTPS)                                                   |
| **Genie connections**                        | OIDC (OpenID Connect) based AuthN (Client Credentials Grant) using KeyCloak | TLS for controls & SSH (over TCP tunnel) for support sessions |
| **Logging (agent logs)**                     | AWS IAM based AuthN                                                         | TLS (HTTPS)                                                   |

***

### Q: How are NAT Gateways used in Tessell?

**A:** Tessell creates Database Services — which are referred to as the **Data Plane** (an Oracle instance, for example) — in a VNet/Subnet. The Tessell agents that run on this DB Service need to communicate outbound with the **Control Plane** for various purposes (send out metrics information, get tasks to perform database lifecycle operations, and so on).

In order for the Tessell agents to talk to the services in the Control Plane, they need a path to go from the Data Plane on said VNet/Subnet to the Control Plane. In environments that only contain private addresses and do not have public IPs bound to the Data Plane, the **NAT Gateway** is the component that provides that path from the Data Plane to the Control Plane. It is the communication conduit from the Tessell agents on the running VM in the Data Plane to the Control Plane components that are hosted in the Tessell account.

From a security perspective, the NAT Gateway helps mask the IP addresses of the VMs that are initiating the network connection — these VMs are the DB Service VMs. This helps protect the internal IP structure of your VNet/Subnet, making it harder for potential attackers to identify and target specific resources within your network. The NAT Gateway facilitates outbound connections from the DB Service VM to the Tessell Control Plane, ensuring that no inbound connections from the internet are allowed. This significantly reduces the attack surface, as the DB Service VM is not exposed directly to the internet. In addition to the above, it provides centralized logging and auditing of all outbound traffic.

The above scenario describes a situation where Data Plane/Control Plane traffic is traversing the internet. Tessell can also provide a more secure method for this communication between the Data Plane and Control Plane, leveraging **Private Links and Private Endpoints**, thus eliminating the need for NAT Gateways altogether. This is because using Private Link/Endpoints provides direct connectivity between the Data Plane and Control Plane, removing the need for internet traversal.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.tessell.com/tessell/faq/security-and-networking.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.