JSON API for SIM Programmer

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:

  • "noreader" - a card reader is not connected
  • "nocard" - the SIM is not inserted or it's not detected by the reader
  • "nosim" - a card is inserted but it doesn't appear to be a SIM
  • "busy" - another session is in progress

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:

  • "notopen" - the specified session is not open
  • "failed" - a failure occured while trying to close the card

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:

  • "notopen" - the specified session is not open
  • "unsupported" - the PIN or ADM is not supported by the card
  • "disabled" - the PIN1 verification is disabled
  • "incorrect" - the provided PIN or PUK was incorrect; this causes the attempts counter to decrement!
  • "incorrect_remaining_N" - the provided PIN or PUK was incorrect and the remaining attempts counter (1-9) is returned
  • "blocked" - the PIN, PUK or ADM is blocked because of too many incorrect attempts
  • "failed" - command failed to execute and returned no status
  • "failed_XXXX" - command failed with status XXXX (hexadecimal)
  • "already_STATUS" - command was already attempted in the current session and returned STATUS; note that "already_succeeded" may be returned

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:

  • "notopen" - the specified session is not open

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:

  • "notopen" - the specified session is not open