RSA Keys

This guide will walk you through creating and using RSA key pairs for authenticating embedded users. Even if you're not technical, you can follow these steps or share them with your developer.

What Are RSA Keys?

RSA keys are a pair of cryptographic keys used to securely sign and verify authentication tokens:

• Private Key: Like a master key - you keep this secret on your server. Never share it.
• Public Key: Like a lock - you share this with Round Two so they can verify your tokens.

Think of it like this: Your private key "signs" tokens (like signing a document), and Round Two uses your public key to verify that signature is authentic.

Why Do I Need This?

Round Two needs to verify that authentication tokens are coming from your application and haven't been tampered with. RSA keys provide this security:

• Security: Only your server can create valid tokens (because only you have the private key)
• Verification: Round Two can verify tokens are authentic (using your public key)
• Industry Standard: RSA is used by banks, governments, and major tech companies

Step 1: Generate Your Key Pair

You'll generate two files: a private key (keep secret) and a public key (share with Round Two).

Option A: Using Command Line (Mac, Linux, or Windows with Git Bash)

Step 1.1: Open Terminal

• Mac: Press Cmd + Space, type "Terminal", press Enter
• Linux: Press Ctrl + Alt + T or search for "Terminal"
• Windows: Install Git Bash (https://git-scm.com/downloads), then open Git Bash

Step 1.2: Navigate to a Safe Folder

# Create a folder for your keys (you can name it anything)
mkdir ~/roundtwo-keys
cd ~/roundtwo-keys

What this does: Creates a folder in your home directory where you'll store your keys.

Step 1.3: Generate the Private Key

openssl genrsa -out private_key.pem 2048

What this does: Creates a file called private_key.pem containing your private key. The 2048 means it's 2048 bits long (strong security).

Important: You'll see no output if it works correctly. This is normal!

Step 1.4: Generate the Public Key

openssl rsa -in private_key.pem -pubout -out public_key.pem

What this does: Creates a file called public_key.pem containing your public key, derived from your private key.

Step 1.5: Verify Your Keys Were Created

ls -la

What this does: Lists all files in the folder. You should see:

• private_key.pem (your secret key)
• public_key.pem (the key you'll share)

Option B: Using Windows PowerShell

Step 1.1: Open PowerShell

• Press Windows + X, then select "Windows PowerShell" or "Terminal"

Step 1.2: Navigate to a Safe Folder

# Create a folder for your keys
New-Item -ItemType Directory -Path "$env:USERPROFILE\roundtwo-keys"
cd "$env:USERPROFILE\roundtwo-keys"

Step 1.3: Check if OpenSSL is Installed

openssl version

If you see a version number: Great! Skip to Step 1.4.

If you see an error: Install OpenSSL:

1. Download from: https://slproweb.com/products/Win32OpenSSL.html
2. Install the "Win64 OpenSSL" version
3. During installation, choose "Copy OpenSSL DLLs to" → "The Windows system directory"
4. Restart PowerShell and try again

Step 1.4: Generate the Private Key

openssl genrsa -out private_key.pem 2048

Step 1.5: Generate the Public Key

openssl rsa -in private_key.pem -pubout -out public_key.pem

Step 1.6: Verify Your Keys Were Created

Get-ChildItem

You should see both private_key.pem and public_key.pem.

Option C: Using Online Tools (Not Recommended for Production)

Warning: Online tools are convenient but less secure. Only use for testing or if you understand the risks.

1. Visit: https://8gwifi.org/rsakeygenerator.jsp
2. Select "RSA 2048"
3. Click "Generate Key"
4. Copy the "Public Key" (this is your public key)
5. Copy the "Private Key" (this is your private key - keep it secret!)

Important: For production, always use command-line tools on your own computer.

Step 2: View Your Public Key

You need to copy your public key to share it with Round Two. Here's how:

On Mac/Linux:

cat public_key.pem

On Windows PowerShell:

Get-Content public_key.pem

What You'll See:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
(many lines of letters and numbers)
...
-----END PUBLIC KEY-----

Important: Copy the ENTIRE output, including the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- lines.

Step 3: Add Public Key to Round Two

1. Log into your Round Two workspace
2. Go to your board's settings
3. Click the Embed tab
4. Scroll to "Authentication & Security"
5. Paste your entire public key into the "Public Key (PEM format)" field
6. Click "Save Changes"

What this does: Round Two stores your public key and uses it to verify tokens from your application.

Step 4: Use Your Private Key in Your Application

Your private key must be stored securely in your application and used to sign tokens.

Where to Store Your Private Key

Option 1: Environment Variables (Recommended)

Store your private key as an environment variable:

# In your .env file (never commit this to version control!)
ROUNDTWO_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
(many lines)
...
-----END RSA PRIVATE KEY-----"

Option 2: Secure File Storage

Store private_key.pem in a secure location:

• Not in your code repository
• Not accessible via web server
• Only readable by your application
• Use file permissions to restrict access

Option 3: Secret Management Service (Best for Production)

Use services like:

• AWS Secrets Manager
• Google Cloud Secret Manager
• Azure Key Vault
• HashiCorp Vault

How to Use Your Private Key

Your developer will use the private key to sign tokens. Here's what they need to know:

const jwt = require('jsonwebtoken');
const fs = require('fs');

// Load private key from environment variable or file
const privateKey = process.env.ROUNDTWO_PRIVATE_KEY 
  || fs.readFileSync('path/to/private_key.pem', 'utf8');

// Sign a token
const token = jwt.sign(
  {
    iss: 'yourworkspace/yourboard', // Format: "[workspace]/[board]" in lowercase
    aud: 'roundtwo',
    sub: user.id, // Required: unique user ID
    name: user.name || user.displayName, // Required: display name (non-empty string)
    email: user.email, // Required: valid email address format
    avatar_url: user.avatarUrl, // Optional: avatar URL
    exp: Math.floor(Date.now() / 1000) + 300,
    iat: Math.floor(Date.now() / 1000),
  },
  privateKey,
  { algorithm: 'RS256' }
);

import jwt
import os

# Load private key
private_key = os.getenv('ROUNDTWO_PRIVATE_KEY')
if not private_key:
    with open('path/to/private_key.pem', 'r') as f:
        private_key = f.read()

# Sign a token
token = jwt.encode(
    {
        'iss': 'yourworkspace/yourboard',  # Format: "[workspace]/[board]" in lowercase
        'aud': 'roundtwo',
        'sub': user.id,  # Required: unique user ID
        'name': user.name,  # Required: display name (non-empty string)
        'email': user.email,  # Required: valid email address format
        'avatar_url': user.avatar_url,  # Optional: avatar URL
        'exp': int(time.time()) + 300,
        'iat': int(time.time()),
    },
    private_key,
    algorithm='RS256'
)

Step 5: Test Your Keys

After setting up, test that everything works:

1. Generate a test token using your private key
2. Verify the token works with Round Two's embed authentication
3. Check that feedback submissions work correctly

If you encounter errors, see the Troubleshooting section below.

Security Best Practices

✅ DO:

• Keep your private key secret: Never share it, commit it to code, or send it via email
• Use different keys for different environments: Production, staging, and development should each have their own key pair
• Rotate keys periodically: Generate new keys every 6-12 months
• Use strong file permissions: On Linux/Mac, set private key permissions to 600 (only you can read/write):
  Copy

  chmod 600 private_key.pem
  

• Backup your private key securely: Store encrypted backups in a secure location
• Monitor key usage: Log when keys are used and monitor for suspicious activity

❌ DON'T:

• Don't commit keys to version control: Add *.pem to your .gitignore file
• Don't share private keys: Not even with Round Two support
• Don't use the same key for multiple boards: Each board should have its own key pair
• Don't store keys in plain text: Use environment variables or secret management
• Don't use keys shorter than 2048 bits: 2048 is the minimum recommended length

Rotating Keys (Changing Your Keys)

If you need to change your keys (security incident, key compromise, or routine rotation):

1. Generate a new key pair (follow Step 1 above)
2. Add the new public key to Round Two (follow Step 3 above)
3. Update your application to use the new private key
4. Test thoroughly to ensure everything works
5. Remove the old public key from Round Two settings

Important: During rotation, both old and new keys will work temporarily. Once you've verified the new key works, remove the old one.

Troubleshooting

"OpenSSL: command not found"

Problem: OpenSSL isn't installed on your system.

Solution:

• Mac: Install via Homebrew: brew install openssl
• Linux: Install via package manager: sudo apt-get install openssl (Ubuntu/Debian) or sudo yum install openssl (CentOS/RHEL)
• Windows: Download from https://slproweb.com/products/Win32OpenSSL.html

"Invalid key format" Error in Round Two

Problem: The public key wasn't copied correctly.

Solution:

• Make sure you copied the ENTIRE key, including -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----
• Check for extra spaces or line breaks
• Ensure you're using the public key (not the private key)
• Verify the key is in PEM format (not DER or other formats)

"Token verification failed" Error

Problem: The public key in Round Two doesn't match your private key.

Solution:

• Verify you're using the correct key pair (private and public keys must match)
• Check that the public key in Round Two matches the one you generated
• Ensure you're using the correct private key in your application
• Verify the issuer (iss claim) matches exactly: [Workspace Name]/[Board Title]

"Permission denied" When Reading Private Key

Problem: File permissions are too restrictive.

Solution:

# Make the file readable by your application user
chmod 600 private_key.pem  # Only owner can read/write
# Or if your app runs as a different user:
chmod 644 private_key.pem  # Owner can read/write, others can read

Keys Work Locally But Not in Production

Problem: Environment differences or key not properly deployed.

Solution:

• Verify the private key is available in your production environment
• Check environment variables are set correctly
• Ensure file paths are correct in production
• Verify file permissions allow your application to read the key
• Check that the public key in Round Two matches your production private key

Getting Help

If you're stuck:

1. Check the error message: It often tells you exactly what's wrong
2. Verify each step: Go back through the steps to ensure you didn't miss anything
3. Test with a simple example: Try generating a test token to isolate the issue
4. Contact your developer: If you're not technical, share this guide with your developer
5. Contact Round Two support: If the issue is with Round Two's verification, reach out with:
   • The error message you're seeing
   • When the error occurs
   • Your board ID (not your keys!)

Quick Reference

Generate keys:

openssl genrsa -out private_key.pem 2048
openssl rsa -in private_key.pem -pubout -out public_key.pem

View public key:

cat public_key.pem  # Mac/Linux
Get-Content public_key.pem  # Windows

Set secure permissions (Mac/Linux):

chmod 600 private_key.pem

What to share: Only the public key (public_key.pem) What to keep secret: The private key (private_key.pem)

Next Steps

• Token Endpoint - Use your private key to sign tokens
• User Data - Include user information in tokens
• Testing - Verify everything works correctly