SIM Images — SAIP Profile Packages

A SIM Image is a saved snapshot of a card's whole file system. OmniWeb stores each image as a SAIP Unprotected Profile Package (UPP) in DER encoding — the same interoperable format eUICC profiles use, defined by the TCA eUICC Profile Package: Interoperable Format Technical Specification. One captured card becomes one portable .der file that any SAIP-aware tool can read.

This page is the operations guide for capturing, exporting, uploading, browsing and diffing SIM images, and for using a saved image to back a virtual SIM. The live reader inventory is covered in SIM Bank.

Table of Contents

• Why SAIP UPP
• Architecture Overview
• What's in an Image
• Capturing an Image
• Exporting an Image
• Uploading an Image
• Browsing an Image in the Explorer
• Diffing Two Images
• Backing a Virtual SIM with an Image
• Profile Element Reference
• Troubleshooting

Why SAIP UPP

Earlier builds stored a SIM image as a decoded JSON tree used only for diffing. That format was OmniWeb-private and could not be consumed by any external tool.

Storing the image as a SAIP UPP instead means:

• Portability — the exported .der is a standard profile package. It loads in SAIP profile validators and any SAIP-compliant toolchain.
• One format everywhere — the same .der an operator downloads is what backs a virtual SIM and what the file-system explorer renders. There is no second, divergent representation.
• Reprovisioning — when the card's authentication keys are known (see Capturing an Image), the UPP includes a PE-AKAParameter element carrying Ki and OPc, so the package describes a complete, installable profile rather than a read-only dump.

The package is a raw concatenation of DER-encoded Profile Elements; it is not encrypted (it is an Unprotected Profile Package). Treat an exported .der with the same care as any file holding Ki/OPc — see Troubleshooting.

Architecture Overview

Capture reads the card, the encoder produces a UPP (folding in Ki/OPc from the SIM Key Store if available), and the package is stored. Every consumer reads back from that single stored package — the explorer and diff decode it to a tree on demand; download and the virtual-SIM bankd use the bytes verbatim.

What's in an Image

A captured image holds, for the card's standard MF / ADF.USIM layout:

Element	SAIP Profile Element	Contents
File system	PE-GenericFileManagement	Every reachable EF: its File Control Parameters (FCP) and raw content (transparent EFs) or every record (linear/cyclic EFs)
Identity	PE-Header	The card's ICCID
Authentication	PE-AKAParameter	Ki and OPc for Milenage — only when the card's keys are in the SIM Key Store

Files are created with PE-GenericFileManagement (one operation group per DF) rather than the standardised SAIP file-system templates: a card read recovers raw bytes, not the template a profile creator originally used, so the generic representation is always exact.

Capturing an Image

Capture happens from the SIM Filesystem explorer or the SIM Bank slot actions:

1. Read a card's file system in the explorer.
2. Choose Save image and give it a label.

The decoded file system is encoded to a UPP and stored. If a SIM Key Store entry exists for the card's ICCID with both Ki and OPc, those keys are written into a PE-AKAParameter so the resulting package is fully installable. Without a key-store entry the package still captures the complete file system; only the authentication element is omitted.

Identity columns (ICCID, IMSI, card type, file count) are derived from the file system at capture time so the image list and diff header never have to re-decode the package.

Exporting an Image

Each row in the saved-images list has a download action that serves the stored package verbatim as UPP_<iccid>.der.

The downloaded .der is a standard SAIP UPP and can be inspected with any SAIP-compliant profile tool.

How it works: The file is the exact bytes stored at capture (or upload), with no re-encoding on download, so a round-trip download is byte-identical to what is stored.

Uploading an Image

The saved-images page has an Upload .der action that accepts a SAIP UPP file and stores it as a new image. Use it to bring in profiles generated elsewhere — for example the GSMA TS.48 Generic eUICC Test Profile packages, or a UPP produced by another SAIP tool.

On upload, OmniWeb:

1. Validates the file begins with a SAIP Profile Element tag (a context-class constructed tag — A0, A1 or B0).
2. Stores the package verbatim.
3. Decodes the PE-Header to populate the ICCID column where present.

