NIP-17: Private Direct Messages - A Complete Guide

Learn about NIP-17, the secure replacement for NIP-04, and how to migrate your private messaging in Nostr

NIP-17 represents a significant security upgrade to how private messages work in Nostr. This guide explains why you should care about this protocol improvement, how to migrate from the old NIP-04 standard, and practical steps to secure your communications.

What is NIP-17?

NIP-17 is a Nostr protocol specification that defines Private Direct Messages using a dual-layer encryption system called “seal + gift wrap.” It was created to address fundamental security flaws in the previous NIP-04 encryption method.

Unlike NIP-04, which used a single layer of AES-256-CBC encryption, NIP-17 uses:

1. Seal - Inner encryption layer protecting the message content
2. Gift Wrap - Outer encryption layer that hides sender and recipient metadata

This dual-layer approach ensures that:

• Message content remains private
• Even relay operators cannot see who is talking to whom
• Message patterns and metadata are protected from network observers

Why NIP-17 Matters: The NIP-04 Security Problem

NIP-04 was Nostr’s original direct message protocol, but it has several critical security issues that make it unsuitable for truly private communication.

Comparison: NIP-04 vs NIP-17

The Core Problem with NIP-04

NIP-04 messages expose who is talking to whom on the blockchain. While the message body is encrypted, the envelope contains:

# NIP-04 Event Structure (simplified)
{
  "pubkey": "<sender_public_key>",      # Anyone can see who sent this
  "tags": [["p", "<recipient_pubkey>"]], # Anyone can see who received it
  "content": "<encrypted_content>"       # Only content is hidden
}

This means relay operators, network observers, and data scrapers can:

• Build social graphs showing who communicates with whom
• Track communication patterns and frequencies
• Infer relationships from message timing

NIP-17 solves this by wrapping the entire message structure in an additional encryption layer, making it impossible to see sender or recipient information without the decryption key.

How NIP-17 Works: Seal + Gift Wrap

Understanding the technical implementation helps appreciate the security improvements.

The Gift Wrap Layer (Outer)

The gift wrap is the outer envelope that hides all metadata. It’s encrypted to a special “gift wrap key” derived from the recipient’s public key. This layer contains:

• A random public key (not linked to the real sender)
• The recipient’s public key
• A timestamp
• The sealed inner message

The Seal Layer (Inner)

Inside the gift wrap sits the seal, which contains the actual message. This layer:

• Is encrypted using a fresh ephemeral key pair
• Contains the sender’s real public key
• Includes the message content
• Has its own timestamp for replay protection

Visual Representation:
┌─────────────────────────────────────┐
│ Gift Wrap (Outer Layer)             │
│ ┌─────────────────────────────────┐ │
│ │ Seal (Inner Layer)              │ │
│ │ ┌─────────────────────────────┐ │ │
│ │ │ Actual Message Content      │ │ │
│ │ │ Sender: real_pubkey         │ │ │
│ │ │ Timestamp: 1234567890       │ │ │
│ │ └─────────────────────────────┘ │ │
│ │ Encrypted with ephemeral key    │ │
│ └─────────────────────────────────┘ │
│ Random pubkey, recipient hint         │
└─────────────────────────────────────┘

Key Benefits

1. Metadata Privacy: No one except the recipient can determine who sent the message or who it was sent to
2. Unlinkability: Multiple messages between the same parties appear as unrelated events to observers
3. Better Forward Secrecy: Each message uses unique ephemeral keys

Migration Guide: Switching from NIP-04 to NIP-17

Migrating to NIP-17 is straightforward with modern Nostr clients. Here’s how to make the switch.

Step 1: Check Your Client Support

Before migrating, verify your client supports NIP-17:

Step 2: Enable NIP-17 in Your Client

Damus (iOS/macOS)

1. Open Settings → Privacy & Security
2. Scroll to “Message Encryption”
3. Toggle “Use NIP-17 for new messages” to ON
4. Your new DMs will use NIP-17 automatically

Note: Older NIP-04 messages remain readable but new messages use NIP-17.

Amethyst (Android)

1. Go to Settings → Messages
2. Enable “Use NIP-17 for DMs”
3. Restart the app for full effect

Primal (iOS/Android/Web)

1. Navigate to Settings → Privacy
2. Under “Direct Messages,” select “NIP-17 (Recommended)”
3. Changes apply immediately to new conversations

Step 3: Communicate with Your Contacts

NIP-17 only works if both parties have NIP-17 support. Send a note to frequent contacts:

nostr:note1... # Migration message template

"Hey! I'm upgrading to NIP-17 for better privacy in our DMs.
Please update your Nostr client if you haven't already.
Our future messages will be more secure!"

Step 4: Verify Migration Success

To confirm NIP-17 is working:

1. Send a test message to yourself or a friend
2. Check the event kind (should be 1059 for gift wraps)
3. Look for the kind: 1059 in message details
4. The p tag should point to a random ephemeral key, not your friend’s real key

// Example NIP-17 event (simplified)
{
  "kind": 1059, // Gift wrap event
  "pubkey": "<random_ephemeral_key>", // Not the real sender!
  "tags": [["p", "<recipient_pubkey>"]],
  "content": "<encrypted_seal_content>"
}

Client-Specific Setup Guides

Damus

Damus made NIP-17 the default for new direct messages in recent versions. If you’re on an older version:

1. Update to the latest Damus from App Store
2. NIP-17 is automatically enabled for new conversations
3. Check message details (tap and hold) to see “NIP-17” badge

Pro tip: Damus shows a lock icon with “NIP-17” text on secure messages.

Amethyst

Amethyst supports NIP-17 but may require explicit enablement:

1. Settings → Advanced → Protocol Settings
2. Enable “NIP-17 gift wrap for DMs”
3. The client will automatically negotiate NIP-17 with supported contacts

Note: Amethyst gracefully falls back to NIP-04 if the recipient doesn’t support NIP-17.

Primal

Primal has excellent NIP-17 support:

1. Settings → Security & Privacy
2. Under “Messaging Protocol” select “NIP-17 (Private)”
3. Optional: Enable “Auto-upgrade NIP-04 conversations” to convert existing chats

Security Best Practices

Maximize your privacy when using NIP-17:

1. Verify Client Support Before Sensitive Communication

Always confirm your contact uses a NIP-17-capable client before sharing sensitive information. Sending NIP-17 to a NIP-04-only client will result in unreadable messages.

2. Don’t Mix Protocols in Same Thread

Avoid confusion by using one protocol per conversation. If you start with NIP-04, finish with NIP-04, or clearly indicate when switching.

3. Use Fresh Keys for High-Security Conversations

For maximum security:

• Create a dedicated keypair for sensitive communication
• Share the public key through a secure out-of-band channel
• Rotate keys periodically

4. Be Aware of Metadata in Other Event Types

NIP-17 only protects direct messages. Other event types (notes, reactions, follows) still expose social graph data. Use multiple identities for compartmentalization.

5. Choose Privacy-Focused Relays

Even with NIP-17, your traffic patterns are visible to relays. Use:

• Tor or VPN for additional network-level privacy
• Relays that don’t log or retain message metadata
• Multiple relays to distribute your traffic

6. Understand Limitations

NIP-17 provides excellent privacy but is not perfect:

• Relays can still see IP addresses (use VPN/Tor)
• Timing analysis can reveal communication patterns
• Compromised clients can leak information
• Recipient always sees sender identity

Troubleshooting Common Issues

”Messages show as unreadable or gibberish”

Cause: Recipient doesn’t support NIP-17 Solution: Ask recipient to update their client, or temporarily switch back to NIP-04

”Can’t see if someone read my NIP-17 message”

Cause: Read receipts not standardized for NIP-17 yet Solution: This is expected behavior. NIP-17 prioritizes privacy over delivery confirmation.

”Messages appear out of order”

Cause: Clock skew between devices Solution: Ensure your device time is synchronized (enable automatic time sync)

“Relay rejects NIP-17 events”

Cause: Old relay software Solution:

1. Check relay’s supported NIPs
2. Add modern relays that support NIP-17
3. Report to relay operator

”Client shows both NIP-04 and NIP-17 options”

Expected behavior: Many clients support both during transition period. Always choose NIP-17 when available.

The Future of Private Messaging in Nostr

NIP-17 is the current gold standard for Nostr private messaging, but development continues:

• NIP-44: An improved encryption scheme that may supersede NIP-17
• Group encryption: Private group messaging protocols are being developed
• Payment integration: Private messages with Lightning payments

Stay updated by following:

• nostr:npub1… # Nostr protocol development
• nostr:npub1… # Security best practices

Conclusion

NIP-17 represents a major step forward for privacy in Nostr. By addressing the metadata leakage problems of NIP-04, it enables truly private direct messaging that protects both content and communication patterns.

The migration process is straightforward: update your client, verify your contacts support NIP-17, and enjoy enhanced privacy. With widespread client support already available, there’s no reason to continue using the deprecated NIP-04 protocol.

Action items:

1. ✅ Update your Nostr client to the latest version
2. ✅ Enable NIP-17 in settings
3. ✅ Verify with contacts that they support NIP-17
4. ✅ Start using NIP-17 for all new private conversations

Remember: Privacy is a practice, not a product. NIP-17 gives you the tools—use them wisely.

Test Your NIP-17 Knowledge

Ready to check your understanding of secure messaging?

Last updated: February 11, 2025

Have questions? Join the discussion on Nostr or open an issue on this documentation repository.