SurfSIM User Guide

Programming SIM cards for your private 5G network.

1. Introduction

SurfSIM is a web-based tool for programming SIM cards for your private 5G network. It handles the complex encoding and writes for you — just fill in the form and click Program.

Instead of running command-line tools and manually encoding hex values, SurfSIM gives you a clean interface to:

• Write subscriber identities (IMSI) and network codes (MCC/MNC) to your SIM cards

• Set authentication keys (K and OPc) for network access

• Configure 5G privacy protection (SUCI)

• Program multiple cards in batch with auto-incrementing IMSIs

• Save and reuse programming profiles

[Screenshot: SurfSIM dashboard showing reader status and SIM info] The SurfSIM dashboard — your card reader status, SIM card info, and programming form in one place.

2. Getting Started

What You Need

Installation

1. Install system dependencies (Linux — Debian/Ubuntu):

   sudo apt install pcscd pcsc-tools

2. Install SurfSIM:

   pip install surfsim

3. Start the smart card service (Linux):

   sudo systemctl start pcscd
   sudo systemctl enable pcscd

Note: On macOS, the smart card service runs automatically. On Windows, your card reader's driver handles this.

Starting SurfSIM

Run this command in your terminal:

surfsim start

SurfSIM will start and open your browser to http://127.0.0.1:8808. You'll see the dashboard with your card reader status.

Note: To use a different port, run surfsim start --port 9000. To prevent the browser from opening automatically, use surfsim start --no-browser.

Connecting Your Card Reader

1. Plug your USB smart card reader into your computer

2. Insert a SIM card into the reader (chip facing down for most readers)

3. Check the reader status indicator in SurfSIM

The reader status indicator tells you what's happening:

[Screenshot: Reader status showing green "Card Ready" indicator] A green indicator means your reader and SIM card are detected and ready.

3. Understanding the Dashboard

When you open SurfSIM, you'll see the main dashboard with status information and quick actions.

Status Cards

Reading SIM Card Info

When a SIM card is inserted and the reader shows green, SurfSIM can read the card's current values. Each field tells you something about the card:

Using Card Values in the Form

If you want to reprogram a card with updated values, click the "Use in form" button on the SIM Card Info panel. This copies the card's current values into the programming form, so you only need to change what's different.

[Screenshot: SIM card info panel showing card details with "Use in form" button] Click "Use in form" to populate the programming form with the card's current values.

4. Programming a SIM Card

Before You Start

Make sure you have everything ready:

Note: Your SIM card's ICCID is set at the factory and cannot be changed. SurfSIM reads it for your reference but does not modify it.

Step-by-Step: Programming Your First SIM

1. Insert your SIM card into the reader and verify the reader status shows green ("Card Ready").

   [Screenshot: Green reader status indicator showing "Card Ready"] Confirm green status before programming.

2. Click the Program tab to open the programming form.

3. Enter your ADM Key — this is the administrative password for your SIM cards, provided by your SIM card supplier. It's a numeric code (up to 8 digits).

   [Screenshot: ADM Key field in the programming form] The ADM key is shown as a password field for security.

4. Enter your MCC — the 3-digit Mobile Country Code for your network (e.g., 315 for the United States).

5. Enter your MNC — the 2 or 3-digit Mobile Network Code for your network.

6. Enter your IMSI — the 15-digit International Mobile Subscriber Identity. Your network administrator provides this. It typically starts with your MCC and MNC.

7. Enter your K key — the 32-character hex authentication key (e.g., 465B5CE8B199B49FAA5F0A2EE238A6BC). This is shared between the SIM and your network core.

8. Enter your OPc key — the 32-character hex operator key (e.g., E8ED289DEBA952E4283B54E88E6183CA). Also shared with your network core.

9. (Optional) Enter a Service Provider Name — this is the name shown on devices using this SIM (up to 16 characters, e.g., "Waveriders").

10. Consider enabling Dry Run — check the "Dry Run" box to validate all your parameters without actually writing to the card. This is a good way to catch mistakes before committing.

    [Screenshot: Dry Run checkbox and Program SIM button] Use Dry Run to validate your parameters first.

11. Click "Program SIM" to start programming.

Understanding the Results

After programming, you'll see a results summary showing each operation:

[Screenshot: Successful programming result modal showing all steps passed] A successful programming result — all steps show green checkmarks.

Each step is listed individually:

If a step fails, the remaining steps are still attempted. Check the error message for the failed step — the most common issue is an incorrect ADM key.

Verifying Your Card

After programming, verify the card was written correctly:

1. Remove the SIM card from the reader

2. Reinsert the SIM card

3. Check the SIM Card Info panel — it should show your new values

4. Confirm that the IMSI, MCC/MNC, and SPN match what you programmed

Note: The ICCID will remain unchanged — it's the card's factory serial number.

5. Programming Multiple SIM Cards (Batch Mode)

If you need to program several SIM cards with the same network settings, batch mode saves time by auto-incrementing the IMSI for each card.

How Batch Mode Works

You fill in the programming form once with the first card's values, then tell SurfSIM how many cards to program. For each subsequent card, SurfSIM automatically increments the IMSI by your chosen step value. All other settings (MCC, MNC, K, OPc, SPN, SUCI) stay the same.

Note: The ICCID is not incremented. Each card keeps its factory-assigned ICCID.

Step-by-Step: Batch Programming

1. Fill in the programming form with the values for your first SIM card (follow the steps in Section 4).

