The Oman eID, end to end
A guided tour of the card and the tool that reads and personalizes it — from what a smart card is, through GlobalPlatform, MPCOS and the IAS PKI, to the Workshop you drive it all with. The material is organized into six parts. Use the Simple / Technical switch in the header to change how much detail every explanation shows, then jump to the Workshop to watch these ideas happen on the real card in your reader.
Foundations
How a smart card is built and how we talk to it — the vocabulary the rest of the book uses.
Chapter 1What is the Oman eID?
It's the Omani national ID card — but with a tiny secure computer (a chip) inside. The chip can prove who you are online, hold a digital signature, and act as an e-passport, all protected so it can't be copied.
Chapter 2Anatomy of a smart card
The chip is a complete little computer with no screen or battery. It only wakes up in a reader, and it only ever receives a request, thinks, and sends an answer back. Everything it protects is protected by maths, not by a lock you can see.
Chapter 3APDUs — how we talk to a card
Every message to the card is a small command packet, and the card replies with data plus a 2-byte 'verdict' code. 9000 means OK.
Chapter 4TLV — how data is stored
Data on the card is packed as labelled boxes: a Tag (what it is), a Length (how big), and the Value (the contents).
Chapter 5The file system — MF, DF & EF
Inside the chip, data is organised like folders and files on a computer. There's one root folder, a sub-folder for each application, and the real data lives in small files inside. To read something you first open the right folder, then the file.
Platform & security
How applications are managed, how a card is identified, and the secure channel that protects every write.
Chapter 6GlobalPlatform & Java Card
Think of the card as a phone and the features as pre-installed apps. GlobalPlatform is the 'device admin + app store' that installs them and decides who's allowed to.
A0 00 00 00 18 43 4D 00A0 00 00 00 18 52 4F 50 01A0 00 00 00 18 0C 00 00 01 63 42 00A0 00 00 00 30 80 00 00 00 0A B1 00 01A0 00 00 06 47 2F 00 01A0 00 00 02 47 10 01Chapter 7Identifying a card
Before doing anything, we read three harmless things: the card's 'hello' (ATR), its 'birth certificate' (CPLC), and an identity tag that says Citizen vs Resident and Test vs real.
Chapter 8Keys & diversification
Every card shares one factory 'master key' family — but it would be dangerous if they were all identical. So each card mixes the master key with its own serial number to make keys that are unique to it. We never see the keys; we only see a short 'fingerprint' that proves they're right.
Chapter 9SCP03 & staying safe
To manage the card you must prove you know its secret key. Both sides swap random numbers and compute a matching proof. The big danger: guessing wrong locks the card forever after only 3 tries. So our tool checks the card's proof first and only sends our reply when it already knows it will succeed — it can never lock the card.
Chapter 10Lifecycle & dangerous operations
A card has a 'life cycle' — stages from factory-fresh to retired. Some moves forward can never be undone, and a few operations can permanently brick the card. The tool is built so you can explore all of this safely, but it's important to know which actions are the dangerous ones.
MPCOS — data, keys & what it proves
The legacy identity store: its access rules, PINs and secure key loading — and what personalizing it end-to-end reveals about the “issuer wall.”
Chapter 11Access conditions — the 2-byte lock
Every file on the card carries a tiny 2-byte rule that says who may read it, who may change it, and who may never touch it. Learning to read those two bytes tells you at a glance whether a field is public, locked behind a PIN, or frozen forever.
Chapter 12Writing data & the safety gate
Reading is safe; writing changes the card. Personalization means writing the cardholder's details into little files on the chip. To make sure nothing happens by accident, the tool always asks you to confirm first — and real cards are protected until you deliberately turn writes on.
Chapter 13MPCOS PINs & the secret-code file
The card keeps its PINs in one small file with eight numbered slots. On the Oman ID app, slot 5 is the cardholder's PIN that unlocks the protected fields, and slot 8 is the PUK — the 'master PIN' used to rescue a PIN that got blocked from too many wrong tries.
Chapter 14Loading keys & PINs without an HSM
You can't just write a key or PIN into the card as plain bytes — the chip ignores that. Instead you send it as a scrambled little package that only the current session can unlock, and the card sends back a short proof that it landed correctly. This is the exact step everyone assumed needed the manufacturer's secure server — and it turns out we can build the package ourselves.
Chapter 15Personalizing a blank card end-to-end
Putting it all together: starting from a blank card we open an admin session, create the folders and files, load the keys and the PIN/PUK, and finally write the identity fields — marking the sensitive ones as PIN-protected. The result is a working ID card built entirely on the workstation.
→ Personalize a card in the WorkshopChapter 16Reading protected files & the PUK
To read a protected field you open the card's secure channel and type the PIN — but the PIN never travels in the clear; it's scrambled first. Type it wrong too many times and the PIN blocks, and the PUK is supposed to rescue it. Blocking works exactly like a real card; the PUK rescue is still a work in progress.
→ Read the protected fields in the WorkshopChapter 17The issuer wall — re-examined
We first assumed you could read a card but never build one — that 'issuing' was locked inside the manufacturer's secure server. Digging into the real tools showed that's only half true. The server mostly just mixes the master keys with the card's serial number, which we can reproduce ourselves once we hold those master keys. So with the master keys and a blank card, we personalized a fully working card locally. What still can't be forged is a card that's already finished and frozen — plus the factory's own perso keys we don't have.
IAS & PKI
The modern PKI application: certificates and keys, and how we install, personalize and read it back.
Chapter 18IAS, PKI & secure messaging
IAS is the part of the card that does digital signatures and proves your identity online, using public-key cryptography (PKI). First we install the empty app; then, in chapter 20, we fill it with keys, a PIN and a certificate. Both jobs run over the encrypted admin channel, so every command is signed to prove it really came from us and wasn't tampered with on the way.
Chapter 19Certificates, X.509 & PKCS#15
A certificate is a signed statement that says 'this public key belongs to this person.' The card keeps the matching private key locked inside and never lets it out; the certificate is public. Because a trusted authority signed the certificate, anyone can check it's genuine and hasn't been altered. The card also keeps a little index so software knows which key, certificate and PIN go together.
→ Explore the PKCS#15 index in the WorkshopChapter 20Personalizing IAS & writing a certificate
Putting real keys and a certificate onto the card. Installing only creates the empty PKI app; personalizing logs into it over an encrypted channel and writes its secret key, its PIN, a signing key, its folder structure, and a genuine digital certificate — then finalizes it so the card is ready to sign with the PIN.
Chapter 21Exploring the IAS PKI
Reading everything the PKI app holds — safely. We open the app and list its certificates, keys and PIN status without ever typing a PIN or changing anything. A deeper 'authenticated' pass opens the encrypted channel to also read protected content, like the face photo.
→ Explore IAS in the Workshop (read-only or deep)Chapter 22Signing with a PIN on the card
The whole point of the PKI app: making a real digital signature. You type your PIN, the chip signs your message with its private key, and anyone can check the signature with the public certificate. The private key never leaves the card — the card itself does the signing, and only after you enter the PIN.
The other applications
The rest of what the chip can hold — the e-passport and the applets this tool doesn't drive — and why.
Chapter 23e-Passport (eTravel) & PACE
The card can also act as an e-passport. To stop anyone secretly reading it over the air, the chip only opens up after you prove you can physically see the document — by entering a password printed on it (the machine-readable text, or a 6-digit number). Then the reader can fetch the holder's details and photo, and check the issuer's signature to be sure nothing was changed.
The eTravel applet is contactless and PACE-gated: reading it needs the MRZ/CAN-derived keys printed on the document, which the test cards don't carry — so this tool doesn't operate it. The mechanics are covered here for background.
Chapter 24FIDO, MOCA & PURE
Beyond identity and signatures, the chip carries a few more applications: a fingerprint check that happens inside the card, a phishing-resistant login key for websites, and a bank-card-style applet. This tool focuses on the ID and PKI applications, so it shows these exist but doesn't drive them — each needs credentials or an enrolment this tool doesn't have.
Phishing-resistant login. Per-site key handles + a signature counter; attestation cert.
Match-on-card fingerprint. Templates never leave the chip; BioPIN fallback.
Payment kernel, personalized post-issuance via its own SSD over SCP02.
Chapter 25Match-on-card: fingerprints on the chip
A normal system checks your fingerprint by sending it to a computer that holds a copy. Match-on-card flips that around: your fingerprint is stored inside the chip, and the comparison happens inside the chip too. Nothing about your finger ever comes back out — the card only ever answers 'yes, that's the finger' or 'no, it isn't'. This tool can set that up on a test card with a made-up (synthetic) fingerprint, then prove the matching works.
Holds the enrolled template and does the comparison on-chip. Personalized with a synthetic ISO 19794-2 fingerprint; the matcher goes live automatically.
The applet an app talks to for a runtime VERIFY. Its install parameter is applet-private (not in the vendor manual), so runtime verify needs the vendor integration guide.
Using the Workshop
How the tool itself works: the card overview, the two views, the contextual toolbox and the safety model.
Chapter 26The Workshop & the two views
The Workshop is the main screen. Put a card in the reader, press Scan, and it draws everything on the card as a grid of applications — each showing whether it's present. There are two ways to view the work: Simple, which shows plain outcomes, and Technical, which shows every command the tool sends. The switch is in the top bar; this whole book responds to it too.
→ Open the WorkshopChapter 27The toolbox & the safety model
Instead of a menu of raw commands, each application on the card offers just the actions that make sense for it right now. An empty IAS offers Install; once installed it offers Personalize; once personalized it offers Explore and Sign. Anything that changes the card asks you to confirm first, and the tool refuses to touch anything but test cards.