> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ditto.live/llms.txt
> Use this file to discover all available pages before exploring further.

# Certificate-Based Security

> All communications are consistently protected by modern and robust encryption for all of Ditto's communication methods.

<Info>
  This section contains an advanced discussion of Ditto's underlying certificate, identity, and encryption implementation. Most readers can skip this section.  However, if you are deploying an enterprise on-premises deployment of Ditto, you may be required to reference the following material.
</Info>

Cryptographically-signed business rules ensure users can only sync data that they are permitted to access. The app developer is in complete control of the keys, certificates, and rules.

Ditto Server provisions a signed x509 certificate. This certificate may then be presented to other Ditto peers to mutually establish trust and create encrypted communications channels.

The following details information about the certificates used to encrypt the communication channels.

| **Capability**       | **Type**                                                              |
| -------------------- | --------------------------------------------------------------------- |
| Encryption           | TLS 1.3                                                               |
| Authentication       | EC key-pairs with signed certificates                                 |
| Trust infrastructure | X.509 with a developer-controlled certificate authority               |
| Access Rules         | Query patterns on Document \_id's describing read and or write access |

## Identities

An identity is a bundle of the device and app-specific information:

| &#xA;                | **Production**                                                              | **Development**                                     |   |
| -------------------- | --------------------------------------------------------------------------- | --------------------------------------------------- | - |
| Site ID              | Allocated by central authority                                              | Defaults to a random number; can be customized      |   |
| Database ID          | Set by central authority                                                    | For example, "5322afcd-5a70-43a3-bc2d-85d98ccf5ac0" |   |
| Access Rules         | Set by central authority                                                    | All devices may read/write all documents            |   |
| Private Key          | Either generated on device or distributed by central authority              | Hard-coded and shared by all devices                |   |
| Identity Certificate | Unique and signed by a central authority; contains this device's public key | Hard-coded and shared by all devices                |   |
| CA Certificate       | Shared by all users of the same app                                         | Hard-coded and shared by all devices                |   |

## Certificates

Ditto identities and public keys are distributed in the standard X.509 certificate format. They do not directly contain potentially sensitive data such as access rules, but these can be defined by the app's authentication webhook when configuring [server authentication](/sdk/latest/auth-and-authorization/cloud-authentication).

When you are ready to use production identities, feel free to contact us through the Ditto Portal and we will help you set up the right CA tooling for your use case - or provide specifications so you can build your own.

## Discovering peers

Devices need to have the same Database ID to discover other peers on the network, as well as matching certificates to connect over TLS 1.3. Peer-to-peer connections use mTLS (client certificates) with TLS 1.3. Connections to Ditto Server use a TLS-secured WebSocket connection, with authentication by JWT. Once the certificates match, then the embedded authorization information inside each certificate is used to authorize any incoming requests by that peer. This ensures that those access control rules are enforced.

## Syncing with Ditto Server

<Info>
  This covers internal details of the Ditto Server implementation. Ditto's authentication module handles it for you under the hood when using server authentication.
</Info>

Server authentication is used when a Ditto application is hosted on Ditto Server, which runs an HTTPS identity service that handles login requests. A device must log in with credentials before it can communicate with any peers; a successful login populates it with the authentication material that identifies the user and defines their level of access, after which the transports that depend on it start automatically.

For the step-by-step login flow — the peer key challenge, credential issuance, and on-disk persistence — see [Detailed Online Certificate Flow](/key-concepts/authentication-and-authorization#detailed-online-certificate-flow).

## Rationale

**Why does X.509 return both a key and a certificate instead of locally generating a key and sending a CSR?**

It would be possible to use a standard CSR flow. It was chosen to issue keys directly for a few reasons.

* There is no security benefit as our certificate request is in a secured tunnel, and the identity service is presumed to be completely trustworthy.
* Validating and signing CSRs is more complex than simply creating one with the correct format and fields.
* This is a convenient workflow if using Hashicorp Vault or similar to manage your PKI and issue certificates on demand.