Security
Most applications need a way to control which users can write or read certain data.
For example, you might build an application where senior staff members can read and write documents in the "menuItems" collection while junior staff members can only read.
Ditto's security is controlled by identities. Each Ditto instance must identify itself to other peers in order to syncronize with them.
Ditto implements network protections that secure all data while in transit and at rest, including inter- and intra-service, client-server, direct peer-to-peer transports communications.
Encrypted at the transport layer using version 1.3 of the Transport Layer Protocol (TLS), clients and servers are mutually authenticated prior to transmission of API and peer-to-peer access credentials. The use of mutually authenticated TLS (mTLS) mitigates potential risks posed by outside attackers attempting to masquerade as a valid API endpoint or peer in the mesh network to steal information.
Additionally, Ditto workloads and services are tightly controlled in a containerized Kubernetes environment.
Following is an overview of the authentication and authorization controls, network protections, and access credentials Ditto uses to ensure access and data remain secure and resilient:
Material | Issuer | Usage Description |
|---|---|---|
JSON web token (JWT) | Third-party identity provider | Used by the WebsocketClient and is accepted by the WebsocketServer, the JWT credential determines access permissions and privileges. |
X.509 | Ditto | Used by all peer-to-peer transports, such as Bluetooth Low Energy (LE), as well as the TCP client and server transport. |
In-Band Certificate | Third-party identity provider | Used to secure multi-hop replication transports: LinkClientTransport and LinkServerTransport |
The AuthClient locally generates a peer key. The peer key is a P-256 private key generated and persisted on every client device running Ditto. This is the primary unique identifier for each peer; its Elliptic Curve Digital Signature Algorithm (ECDSA) signatures are used to prove authenticity: a signing key-pair. This is the primary identifier for a particular unique peer device or application, but it isn’t trustworthy.
In addition to using a peer key to verify client identity, the transports need to prove that a given device is authorized to join the mesh. Using central authority (CA), a cryptographic root of trust for everybody participating in the same Ditto application.
This trust comes in the form of signed access tokens or client certificates, depending on the transport type, which are managed by the AuthClient object and the on-disk cache.
When a Small Peer calls OnlineWithAuthentication, first a request for an access token specifying user access permissions and privileges in an encryption is sent to the third-party identity provider integrated with your app. Once generated, your identity provider returns the access token, which is typically in the format of a JSON web token (JWT), to the calling Small Peer.
Once retrieved, the Small Peer passes the access token to the Ditto authenticator service, which then passes it to your identity provider’s authentication WebHook URL endpoint.
The Small Peer uses the authentication WebHook endpoint to validate and decrypt the access token and then issues the Small Peer certificate encoded with identity and access control permissions in a JSON payload to the Ditto database server, the Big Peer.
Each peer verifies certificates of other peers and accepts or rejects reads and writes based on the certificates encoded identity and access control permissions.You can issue each peer certificate manually or using OnlineWithAuthentication.
When the access token is soon to expire, if implemented, the authenticationExpiringSoon asynchronously invokes to refresh the access token before it expires.
In offline scenarios, a Small Peer that invokes the OnlineWithAuthentication API must connect to the internet at least once in order to authenticate and retrieve their client certificate before it can sync with other peers offline.
The following diagram illustrates the end-to-end authentication flow for client apps (Small Peers) invoking OnlineWithAuthentication:
