Skip to content

Key Management

R-VPN uses Ed25519 identity keys for authentication. This guide covers key generation and management.

Key Types

Key Type Purpose Storage
Identity Key Long-term identity Keep secure, backup
Public Key Shared with server Can be public
Prekey Bundle Initial handshake Server-side

Generating Keys

Generate Identity Key

# Generate client identity key
rvpn keygen --output client_identity.key

# Generate with default output (identity.key)
rvpn keygen

This creates a new Ed25519 key pair. The file format:

R-VPN-IDENTITY-v1
<base64 encoded public key>
<base64 encoded private key>

Extract Public Key

# Extract public key from identity file
rvpn pubkey --key client_identity.key --output client_public.key

# Extract with default output (public.key)
rvpn pubkey --key client_identity.key

Generate Prekey Bundle

For server operators:

# Generate prekey bundle from server identity
rvpn prekey-bundle --identity server_identity.key --output bundle.json

Or using the server binary:

rvpn-server prekey-bundle --identity /etc/rvpn/server_identity.key --output bundle.json

The bundle contains: - identity_key - Server's Ed25519 identity public key (base64) - identity_x25519_key - Server's X25519 identity key for X3DH (base64) - signed_prekey - X25519 signed prekey for X3DH handshake (base64) - prekey_signature - Signature of the signed prekey (base64) - one_time_prekey - Optional one-time prekey for enhanced forward secrecy (base64)

Obtaining Server Prekey Bundle

To connect to a server, you need the server's prekey bundle. This can be obtained:

  1. From server administrator - They generate it using the prekey-bundle command
  2. Via secure channel - Share the JSON file through a secure means

The bundle file (prekey-bundle.json) contains all information needed for the X3DH handshake.

Key Security

Protecting Private Keys

Your identity key is the core of your security:

# Set restrictive permissions
chmod 600 client_identity.key

# Store in secure location
mkdir -p ~/.rvpn/keys/
mv client_identity.key ~/.rvpn/keys/

Backing Up Keys

Backup your identity key securely:

# Encrypt before backup with GPG
gpg --symmetric --cipher-algo AES256 client_identity.key

# Or use passphrase-protected encryption
gpg --symmetric --armor client_identity.key

# Store in secure location
# - Password manager
# - Encrypted USB drive
# - Secure cloud storage

To restore from backup:

# Decrypt the backup
gpg --decrypt client_identity.key.gpg > client_identity.key

# Set proper permissions
chmod 600 client_identity.key

Rotating Keys

Periodically rotate your identity keys for enhanced security:

# Generate new key
rvpn keygen --output new_client_identity.key

# Extract new public key
rvpn pubkey --key new_client_identity.key --output new_public.key

# Update server with new public key
# (Contact your VPN provider with the new public key)

# Backup old key
mv client_identity.key client_identity.key.old

# Switch to new key
mv new_client_identity.key client_identity.key

# Securely delete old key when confirmed working
shred -u client_identity.key.old

Server Key Setup

Server Identity

# Generate server identity
rvpn-server keygen

# Or using client binary
rvpn keygen --output server_identity.key

Extract Public Key

rvpn pubkey --key server_identity.key --output server_public.key

Distribute server_public.key to clients for server authentication.

Prekey Bundle

Generate the prekey bundle for client initialization:

rvpn-server prekey-bundle --identity server_identity.key --output prekey-bundle.json

The server also generates a private bundle (prekey-bundle.private.json) containing the signed prekey private key, which must be kept secure on the server.

The public bundle should be served via HTTPS for clients to retrieve during connection.

Key File Formats

Identity Key File Format

R-VPN-IDENTITY-v1
<base64 public key>
<base64 private key>

Example: 

R-VPN-IDENTITY-v1
AbCdEf123...xyz
XyZaBc456...789

Public Key File Format

R-VPN-PUBLICKEY-v1
<base64 public key>

Example: 

R-VPN-PUBLICKEY-v1
AbCdEf123...xyz

Prekey Bundle Format (JSON)

{
  "identity_key": "base64 encoded Ed25519 public key",
  "identity_x25519_key": "base64 encoded X25519 public key",
  "signed_prekey": "base64 encoded X25519 signed prekey",
  "prekey_signature": "base64 encoded Ed25519 signature",
  "one_time_prekey": "base64 encoded X25519 one-time prekey (optional)"
}

Troubleshooting

Invalid Key Format

Ensure the key file hasn't been corrupted:

# Check file contents
head -n 1 client_identity.key
# Should output: R-VPN-IDENTITY-v1

Key Not Found

Verify the path in your configuration:

[client]
identity_key_file = "/full/path/to/client_identity.key"

Permission Issues

Keys should have restricted permissions:

# Check current permissions
ls -la client_identity.key

# Fix permissions
chmod 600 client_identity.key

Prekey Bundle Errors

If you encounter handshake errors:

  1. Verify the bundle was generated from the correct identity key
  2. Check that the bundle JSON is valid and not corrupted
  3. Ensure the server has the corresponding private bundle

Best Practices

  1. Never share private keys - Keep identity keys secure and never transmit them
  2. Backup keys - Store encrypted copies in secure locations
  3. Rotate periodically - Generate new keys every 6-12 months
  4. Use strong permissions - chmod 600 on all key files
  5. Verify signatures - Always verify server public keys before first connection
  6. Secure deletion - Use shred or similar when deleting old keys
  7. Separate keys - Use different identity keys for different servers

Next Steps