> For the complete documentation index, see [llms.txt](https://vector-privacy.gitbook.io/vector-privacy/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/docs/security.md).

# Security

## Security Documentation

This document provides an overview of the security features, best practices, and considerations for the Vector SDK.

***

## Table of Contents

* [Overview](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/advanced/editor-2#overview)
* [Cryptography](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/advanced/editor-2#cryptography)
* [Data Protection](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/advanced/editor-2#data-protection)
* [Threat Model](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/advanced/editor-2#threat-model)
* [Best Practices](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/advanced/editor-2#best-practices)
* [Vulnerability Reporting](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/advanced/editor-2#vulnerability-reporting)
* [Dependencies](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/advanced/editor-2#dependencies)
* [Key Management Guidelines](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/advanced/editor-2#key-management-guidelines)
* [MLS Security Considerations](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/advanced/editor-2#mls-security-considerations)
* [Resources](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/advanced/editor-2#resources)

***

### Overview

Vector SDK is designed with security as a primary concern. It provides end-to-end encryption for all communications and implements industry-standard cryptographic protocols to protect user privacy.

***

### Cryptography

#### Encryption Algorithms

**AES-256-GCM**

* **Purpose**: Encrypting file attachments and sensitive data
* **Key Size**: 256-bit (32 bytes)
* **Nonce Size**: 128-bit (16 bytes)
* **Authentication**: Galois/Counter Mode (GCM) provides authenticated encryption
* **Implementation**: `aes-gcm` crate with `Aes256` cipher

**SHA-256**

* **Purpose**: Hashing files for integrity verification
* **Output**: 256-bit (32 byte) hash
* **Implementation**: `sha2` crate

#### Key Management

* **Key Generation**: Cryptographically secure random keys using `rand::thread_rng()`
* **Key Storage**: Keys are stored in memory and not persisted to disk
* **Key Rotation**: Applications should implement their own key rotation policies

#### Message Layer Security (MLS)

Vector SDK integrates with the [nostr-mls](https://github.com/nostr-protocol/nips/tree/master/nips) protocol for group messaging:

* **End-to-End Encryption**: All group messages are encrypted
* **Forward Secrecy**: Ephemeral keys provide forward secrecy
* **Key Package Management**: Automatic publishing of key packages to relays
* **Group Membership**: Secure group creation, joining, and member management

***

### Data Protection

#### Private Messaging

* **Protocol**: NIP-59 (Gift Wrap) for direct messages
* **Encryption**: Each message is encrypted with a unique key
* **Recipient Verification**: Messages are wrapped for specific recipients

#### File Attachments

1. **Encryption**: Files are encrypted with AES-256-GCM before upload
2. **Upload**: Encrypted files are uploaded to Blossom media servers
3. **Metadata**: Encryption parameters (key, nonce) are sent separately
4. **Integrity**: SHA-256 hash of original file is included in metadata

#### Typing Indicators

* **Protocol**: NIP-40 (Application-Specific Data)
* **Expiration**: Typing indicators expire after 30 seconds
* **Encryption**: Typing indicators are encrypted like regular messages

#### Reactions

* **Protocol**: NIP-25 (Reactions)
* **Encryption**: Reactions are encrypted and wrapped for recipients
* **Content**: Only emoji content is sent (no additional metadata)

***

### Threat Model

#### Threats Addressed

| Threat            | Mitigation                                          |
| ----------------- | --------------------------------------------------- |
| Eavesdropping     | End-to-end encryption with AES-256-GCM              |
| Message Tampering | GCM authentication tags verify integrity            |
| Impersonation     | Nostr public keys authenticate senders              |
| Man-in-the-Middle | TLS for relay connections, encrypted content        |
| Replay Attacks    | Timestamps and sequence numbers prevent replay      |
| File Interception | Files encrypted before upload, keys sent separately |

#### Threats Not Addressed

* **Malicious Relays**: Relays can withhold or delay messages (standard Nostr limitation)
* **Metadata Leakage**: Profile information (name, picture) is public
* **Key Compromise**: If private keys are compromised, past messages can be decrypted
* **Client-Side Vulnerabilities**: Applications using the SDK must implement secure practices

***

### Best Practices

#### For Application Developers

1. **Key Management**:
   * Store private keys securely (use platform keychains)
   * Never hardcode or commit private keys to version control
   * Implement proper key backup and recovery
2. **Error Handling**:
   * Never expose cryptographic errors to end users
   * Log errors securely (no sensitive data in logs)
   * Handle decryption failures gracefully
3. **Network Security**:
   * Use secure relay connections (wss\://)
   * Validate relay URLs before connecting
   * Implement connection timeouts
4. **Data Handling**:
   * Clear sensitive data from memory when no longer needed
   * Validate all file inputs before processing
   * Limit file sizes to prevent DoS attacks
5. **Logging**:
   * Avoid logging encrypted content
   * Mask sensitive information in logs
   * Use appropriate log levels

#### For End Users

1. **Key Security**:
   * Protect your private keys
   * Use strong passphrases for key encryption
   * Backup your keys securely
2. **Relay Selection**:
   * Use trusted relays
   * Diversify relay connections for redundancy
3. **File Sharing**:
   * Verify file sources before opening
   * Check file hashes when available
   * Be cautious with executable files

***

### Vulnerability Reporting

If you discover a security vulnerability in Vector SDK, please follow these steps:

1. **Do not** open a public issue on GitHub
2. **Do not** discuss the vulnerability in public channels
3. **Email** the security team at: `security@vectorapp.io`
4. **Include** as much detail as possible:
   * Steps to reproduce
   * Impact assessment
   * Potential mitigations
   * Your contact information

The security team will:

* Acknowledge receipt within 48 hours
* Provide updates on the investigation
* Work on a fix and coordinate disclosure
* Credit responsible disclosers in release notes

***

### Dependencies

Vector SDK uses the following security-critical dependencies:

| Dependency  | Purpose                       | Version | Notes                       |
| ----------- | ----------------------------- | ------- | --------------------------- |
| `nostr_sdk` | Nostr protocol implementation | Latest  | Includes NIP-59 (Gift Wrap) |
| `aes-gcm`   | AES-256-GCM encryption        | Latest  | FIPS 197 compliant          |
| `sha2`      | SHA-256 hashing               | Latest  | FIPS 180-4 compliant        |
| `rand`      | Cryptographic RNG             | Latest  | Uses OS-provided CSPRNG     |
| `reqwest`   | HTTP client                   | Latest  | Used for file uploads       |
| `mdk`       | Message Layer Security        | Latest  | For group messaging         |

#### Dependency Security

* All dependencies are kept up-to-date
* Security advisories are monitored
* Vulnerable dependencies are patched promptly

***

### Key Management Guidelines

#### Private Key Storage

**Do:**

* Use platform-specific secure storage (Keychain on macOS, Keystore on Android, etc.)
* Encrypt keys at rest with strong passphrases
* Implement proper access controls
* Rotate keys periodically

**Don't:**

* Hardcode keys in source code
* Store keys in plaintext files
* Commit keys to version control
* Share keys between applications

#### Key Rotation

While Vector SDK doesn't enforce key rotation, applications should implement their own policies:

1. **Regular Rotation**: Rotate keys every 6-12 months
2. **Event-Based Rotation**: Rotate after security incidents
3. **Compromise Detection**: Monitor for unusual activity
4. **Graceful Transition**: Support multiple active keys during rotation

***

### MLS Security Considerations

#### Group Security

* **Group IDs**: Unique identifiers for each group, stored securely
* **Welcome Events**: Verify welcome events before accepting
* **Member Management**: Only authorized members can add/remove participants
* **Message Processing**: All messages are validated before decryption

#### Storage Security

* **SQLite Database**: MLS group state is stored in `mls/vector-mls.db`
* **Database Location**: The database is created in the `mls/` directory relative to your application's data directory. The exact path depends on your operating system:
  * Linux: `~/.local/share/your_app/mls/vector-mls.db`
  * macOS: `~/Library/Application Support/your_app/mls/vector-mls.db`
  * Windows: `%APPDATA%\your_app\mls\vector-mls.db`
* **Encryption at Rest**: Consider encrypting the SQLite database at rest using platform-specific encryption APIs:
  * macOS: Use Keychain or FileVault
  * iOS: Use Keychain or Data Protection
  * Android: Use Android Keystore System
  * Linux/Windows: Use platform-specific encryption tools
* **Backup**: Regularly backup the `mls/vector-mls.db` file for recovery. The database contains:
  * Group membership information
  * Cryptographic keys and key packages
  * Message history and state
  * Without this backup, you may lose access to group conversations
* **Cleanup**: Remove old group data when no longer needed to reduce attack surface
* **Database Permissions**: Ensure the database file has appropriate file system permissions to prevent unauthorized access

#### Security Checklist for Applications

When building applications with Vector SDK, consider this checklist:

* [ ]  Private keys are stored securely
* [ ]  Sensitive data is not logged
* [ ]  Network connections use TLS
* [ ]  File uploads have size limits
* [ ]  Error messages don't expose system details
* [ ]  Cryptographic operations are properly handled
* [ ]  User inputs are validated
* [ ]  Session management is secure
* [ ]  Dependencies are kept updated
* [ ]  Security headers are set (for web apps)
* [ ]  MLS database is backed up regularly
* [ ]  MLS database is encrypted at rest (recommended)
* [ ]  Key rotation policy is documented
* [ ]  Database file permissions are properly configured
* [ ]  Database backup location is secure

***

### Resources

* [NIP-59: Gift Wrap](https://github.com/nostr-protocol/nips/blob/master/59.md)
* [NIP-40: Application-Specific Data](https://github.com/nostr-protocol/nips/blob/master/40.md)
* [NIP-25: Reactions](https://github.com/nostr-protocol/nips/blob/master/25.md)
* [AES-GCM Specification](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38D.pdf)
* [Rust Crypto](https://github.com/RustCrypto)
* [MLS Protocol](https://messaginglayersecurity.rocks/)


---

# 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:

```
GET https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/docs/security.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.