> For the complete documentation index, see [llms.txt](https://docs.envector.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.envector.io/1.4.x/sdk-user-guide/client-security-best-practices.md).

# Client Security Best Practices

> **Audience**: Backend / device developers integrating their own systems with the enVector SDK **Scope**: Common to every client-side integration scenario — face recognition, and beyond

***

## Architectural Paradigm: The Server Only Sees Ciphertext

The biggest difference between enVector and conventional DB-encryption solutions lies in the data flow. Every "data at rest" payload sent to the enVector server **must already be encrypted on the client side (Client-Side Encryption)** before transmission.

1. **Role of the Server (enVector Engine)**
   * Stores encrypted vector data
   * Performs de-identified distance computation directly on ciphertexts (Homomorphic Computation)
   * **The server does not hold any decryption key (Secret Key) whatsoever.**
2. **Role of the Client (Customer Terminal / Backend)**
   * Extracts feature vectors (e.g., a 512-dimensional float array) from raw inputs (images, text, sensor data, etc.)
   * Uses the enVector SDK to encrypt (Seal) the extracted vectors
   * Transmits the encrypted data to the enVector server

> ⚠️ Because of this design, even if the enVector engine server is breached, neither plaintext data nor decryption keys exist on the server to be leaked.

**However**, if the **customer-side client (terminals, WAS, backend servers)** that directly handles plaintext data and keys is compromised, the entire security model collapses. The remainder of this document outlines the security-architecture principles that client-side developers must therefore observe when building enVector integrations.

***

## 1. Physically Isolate the Secret Key (Decryption Key)

* The Secret Key must **never** be uploaded to the server.
* Store it only in a **secure isolated environment** (Hardware-Backed Keystore, HSM, TEE, etc.) on the air-gapped internal WAS or client terminal where decryption operations (such as decrypting `search()` results) actually take place.

***

## 2. Strict Control of Key-Store Access Credentials (IAM / API Tokens)

* If a non-decryption-capable EncKey (Public Key) is leaked on its own, the attacker is limited to encrypting forged data and polluting the database.
* However, a far more critical risk is the leakage of credentials that grant access to key stores or secret-management systems (e.g., IAM roles, service-account tokens, or API keys used to access KMS).
* Compromise of such credentials may allow attackers to retrieve, unwrap, or misuse sensitive key material, effectively bypassing the intended key-isolation guarantees.
* Therefore, in high-security environments: Never persist key-store access credentials (IAM tokens, service-account keys, etc.) in plaintext memory or local storage. Prefer short-lived, dynamically issued credentials from systems such as HashiCorp Vault, AWS KMS, or Google Cloud Platform Secret Manager. Enforce strict least-privilege policies and regularly rotate all credentials.
* Rationale: While leakage of a public encryption key mainly enables data pollution, leakage of key-store access credentials can lead to direct exposure or misuse of protected keys, which fundamentally breaks the security model.

***

## 3. Immediate Zeroization of Plaintext Memory — Responsibility Boundary

* The `pyenvector` SDK internally zeroizes encryption-key memory automatically once it is no longer needed.
* **However, the SDK cannot control raw plaintext vector arrays loaded into memory by the customer's application framework** — for example, the `query_vector` float array extracted from a camera in a face-recognition scenario, or the input embeddings in a RAG pipeline.
* Immediately after a `search()` or `insert()` call returns, the client developer **must** explicitly wipe any remaining plaintext data from application memory using platform-provided zeroization primitives (`explicit_bzero`, `Arrays.fill`, etc.).

***

## 4. No Plaintext Logging

* When emitting authentication accept/deny, search-result, or audit logs, rigorously censor anything that could leak sensitive data — including raw extracted float arrays (`Float Array`), threshold/debug information, and score distributions. None of these may end up in plaintext logs.
* Enforce in your build/deployment pipeline that debug log levels are disabled in production environments.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.envector.io/1.4.x/sdk-user-guide/client-security-best-practices.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.