2. Enable Batch Mode — toggle the Batch Mode switch.

   [Screenshot: Batch mode toggle and settings showing card count and IMSI increment] Enable batch mode and set your card count and IMSI increment.

3. Set the number of cards — how many SIM cards you want to program (1–100).

4. Set the IMSI increment — how much to increase the IMSI for each card (default: 1). For example, if your first IMSI is 999700000000001 and increment is 1, the second card gets 999700000000002, the third gets 999700000000003, and so on.

5. Click "Program N Cards" (where N is your card count).

6. For each card: SurfSIM will program the current card, then prompt you to swap it. Remove the programmed card, insert the next blank card, and confirm when ready.

Batch Results

After the batch completes, you'll see a summary:

Note: If a card fails during batch programming, SurfSIM continues with the remaining cards. You can reprogram any failed cards individually afterward.

6. Using Profiles

Profiles let you save a set of programming parameters so you can reuse them later. This is especially useful if you program cards for multiple networks or need consistent settings across batches.

Saving a Profile

1. Fill in the programming form with the values you want to save

2. Click the "Save as Profile" button

3. Enter a name and (optionally) a description for the profile

4. Click Save

Your profile is saved and can be loaded at any time.

Loading a Profile

1. Go to the Profiles tab

2. Click on a profile card to select it

3. The programming form is automatically populated with the profile's values

4. Make any changes you need, then program as usual

Managing Profiles

[Screenshot: Profiles tab showing saved profiles with action icons] Your saved profiles — click to load, or use the icons to edit, duplicate, or delete.

Note: Profiles are stored as JSON files in ~/.config/surfsim/profiles/. Each profile is a separate file, so they're easy to back up or share between machines.

7. 5G Privacy (SUCI Configuration)

What Is SUCI?

When a device connects to a 5G network, it needs to identify itself. Normally, this identity (the IMSI) is sent in the clear — meaning anyone listening could intercept it. SUCI (Subscriber Concealed Identifier) encrypts this identity so it can't be intercepted. Think of it as putting your ID in a sealed envelope instead of showing it openly.

Do I Need SUCI?

If you're running a 5G SA (Standalone) network and want subscriber privacy protection, yes. Your network administrator will provide the public keys needed for SUCI configuration.

If you're running a 4G network or a 5G NSA (Non-Standalone) network, you can leave SUCI disabled.

Default Configuration

When you enable SUCI, SurfSIM provides a sensible default configuration with three protection schemes in priority order:

Configuring SUCI

1. Enable the SUCI toggle in the programming form

   [Screenshot: SUCI configuration section with toggle enabled and key fields] Enable SUCI and add your network's public keys.

2. Add your public keys — for each key, provide:

   Field	What to Enter
   Identifier	A number (1, 2, etc.) to reference this key
   Profile	A (X25519) or B (P-256) — your network admin will tell you which
   Key	The public key in hex format

3. Set protection scheme priorities — each scheme references a key by its identifier. The default priority order (Profile A → Profile B → Null) works for most deployments.

Converting Keys

If you received your public keys in PEM format (a text block starting with -----BEGIN PUBLIC KEY-----), you'll need to convert them to hex first:

1. Go to the Tools tab

2. Open the Key Converter

3. Paste your PEM key

4. Copy the hex output

5. Use this hex value in the SUCI configuration

See Section 8: Tools for more details.

Note: P-256 keys must be in compressed form (starting with 02 or 03). The Key Converter handles this automatically.

8. Tools

SurfSIM includes utility tools to help with key format conversion and hex formatting.

PEM to Hex Key Converter

If your network administrator provides public keys in PEM format, this tool converts them to the hex format SurfSIM needs.

1. Go to the Tools tab

2. Paste your PEM key into the input box (the full block including -----BEGIN and -----END lines)

3. The tool detects the key type automatically (X25519 or P-256)

4. Copy the hex output to use in your SUCI configuration or elsewhere

[Screenshot: Key converter tool with PEM input and hex output showing detected key type] Paste a PEM key and get the hex value — the key type is detected automatically.

Note: For P-256 keys, the converter outputs the compressed form by default (33 bytes / 66 hex characters). This is the format SUCI requires.

Hex Formatter

The Hex Formatter toggles between plain hex and colon-separated hex for readability:

This is useful when comparing keys with other tools or documentation that use different formats.

9. Troubleshooting

Card Reader Issues

Programming Errors

Common Questions

Can I change the ICCID? No. The ICCID is set at the factory and cannot be changed. It's your SIM card's permanent serial number.

What happens if I program the same card twice? The previous values are overwritten with the new ones. There's no harm in reprogramming a card.

Can I undo a programming operation? There's no undo button, but you can reprogram the card with different values at any time (as long as you have the ADM key).

What's the maximum batch size? 100 cards per batch. If you need to program more, run multiple batches.

Do I need internet access? No. SurfSIM runs entirely on your local machine. No data is sent to external servers.

Can I use SurfSIM with non-Sysmocom SIM cards? SurfSIM is designed and tested with Sysmocom SJA2 and SJA5 cards. Other programmable SIM cards may work but are not officially supported.

10. Quick Reference

11. Getting Help

If you run into an issue that isn't covered in this guide, contact Waveriders support:

Email: support@waveriders.live

When reaching out, it helps to include:

• What you were trying to do (e.g., "programming a SIM card" or "batch mode")

• The error message you saw (if any)

• Which page or section of SurfSIM you were on

• Your SIM card type (SJA2 or SJA5) and card reader model

SurfSIM v0.1.0 — Programming SIM cards for private 5G networks.