An uploaded image is a first-class image: it can be downloaded, browsed in the explorer, diffed, and used to back a virtual SIM exactly like a captured one.

Browsing an Image in the Explorer

Every saved image has a Browse in filesystem explorer action. It opens the SIM Filesystem explorer against the stored package — no physical card and no reader are needed. The package is decoded back into the same file-system tree the explorer renders for a live card, so you can inspect every EF's raw content offline.

Diffing Two Images

The saved-images page lets you pick two images and diff them. Both packages are decoded to file-system trees and aligned by EF path, so the comparison is file-by-file regardless of capture order:

Status	Meaning
same	EF present in both with identical content
changed	EF present in both, content differs
only_a	EF present only in the first image
only_b	EF present only in the second image

For a changed EF the diff reports the differing byte ranges (and per-record deltas for record-structured files), so you can see exactly which bytes moved — e.g. a test SIM before and after a personalisation change, or two operators' SIMs side by side.

Backing a Virtual SIM with an Image

A saved image can stand in for a physical card when presenting a virtual SIM. In the virtual-SIM composer, saved images appear alongside the captured rspro images as selectable file-system sources. Pair one with a subscriber identity (from the HSS or the SIM Key Store) and OmniWeb launches a virtual bankd backed by that image's file system, with the subscriber's Ki/OPc overlaid for authentication.

The file system the modem reads is replayed from the image; the identity and keys are overlaid from the chosen subscriber, so one image can back many subscribers.

Profile Element Reference

The UPP is a sequence of Profile Elements, each a DER TLV whose context-class tag identifies its type. OmniWeb writes and reads the subset below; other elements in an uploaded package (PIN, PUK, Security Domain, file-system templates) are preserved on storage and skipped when decoding to a file-system tree.

Tag	Profile Element	Used by OmniWeb
A0	PE-Header	ICCID; profile metadata
A1	PE-GenericFileManagement	The file system (FCP + content)
A4	PE-AKAParameter	Ki and OPc (Milenage)
AA	PE-End	End-of-package marker
B0	PE-MF	(Templated MF — read on upload, not emitted)

For the full element catalogue and encoding rules, see the TCA eUICC Profile Package: Interoperable Format Technical Specification.

Troubleshooting

Exported image has no authentication keys

Symptoms: A downloaded .der has no PE-AKAParameter; a virtual SIM backed by the image cannot authenticate without keys supplied separately.

Possible causes:

• No SIM Key Store entry existed for the card's ICCID at capture time.
• The key-store entry was missing Ki or OPc.

Resolution:

1. Add the card's Ki and OPc to the SIM Key Store, keyed by its ICCID.
2. Re-capture the image — the new capture folds the keys into a PE-AKAParameter.
3. Alternatively, supply the keys at virtual-SIM presentation time (from the HSS or an explicit override).

Upload rejected as "does not look like a SAIP UPP"

Symptoms: Uploading a file returns a validation error.

Possible causes:

• The file is not a SAIP UPP — it does not begin with a Profile Element tag (A0, A1 or B0).
• The file is a protected profile package (encrypted), not an unprotected one.

Resolution:

1. Confirm the file is an Unprotected Profile Package in DER encoding.
2. Verify it begins with a PE-Header (A0) — most well-formed UPPs do.
3. If the package is protected/encrypted, it cannot be stored or browsed; only unprotected packages are supported.

Browsing an uploaded image shows files by FID, not by name

Symptoms: EFs in the explorer are labelled by file identifier (e.g. EF.6FXX) rather than a friendly name.

Possible causes:

• A card read recovers file identifiers and raw content, not the symbolic names a profile creator used. OmniWeb maps the well-known USIM EFs to friendly names; any EF outside that map is shown by its FID.

Resolution: No action needed — the FID is the authoritative identifier and the raw content is exact. This is expected for non-standard or vendor-specific files.

Handling exported packages safely

An exported UPP is unencrypted and, when keys were available at capture, contains Ki and OPc. Treat a downloaded .der as sensitive key material:

• Do not send it over untrusted channels.
• Delete local copies when no longer needed.
• Prefer keeping images inside OmniWeb (where access is gated by the SIM Bank permission) over distributing .der files.