Nano cryptography¶
When logging in using a Nano client, the same login procedure is followed that a user login does. Once logged in, the client connects to a server endpoint that routes remote requests to be executed. Depending on the configurations and the incoming requests, the Nano queries the necessary room keys, blockchain and the keyring of peer users for precessing.
Remote request cryptography¶
All remote requests that arrive to a Nano are always encrypted and go through the following validation process:
Request metadata provided by the server is validated. This includes the id of the requesting account, the id of the room targeted by the request if any, and various caching and data transfer control information.
If a room id is provided, but is not served by the Nano, the processing will exit prematurely. This spares the work of decrypting the payload. There is no useful information an adversary may gain from polling the served rooms by this. The server already knows which rooms the Nano serves. Users other than the owner have no ability to send requests to the Nano directly. Since they will request message routing from the server by the room-id, there is no way for them to influence this metadata field, as it is validated and filled in by the server. If they provide a manipulated payload with correctly encrypted but maliciously different embedded room-id, the inconsistency will stop the processing after decrypting the payload and will not reveal served room ids either.
The decrypting cipher is selected and set up for the account-id provided by the server. There are three distinct encryption configs depending on the requesting account’s identity:
The owner always encrypts their requests to the Nano with an exclusive encryption using a key derived from their master-key.
Anonymous requests are always encrypted using a key derived from the room’s pinned key and an ephemeral 25519 keypair. The public key of the anonymous account’s keypair is submitted with the request.
For any other registered account will need to derive a key from the room’s pinned key and their 25519 keypair.
During the decryption setup, the requesting identity is checked against relevant policies:
Anonymous requests will be denied here if the Nano’s local policy forbids their execution. (deny_anonymous)
Registered accounts (except the owner) will need to pass the identity assurance check of the Nano. This means their identity must be explicitly trusted by the owner or their identity must match the one that was saved prior, to the local Trust-On-First-Use database of the Nano.
When the decryption of the payload succeeds the account_id provided by the server is guaranteed to be authentic from this point onwards, because the associated keys successfully decrypted the payload from an authenticated ciphertext.
The server supplied room-id (if any) is checked to be consistent with the one specified in the decrypted payload.
Local configs and the group config blockchain will be evaluated for the requesting identity selected by the room-id. If the requesting account has no access to the room, or it is denied by a local policy e.g., deny_anonymous, the request processing will exit.
The request handler key is checked if it is a “mutation”. Mutating handlers require the request to supply a session token that prevents malicious or erroneous double submission of requests from executing.
At the point a request is deemed eligible for execution it is guaranteed that:
The metadata provided by the server and the decrypted request payload is consistent and authentic.
The server cannot send a request to a Nano other than the designed, because either the decryption would fail or the inconsistency would be detected.
The request is guaranteed to be made with the knowledge of the required keys.
The requesting account does not only have the necessary keys, but they have sufficient access granted in the blockchain and the local policy.
The request is protected against replay-attack if necessary.
Response cryptography and data caching¶
Responses contain a cryptographic hash that provides a proof to the requesting client that the response received through the servers was made specifically for their request. This prevents malicious servers from performing replay attacks using the Nano responses.
While all requests are encrypted on a peer-to-peer basis between accounts, the responses from a Nano can be encrypted differently. Responses that would benefit from being cached are encrypted by the Nano using deterministically derived keys. The secret values generated by the Nano that are used for deriving the content keys never leave the machine. The servers cache the deterministically encrypted response chunks, allowing multiple users to access the same content without encumbering the network uplink of the Nano.
The server cannot give the cached content to users without explicit authorization of the Nano. When a client requests something from the Nano, the payload is encrypted and the server cannot know if the response would be cached or if it already has the response cached. The Nano must be asked to resolve the request. If the request is authorized the Nano tells the server the cache-key by which the response chunks can be found. Even if the server would guess the response chunks or give all the cached data to any user for a request, they could not decrypt it. The content encryption key is only known by the Nano and it is only shared to clients using peer-to-peer encryption that make authorized requests to that content specifically.
The cached contents are in authenticated ciphertexts, which on by themselves provide data integrity. However these chunks also include checksums of the content that are digitally signed by the Nano. This prevents a malicious server colluding with a malicious, but authorized account to create tampered contents. Basically all cached content is encrypted with symmetric cryptography, meaning if the server would get hold of the unique key of a content under a specific cache-key, then it could manipulate it. This could happen if a malicious person got access to the room and the content, where a Nano would see them as authorized and share the key for the content with them. Using that key the colluding account could make the server able to tamper with the data chunks. The additional digital fingerprinting and signature of the owner made by the Nano makes this impossible, providing assurance that the cached data was not tampered with.
To break this down:
Each response carries a proof that it was specifically made for the client’s request, the server can’t replay previous Nano responses to clients.
Nano either responds to requests in the same peer-to-peer encryption that the request was made, or using an encryption it has complete control over. (latter is typically used for cache-able responses)
The source key material used for deriving deterministic keys for cache-able content never leaves the machine the Nano is running on.
Each cache-able content is derived unique keys by the Nano.
For a client request to be fulfilled from server cache, the client needs the decryption key of the cached content chunks and the server needs the cache-key of the corresponding responses. Both can only be provided by the Nano. Cached content can’t be served by the servers without the Nano explicitly authorizing the request.
The cached data transfer is guaranteed to be authentic even in the face of maliciously colluding authorized member accounts of the room and the server.