> 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 Features & Resources

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

{% hint style="info" %}
This page covers security at the protocol and SDK level. For account-level security inside the Vector app itself (PINs, passwords, local encryption), see the [Vector Messenger](https://vector-privacy.gitbook.io/vector-privacy/vector-messenger/) documentation.
{% endhint %}

## Table of Contents

* [Overview](#overview)
* [Cryptography](#cryptography)
* [Data Protection](#data-protection)
* [Threat Model](#threat-model)
* [Best Practices](#best-practices)
* [Vulnerability Reporting](#vulnerability-reporting)
* [Dependencies](#dependencies)
* [Key Management Guidelines](#key-management-guidelines)
* [Resources](#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

**SHA-256**

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

#### Key Management

* **Key Generation:** Cryptographically secure random keys
* **Key Storage:** A bot's identity key is persisted to `identity.nsec` in its data directory only when no key is explicitly supplied; an explicitly supplied `.nsec(...)` / `.mnemonic(...)` is held in memory for the life of the process
* **Key Rotation:** Applications should implement their own key rotation policies

{% hint style="warning" %}
The `identity.nsec` file written for a keyless bot is the bot's entire identity. Treat its data directory with the same care you would treat any private key file, restrict file permissions, and never commit it to version control.
{% endhint %}

***

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

* **Encryption:** Files are encrypted with AES-256-GCM before upload
* **Upload:** Encrypted files are uploaded to Blossom media servers
* **Metadata:** Encryption parameters (key, nonce) are sent separately
* **Integrity:** A SHA-256 hash of the 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 Not Addressed

{% hint style="warning" %}
**The following are known, accepted limitations rather than bugs:**

* **Malicious Relays:** Relays can withhold or delay messages (a standard Nostr-level limitation)
* **Metadata Leakage:** Profile information (name, picture) is public by nature of the protocol
* **Key Compromise:** If a private key is compromised, past messages encrypted to it can potentially be decrypted
* **Client-Side Vulnerabilities:** Applications built with the SDK must implement their own secure practices, the SDK secures the protocol layer, not your application logic 
  {% endhint %}

***

### Best Practices

#### For Application Developers

{% tabs %}
{% tab title="Key Management" %}

* Store private keys securely (use platform keychains where possible)
* Never hardcode or commit private keys to version control
* Implement proper key backup and recovery 
  {% endtab %}

{% tab title="Error Handling" %}

* Never expose cryptographic errors to end users
* Log errors securely, no sensitive data in logs
* Handle decryption failures gracefully 
  {% endtab %}

{% tab title="Network Security" %}

* Use secure relay connections (`wss://`)
* Validate relay URLs before connecting
* Implement connection timeouts {% endtab %}
  {% endtab %}

{% tab title="Data Handling" %}

* Clear sensitive data from memory when no longer needed
* Validate all file inputs before processing
* Limit file sizes to prevent denial-of-service attacks
  {% endtab %}

{% tab title="Logging" %}

* Avoid logging encrypted content
* Mask sensitive information in logs
* Use appropriate log levels
  {% endtab %}
  {% endtabs %}

#### For End Users

* **Key Security:** Protect your private keys; use strong passphrases for key encryption; back up your keys securely
* **Relay Selection:** Use trusted relays; diversify relay connections for redundancy
* **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:

{% hint style="danger" %}

* **Do not** open a public issue on GitHub
* **Do not** discuss the vulnerability in public channels
* Email the security team directly at `security@vectorapp.io` 
  {% endhint %}

Include as much detail as possible:

* Steps to reproduce
* Impact assessment
* Potential mitigations
* Your contact information

The security team will:

1. Acknowledge issue within 48 hours
2. Provide updates on the investigation
3. Work on a fix and coordinate disclosure
4. Credit responsible disclosers in release notes, with their permission

***

### Dependencies

Vector SDK keeps its own dependency tree intentionally small; see [Dependencies](/vector-privacy/vector-sdk/basics/dependencies.md) for the full list. Lower-level cryptographic and networking primitives live inside `vector-core` rather than being direct dependencies of the SDK itself.

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

***

### Key Management Guidelines

#### Private Key Storage

{% tabs %}
{% tab title="Do" %}

* Use platform-specific secure storage (Keychain on macOS, Keystore on Android, etc.) where your application architecture allows for it
* Encrypt keys at rest with strong passphrases
* Implement proper access controls
* Rotate keys periodically
  {% endtab %}

{% tab title="Don't" %}

* Hardcode keys in source code
* Store keys in plaintext files outside of the SDK's own managed identity storage
* Commit keys to version control
* Share keys between applications
  {% endtab %}
  {% endtabs %}

#### Key Rotation

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

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

***

### 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 (`wss://`)
* \[ ] File uploads have size limits
* \[ ] Error messages don't expose system details
* \[ ] Cryptographic operations are properly handled
* \[ ] User inputs are validated
* \[ ] Dependencies are kept updated
* \[ ] Key rotation policy is documented, if applicable to your application

***

### 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://csrc.nist.gov/publications/detail/sp/800-38d/final)
* [RustCrypto](https://github.com/RustCrypto)