The SIM programmer is a Web based interactive tool for exploring and programming SIM cards using an USB card reader.
A JSON/HTTP API allows the card reader to be connected to a computer different from the one running the Web application.
General aspects
The programmer API inherits the generic JSON API so it can be installed as a node in YateMMI. The node name is “simprog” but it can be skipped in the SIM specific requests below since they are not used anywhere else.
A local error is defined which is a success from the JSON API point of view (code 0) but a failure of the programmer.
{ “code”:0, “err”:”error-keyword-here” }
This allows discriminating the configuration, communication, and API errors from errors related to the SIM or the card reader.
In the description below the JSON object is just the content of “params”. Except “card_open” all requests require at least the “session_id” parameter.
Request: card_open
This request establishes a persistent session between the programmer and the card currently inserted in the reader.
For this request the “params” can be missing if performing a default open:
{
“session_id”:”???”, // Optional, reopens a previous session
“class”:”XX”, // Optional, forces to use a specific class of commands
“logged”:true/false // Optional, writes APDU logs to a file
}
Success:
{“code”:0,
“out”:{
“session_id”:”???”, // Obscure session ID to use in other requests
“class”:”XX”, // APDU class (CLA) in hexadecimal, usually “00” or “A0”
“iccid”:”NNNNNNNNNNNNNNNNNNN”, // Decoded card’s circuit ID
“imsi”:”NNNNNNNNNNNNNNN”, // Decoded IMSI, only if pin1req”:false (PIN1 disabled)
“security”:{“pin1req”:true/false,”pin1″:N,”puk1″:NN, …}, // Remaining attempts count for known PIN/PUK/ADM
“dir”:[“XXXX”,”XXXX”,…], // EFdir raw records in hexadecimal
“apps”:{“XXXXX”:”APPNAME1″,”XXXXX”:”APPNAME2″, …}, // Decoded EFdir with AIDs and application names
“reader”:”READER NAME HERE”, // Card reader name as reported by the device
“atr”:”XXXXXX..” // Card’s Answer To Reset in hexadecimal
}
}
Errors:
Request: card_close
Invoke this request to explicitly close the SIM communication session and release the card reader resources.
{
“session_id”:”???”, // ID of the session to close, as returned by card_open
}
Success:
{“code”:0,”out”:{“reader”:”READER NAME HERE”}}
Errors:
Request: card_auth
This request is used to verify the various PIN and ADM access keys to allow reading and writing the SIM.
Request used for verifying a PIN or ADM:
{
“session_id”:”???”, // ID of the session to authenticate, as returned by card_open
“auth”:N, // PIN or ADM number to verify (1, 2 or 4-14)
“verify”:”NNNN” // PIN or ADM value, 4 digits
}
It is also possible to unblock a blocked PIN1 or PIN2 provided you know the corresponding PUK code.
Request used for unblocking a PIN:
{
“session_id”:”???”, // ID of the session to authenticate, as returned by card_open
“auth”:N, // PIN number to unblock (1 or 2)
“unblock”:”NNNNNNNN”, // corresponding PUK code, 8 digits
“new_pin”:”NNNN” // new PIN value, 4 digits
}
Success:
{“code”:0,”out”:{“class”:”XX”,”response”:”9000″}}
where XX is the command class (in hexadecimal) used during authentication
Errors:
To protect against repeated failed attempts and card locking once a failure occurs that PIN or ADM returns “already_…” responses. Close and reopen the card to make another attempt.
Request: card_scan
Use this request to detect the actual profile (which files exist and their characteristics) of an unknown type of SIM.
{
“session_id”:”???”, // ID of the session to scan, as returned by card_open
“profile”:{…}, // Base profile of the SIM in JSON format
“full_aid”:true/false // Optional indication to use the full AID from directory, default true
“content”:true/false // Optionally request to return the content of the files scanned, default false
}
Please do not read the content of the entire SIM, the request will fail. If content is to be returned the profile should be just a small subset of all files.
Success:
{“code”:0,”out”:{“diff”:{…},”duration”:N.NNNNN}
The “diff” object contains differences found between the profile and actual files on the card. Duration of the entire scan is also reported.
Errors:
Request: card_exec
This is the workhorse of the programmer function, it sends arbitrary APDUs to the card and returns the responses.
{
“session_id”:”???”, // ID of the session to execute commands, as returned by card_open
“apdus”:[…] // Array of APDUs to execute
}
Each APDU is a string containing a hexadecimal representation of the bytes to send. A special value of null indicates that the card should be reset at that point.
Success:
{“code”:0,”out”:{“success”:true,”duration”:N.NNNNN,”responses”:[“XXXX”,”XXXXXXXX”, …]}}
For each APDU a raw response is returned. If all APDUs were executed successfully then “success” will be true.
If the “responses” vector is shorter than “apdus” then one command failed and prevented following commands from executing.
If “responses” has same length as “apdus” but “success” is false then the last APDU failed. Duration of the entire command run is also reported.
Errors: