rtmp-auth

name: rtmp-auth description: Explain and debug the XOR-based RTMP authentication system allowed-tools: Read, Grep, Glob, Bash

RTMP Authentication Deep Dive

You are an expert on Theatrum's RTMP authentication system. Use $ARGUMENTS to focus on specific issues (e.g., /rtmp-auth why is my token rejected or /rtmp-auth compute token for username=bob key=mysecret).

Source Files to Read

Always read these before answering:

• src/domain/services/rtmpAuthService.go — Core auth logic (XOR, pattern matching, token validation)
• src/adapters/driver/rtmp/auth/pattern.go — URL pattern-to-regex conversion (legacy, being moved to domain)
• src/adapters/driver/rtmp/handlers/handler.go — OnConnect/OnPublish where auth is invoked
• src/domain/models/stream.go — Stream model with LiveStreamKey and AuthTokenTemplate fields

Authentication Flow

RTMP Client (OBS, FFmpeg, etc.)
  │
  │  Connect: rtmp://server:1935/user/alice
  │
  ▼
┌─────────────────────────────────────────────┐
│ Handler.OnConnect()                          │
│                                              │
│ 1. Extract TCURL from connect command        │
│    tcurl = "rtmp://server:1935/user/alice"   │
│                                              │
│ 2. Parse URL → extract path                  │
│    path = "/user/alice"                      │
│                                              │
│ 3. Match against channel patterns            │
│    pattern: "/user/{username}"               │
│    regex:   ^/user/(?P<username>[^/]+)$      │
│                                              │
│ 4. Extract variables                         │
│    vars = { "username": "alice" }            │
│                                              │
│ 5. IsAuthorized() → true (pattern matched)   │
└─────────────────┬───────────────────────────┘
                  │
                  │  Publish: publishingName = "<hex_token>"
                  ▼
┌─────────────────────────────────────────────┐
│ Handler.OnPublish()                          │
│                                              │
│ 1. ExtractChannel(tcurl) → stream, vars      │
│                                              │
│ 2. Build XOR input from auth_token_template  │
│    template: "{username}"                    │
│    input:    "alice"                         │
│                                              │
│ 3. XOR(input, live_stream_key)               │
│    key:    "your-secure-rtmp-secret-key"     │
│    result: XOR each byte cyclically          │
│    token:  hex.EncodeToString(result)        │
│                                              │
│ 4. Compare: publishingName == expectedToken  │
│    Match → allow publish                     │
│    Mismatch → reject with error              │
└─────────────────────────────────────────────┘

XOR Implementation Details

From rtmpAuthService.go:

func (s *RtmpAuthService) xorString(liveStreamKey string, input string) string {
    inputBytes := []byte(input)
    result := make([]byte, len(inputBytes))
    for i := 0; i < len(inputBytes); i++ {
        result[i] = inputBytes[i] ^ liveStreamKey[i%len(liveStreamKey)]
    }
    return hex.EncodeToString(result)
}

Key properties:

• Cyclic key: The key wraps around (i % len(key)) — short keys repeat
• Hex output: Result is hex-encoded (2 chars per byte, so output length = 2 * input length)
• Symmetric: XOR(XOR(input, key), key) == input — same operation encrypts and decrypts
• Byte-level: Operates on raw bytes, not unicode codepoints

Pattern-to-Regex Conversion

Channel URL patterns are converted to regexes for matching:

The conversion:

1. regexp.QuoteMeta(pattern) — escape all regex special chars
2. Replace \{varname\} with (?P<varname>[^/]+) — named capture group matching any non-slash chars
3. Wrap with ^...$ for full-string matching

Auth Token Template

The auth_token_template field controls what gets XORed with the key:

The template uses {var} placeholders that are replaced with URL-extracted values. Literal characters in the template (like -) are kept as-is.

Computing Tokens

Python (for testing)

def compute_token(key: str, auth_input: str) -> str:
    result = bytes([ord(c) ^ ord(key[i % len(key)]) for i, c in enumerate(auth_input)])
    return result.hex()

# Example: key="testkey123", template="{username}", username="alice"
token = compute_token("testkey123", "alice")
print(token)  # Use this as publishingName in RTMP URL

Go

func computeToken(key, input string) string {
    inputBytes := []byte(input)
    result := make([]byte, len(inputBytes))
    for i := 0; i < len(inputBytes); i++ {
        result[i] = inputBytes[i] ^ key[i%len(key)]
    }
    return hex.EncodeToString(result)
}

Bash (one-liner for quick tests)

python3 -c "
key='YOUR_KEY'; inp='YOUR_INPUT'
print(bytes([ord(c)^ord(key[i%len(key)]) for i,c in enumerate(inp)]).hex())
"

Common Issues

Security Considerations

• XOR is not cryptographic — it's obfuscation, not encryption. Anyone who knows the key can compute valid tokens.
• No replay protection — the same token works forever (until the key changes). There's no nonce or timestamp.
• Key in plaintext config — live_stream_key is stored in config.yml in plaintext.
• No rate limiting — brute-force attempts are not throttled at the auth level.
• Adequate for private streams — sufficient when the goal is preventing accidental unauthorized streaming, not defending against determined attackers.

Debugging Workflow

When a user reports auth failures:

1. Read the config — check the channel pattern, live_stream_key, and auth_token_template
2. Verify the RTMP URL — does the path match the channel pattern exactly?
3. Extract variables — what values would the regex extract from the URL?
4. Build the auth input — substitute variables into the template
5. Compute expected token — XOR the auth input with the key, hex-encode
6. Compare — does the client's publishing name match?

Use Bash to compute tokens interactively when debugging.