Commit Graph

128 Commits

Author SHA1 Message Date
Philipp Maier 5482737f31 pySim-shell: don't get trapped in applications without file system
When we traverse the file system, we may also end up selecting
applications (ADF), which do not support an USIM/ISIM like file system.
This will leave us without the ability to select the MF (or any other
file) again. The only way out is to select the ISIM or USIM application
again to get the access to the file system again.

Change-Id: Ia2fdd65f430c07acb1afdaf265d24c6928b654e0
Related: OS#5418
2023-12-07 13:21:07 +00:00
Philipp Maier 1c207a2499 pySim-shell: Do not use self.lchan.scc when sending raw APDUs.
When sending raw APDUs, we access the scc (SimCardCommands) object via
the scc member in the lchan object. Unfortunately self.lchan will not be
populated when the rs (RuntimeState) object is missing. This is in
particular the case when no profile could be detected for the card,
which is a common situation when we boostrap an unprovisioned card.

So let's access the scc object through the card object. This is also
more logical since when we send raw APDUs we work below the level of
logical channels.

Change-Id: I6bbaebe7d7a2013f0ce558ca2da7d58f5e6d991a
Related: OS#6278
2023-11-29 15:24:10 +01:00
Philipp Maier eb3b0dd379 pySim-shell: refuse to execute a startup script on initialization errors
When there is an error on initialization (e.g. card not present), we
should not continue to execute a startup script that was passed with the
pySim-shell commandline. Instead we should print a message that the
startup script was ignored due to errors.

Related: OS#6271
Change-Id: I61329988e0e9021b5b0ef8e0819fb8e23cabf38b
2023-11-24 12:41:18 +01:00
Harald Welte 8fab463e67 pySim-shell: Move init_card() function to new module
The point of this is to move generic code out of,
paving the way for more/other executables using the full power of
our class model without having to reinvent the wheel.

Change-Id: Icf557ed3064ef613ed693ce28bd3514a97a938bd
2023-11-09 12:36:47 +00:00
Harald Welte 1c849f8bc2 pySim-shell: Reject any non-decimal PIN values
Don't even send any non-decimal PIN values to the card, but reject
them when parsing the command arguments.

Change-Id: Icec1698851471af7f76f20201dcdcfcd48ddf365
2023-11-03 00:43:17 +01:00
Harald Welte 977c5925a1 pySim-shell: permit string with spaces for 'echo' command
before this patch:

pySIM-shell (00:MF)> echo foo bar baz
usage: echo [-h] string
echo: error: unrecognized arguments: bar baz

after this patch:

pySIM-shell (00:MF)> echo foo bar baz
foo bar baz

Change-Id: I1369bc3aa975865e3a8a574c132e469813a9f6b9
2023-11-03 00:43:17 +01:00
Harald Welte 4e59d89a5d pySim-shell: Validate that argument to 'apdu' command is proper hexstr
Let's not even send anything to the card if it's not an even number
of hexadecimal digits

Change-Id: I58465244101cc1a976e5a17af2aceea1cf9f9b54
2023-11-03 00:43:17 +01:00
Harald Welte f9ea63ea51 pySim-shell: Improved argument validation for verify_adm argument
Let's make sure we don't even bother to ask the card to verify
anything as ADM1 pin which is not either a sequence of decimal digits
or an even number of hex digits (even number of bytes).

Change-Id: I4a193a3cf63462fad73d145ab1481070ddf767ca
2023-11-03 00:43:17 +01:00
Harald Welte 469db9393f pySim-shell: Use argparser for verify_adm to support --help
Let's add a proper argparser instance for the 'verify_adm' command,
avoiding situations where the user types 'verif_adm --help' and then
--help is interpreted as the PIN value, removing one more attempt from
the failed ADM1 counter.

Let's use that opportunity to improve the documentation of the command.

Change-Id: I3321fae66a11efd00c53b66c7890fce84796e658
2023-11-02 21:46:38 +00:00
Harald Welte 0ba3fd996a pySim-shell: Add copyright statement and link to online manual to banner
This way the users are reminded where they can go to read the manual.

Change-Id: Ie86822e73bccb3c585cecc818d4462d4ca6e43c2
2023-11-02 21:46:13 +00:00
Harald Welte 268a2025db Initial support for eUICC
This just adds basic support for the ISD-R application and its
associated STORE DATA command which is used for the ES10x interfaces
between off-card entities and the on-card ISD-R.

Change-Id: Ieab37b083e25d3f36c20f6e9ed3e4bdfdd14a42a
Closes: OS#5637
2023-10-26 15:16:30 +00:00
Harald Welte 237ddb5bb3 pySim-shell: Include current logical channel in prompt
Now that pySim-shell can switch between logical channels, let's state
the currently used logical channel in the prompt.

Change-Id: I45781a6fba205eeb4ac7f58d5cb642b7131bdd88
Related: OS#6230
2023-10-24 15:10:01 +02:00
Harald Welte 20650997e8 pySim-shell: Add 'switch_channel' command
We've already had the 'open_channel' and 'close_channel' commands,
which were sent to (and acknowledged by) the card.  However,
those commands didn't affect the pySim-shell state, i.e. all
communication would still happen through the default channel '0'.

With this patch we introduce a 'switch_channel' command, using which
the user can determine which of the (previously opened) logical channels
shall be used by pySim-shell.

Change-Id: Ia76eb45c4925882ae6866e50b64d9610bd4d546d
Closes: OS#6230
2023-10-24 15:10:01 +02:00
Harald Welte 46255121e0 pySim-shell: Create + use per-RuntimeLchan SimCardCommands
This new approach will "fork" separate SimCardCommands instances
for each RuntimeLchan.  Higher-layer code should now always use the
RuntimeLchan.scc rather than the RuntimeState.card._scc in order to
make sure commands use the correct logical channel.

Change-Id: I13e2e871f2afc2460d9fd1cd566de42267c7d389
Related: OS#6230
2023-10-24 15:10:01 +02:00
Harald Welte bdf595756e pySim-shell: Create/delete RuntimeLchan objects on open/close of channel
We already have the open channel and close_channel commands in
pySim-shell. They are sent to the card and acknowledged, respectively.

We also already do have code that can track multiple different logical
channels (the rs.lchan array).  However, this is currently only used by
pySim-trace, and not by pySim-shell.  Let's change that.

Change-Id: Idacee2dc57e8afe85c79bc85b259064e7f5b83a2
Related: OS#6230
2023-10-21 21:47:04 +02:00
Philipp Maier 7c0cd0a93b pySim-shell: do not fail when EF.ICCID does not exist
An eUICC that has no active eSIM profile does not have an ICCID. (The
reason for this is that EF.ICCID is part of the eSIM profile).
Unfortunately pySim-shell insists on reading the ICCID from EF.ICCID on
startup in order to use it as a lookup key for verify_adm later.

To solve the problem, let's add a try/except block around the section
where EF.ICCID is read. In case of failure we set the ICCID to None,

Related: OS#5636
Change-Id: I8d18c5073946c5a6bb1f93be0ce692a599f46f8c
2023-10-20 20:51:24 +00:00
Philipp Maier af4e5bb18c transport: do not catch exceptions in init_reader
We currently catch any exceptions that may occur when the card reader is
initialized. Then we print the exception string or the exception type
when no string is available. However, a failure during the reader
initialization is usually a severe problem, so a traceback would provde
a lot of helpful information to debug the issue. So lets not catch any
exceptions at this level so that we get the full backtrace.

Related: OS#6210
Change-Id: I4c4807576fe63cf71a7d33b243a3f8fea0b7ff23
2023-10-16 14:36:02 +02:00
Philipp Maier 6bfa8a8533 pySim-shell: print device info in case an exception occurs
When an exception occurs while initializing or handling the card we
print a traceback, but we do not print any info that allows us to
identify the device that was involved when the exception occurred. Let's
include the device path or number in the error message before we print
the traceback.

In order to make it easier to print the device information, let's add a
__str__() method to all of our devices. This method shall return the
device number or path.

Related: OS#6210
Change-Id: I200463e692245da40ea6d5b609bfc0ca02d15bdb
2023-10-10 11:51:08 +02:00
Philipp Maier 8e03f2f2ed pySim-shell: do not pass failed card object to PysimApp
When the try block in which we also call init_card() fails, there may be
no card object, so we must not pass the card object to PysimApp in the
except block. This is also no problem, PysimApp will run without the
card object until the user executes do_equip for a second attempt.

Related: OS#6210
Change-Id: I28195f442ce007f05f7610c882bbc4a6520a8ce6
2023-10-10 11:26:56 +02:00
Philipp Maier 91c971bf82 pySim-prog, pySim-shell do not use global variables
When __main__ runs different variables get assigned. In particular opts,
scc, sl and ch. Those variables are available in any scope and
technically it is possible to access them. However, lets not do this
since it leads to confusion. Also, pylint will complain about those code

- Let's use the proper locations (sl and ch are stored in PysimApp.
- Scc can be assigned in init_card.
- In method walk, the use of the variable opts to call ection_df is wrong,
  lets use **kwargs (see also usage of action_ef).
- The constructor of Cmd2ApduTracer has a parameter cmd2_app, but usese
  the global variable app. Let's use cmd2_app instead.

- Do not use opts.num in find_row_in_csv_file, use num instead.
- Pass scc to process_card as parameter so that it won't access scc
  in the global scope.

Change-Id: I7f09e9a6a6bfc658de75e86f7383ce73726f6666
Related: OS#6210
2023-10-09 12:37:47 +02:00
Philipp Maier 4840d4dc8f pySim-shell: fix commandline option -a (verify_adm)
The commandline option -a, which does an ADM verification on startup,
does no longer work since the verify_adm method is no longer available
in the card base classes ( Let's use the verify_chv method
from SimCardCommands instead.

Related: RT#68294
Change-Id: Ic1e54d0e9e722d64b3fbeb044134044d47946f7c
2023-09-06 14:57:55 +02:00
Philipp Maier a42ee6f99d cards: get rid of method read_iccid
The method read_iccid in class CardBase should be put back to
legacy/ The reason for this is that it falls in the same
category like read_imsi, read_ki, etc. We should not use those old
methods in future programs since we have a more modern infrastructure
(lchan) now.

Also is the only caller of this method now. It is not
used in any other place.

Related: RT#67094
Change-Id: Ied3ae6fd107992abcc1b5ea3edb0eb4bdcd2f892
2023-08-21 18:36:10 +00:00
Philipp Maier e6cba76a36 pySim-shell: check presence of runtime state before accessing it
When the command equip (do_equip) is executed, it accesses to see if there are any commands that need to be
unregistered before moving on with the card initialization.

However, it may be the case that no runtime state exists at this point.
This is in particular the case when the card is completely empty and
hence no profile is picked and no runtime state exists.

Change-Id: I0a8be66a69b630f1f2898b62dc752a8eb5275301
2023-08-11 11:28:31 +02:00
Philipp Maier cfb665bb3f pySim-shell: fix verify_adm command
The comman verify_adm does no longer work since the verify_adm method is
no longer available in the card base classes ( Let's use the
verify_chv method from SimCardCommands instead.

Change-Id: Ic87e1bff221b10d33d36da32b589e2737f6ca9cd
2023-07-20 17:36:08 +02:00
Harald Welte 38306dfc04 pySim-shell: Add a mode where a pySim-shell cmd can be passed by shell
This adds a new operation mode for pySim-shell, where a single command
can be passed to pySim-shell, which then is executed before pySim-shell

Example: ./ -p0 export --json

Change-Id: I0ed379b23a4b1126006fd8f9e7ba2ba07fb01ada
Closes: OS#6088
2023-07-12 22:05:14 +02:00
Harald Welte 531894d386 move Runtime{State,Lchan} from pySim.filesystem to new pySim.runtime
Those two are really separate concepts, so let's keep them in separate
source code files.

Change-Id: I9ec54304dd8f4a4cba9487054a8eb8d265c2d340
2023-07-12 22:05:14 +02:00
Harald Welte 6ad9a247ef pySim-shell: Iterate over CardApplication sub-classes
Rather than having to know and explicitly list every CardApplication,
let's iterate over the __subclasses__ of the CardApplication base class.

Change-Id: Ia6918e49d73d80acfaf09506e604d4929d37f1b6
2023-07-12 22:05:14 +02:00
Harald Welte 323a35043f Introduce concept of CardProfileAddon
We have a strict "one CardProfile per card" rule.  For a modern UICC
without legacy SIM support, that works great, as all applications
have AID and ADF and can hence be enumerated/detected that way.

However, in reality there are mostly UICC that have legacy SIM, GSM-R
or even CDMA support, all of which are not proper UICC applications
for historical reasons.

So instead of having hard-coded hacks in various places, let's introduce
the new concept of a CardProfileAddon.  Every profile can have any
number of those.  When building up the RuntimeState, we iterate over the
CardProfile addons, and probe which of those are actually on the card.
For those discovered, we add their files to the filesystem hierarchy.

Change-Id: I5866590b6d48f85eb889c9b1b8ab27936d2378b9
2023-07-12 22:05:14 +02:00
Harald Welte f8d2e2ba08 split pySim/legacy/{cards,utils} from pySim/{cards,utils}
There are some functions / classes which are only needed by the legacy
tools pySim-{read,prog}, bypassing our modern per-file transcoder
classes.  Let's move this code to the pySim/legacy sub-directory,
rendering pySim.legacy.* module names.

The long-term goal is to get rid of those and have all code use the
modern pySim/filesystem classes for reading/decoding/encoding/writing
any kind of data on cards.

Change-Id: Ia8cf831929730c48f90679a83d69049475cc5077
2023-07-12 22:03:59 +02:00
iw0 f818acd5eb pySim-shell: Unregister profile commands during equip
This avoids error messages about re-registering 'AddlShellCommands' commandsets during 'equip()' in the bulk_script command.

Change-Id: I893bb5ae95f5c6e4c2be2d133754e427bc92a33d
2023-07-09 08:12:28 +00:00
Harald Welte f4a01472bf pySim-shell: Support USIM specific methods/commands on unknown UICC
So far, if no known programmable card (like sysmoISIM) has been found,
we were using the SimCard base class.  However, once we detect an UICC,
we should have switched to the UsimCard class, as otherwise the various
methods called by USIM/ISIM specific commands don't exist and we get
weird 'SimCard' object has no attribute 'update_ust' execptions.

The entire auto-detection and the legacy SimCard / UsimCard classes
are showing the legacy of the code base and should probably be
re-architected.  However, let's fix the apparent bug for now.

Change-Id: I5a863198084250458693f060ca10b268a58550a1
Closes: OS#6055
2023-07-04 21:17:19 +02:00
Harald Welte 0ec01504ab cosmetic: Implement cmd2.Settable backwards-compat via wrapper class
Let's avoid too many open-coded if-clauses and simply wrap it in
a compatibility class.

Change-Id: Id234f3fa56fe7eff8e1153d71b9be8a2e88dd112
2023-06-27 09:29:25 +02:00
Harald Welte e126872a29 Fix run-editor bug with cmd2 >= 2.0.0 compatibility
In cmd2, the upstream authors decided to rename a method in 2.0.0
without providing a backwards compatibility wrapper.  Let's add that

Change-Id: Iaa17b93db13ba330551799cce5f0388c78217224
Closes: OS#6071
2023-06-25 08:22:56 +02:00
Philipp Maier e345e1126d pySim-shell: fix reset command
The API of the lchan object has changed. It no longer features the reset
method used by the pySim-shell reset command. Let's fix this by using
the reset method of the card object.

Change-Id: I55511d1edb97e8fa014724598ec173dd47fe25c1
2023-06-11 19:11:37 +00:00
Harald Welte f422eb1886 Add ".py" suffix to sphinx-argparse generated docs
This is important to produce the right command syntax when generating
command line reference in the user manual.  However, we shouldn't add
this kludge to the individual programs, but only to the documentation
using the :prog: syntax.

Change-Id: I2ec7ab00c63d5d386f187e54755c71ffc2dce429
2023-06-09 11:50:18 +02:00
Harald Welte 659781cbe1 Move "suspend_uicc" command from pySim-shell to
The SUSPEND UICC command is a TS 102 221 (UICC) command, so move
it to the UICC Card Profile.

Also, make sure that any shell command sets specified in the
CardProfile are actually installed during equip().

Change-Id: I574348951f06b749aeff986589186110580328bc
2023-06-07 11:10:33 +02:00
Harald Welte 892526ffd0 pySim-shell: Unregister TS 102 222 commands during 'equip'
This avoids error messages about re-registering the same TS 102 222
commands during executing the 'equip' command.

Change-Id: I3567247fe84e928e3ef404c07eff8250ef04dfe9
2023-06-06 17:36:39 +02:00
Harald Welte e619105249 HPSIM application support
Support HPSIM as specified in 3GPP TS 31.104

Change-Id: I2729fd2b88cd13c36d7128753ad8d3e3d08a9b52
2023-06-06 17:36:39 +02:00
Oliver Smith e47ea5f2e5 Fix pylint errors
In a previous patch the dependency on cmd2 was changed from cmd2==1.5 to
cmd2>=1.5. After this was merged, this lead to the docker images getting
rebuilt and now having a higher cmd2 version that gets used in the CI
checks. So while the patch was in review, pylint was actually running
with a lower cmd2 version and was taking different code paths.

Fix for: E0611: No name 'fg' in module 'cmd2' (no-name-in-module) E0611: No name 'bg' in module 'cmd2' (no-name-in-module) E1123: Unexpected keyword argument 'use_ipython' in method call (unexpected-keyword-arg) E1120: No value for argument 'settable_object' in constructor call (no-value-for-parameter) E1120: No value for argument 'settable_object' in constructor call (no-value-for-parameter) E1120: No value for argument 'settable_object' in constructor call (no-value-for-parameter) E1120: No value for argument 'settable_object' in constructor call (no-value-for-parameter)

Fixes: f8a3d2b3 ("requirements.txt: allow cmd2 versions greater than 1.5")
Fixes: OS#6034
Change-Id: I182d3a2b87e70ed551a70c88d3d531a36bf53f53
2023-05-23 13:12:33 +02:00
Harald Welte 961b803ec4 pySim-shell: fix compatibility problem with cmd2 >= 2.3.0 (bg)
cmd2.fg and have been deprecated in cmd2 2.3.0 and removed
in cmd2 2.4.0. Let's work around this by a version check.

Related upstream commits:
(See also:

Commit f57b08672af97f9d973148b6c30d74fe4e712d14
Author: Kevin Van Brunt <>
Date:   Mon Oct 11 15:20:46 2021 -0400


Commit f217861feae45a0a1abb56436e68c5dd859d64c0
Author: Kevin Van Brunt <>
Date:   Wed Feb 16 13:34:13 2022 -0500

Change-Id: I9fd32c0fd8f6d40e00a318602af97c288605e8e5
2023-05-17 17:30:49 +02:00
Harald Welte c85d4067fd pySim-shell: fix compatibility problem with cmd2 >= 2.0.0 (include_ipy)
In version 2.0.0, the use_ipython parameter in the Cmd constructor is
renamed to include_ipy. There are still plenty of older cmd2
installations around, so let's work around this using a version check.

See also:

Commit: 2397280cad072a27a51f5ec1cc64908039d14bd1
Author: Kevin Van Brunt <>
Date: 2021-03-26 18:56:33

This commit is based on pySim gerrit changes:

Change-Id: Ibc0e18b002a03ed17933be4d0b4f4e86ad99c26e
2023-05-17 17:30:49 +02:00
Harald Welte 93aac3abe6 pySim-shell: fix compatibility problem with cmd2 >= 2.0.0 (Settable)
In cmd2 relase 2.0.0 the constructor of Settable adds a settable_object
parameter, which apparantly was optional at first, but then became
mandatory. Older versions must not have the settable_object parameter
but versions from 2.0.0 on require it. Let's add a version check so that
we stay compatible to cmd2 versions below and above 2.0.0.

See also:

Commit 486734e85988d0d0160147b0b44a37759c833e8a
Author: Eric Lin <>
Date:   2020-08-19 20:01:50


Commit 8f981f37eddcccc919329245b85fd44d5975a6a7
Author: Eric Lin <>
Date: 2021-03-16 17:25:34

This commit is based on pySim gerrit change:

Change-Id: I38efe4702277ee092a5542d7d659df08cb0adeff
2023-05-17 17:30:49 +02:00
Vadim Yanitskiy 87dd020d5f Add very basic profile for R-UIM (CDMA) cards
R-UIM (CDMA) cards are pretty much like the normal GSM SIM cards and
"speak" the same 2G APDU protocol, except that they have their own file
hierarchy under MF(3f00)/DF.CDMA(7f25).  They also have DF.TELECOM(7f10)
and even DF.GSM(7f20) with a limited subset of active EFs.  The content
of DF.CDMA is specified in 3GPP2 C.S0023-D.

This patch adds a very limited card profile for R-UIM, including auto-
detecion and a few EF definitions under DF.CDMA.  This may be useful
for people willing to explore or backup their R-UIMs.  To me this was
useful for playing with an R-UIM card from Skylink [1] - a Russian
MNO, which provided 450 MHz CDMA coverage until 2016.


Change-Id: Iacdebdbc514d1cd1910d173d81edd28578ec436a
2023-05-10 00:14:13 +00:00
Philipp Maier 7b9e24482d pySim-shell: add cardinfo command
It may sometimes be helpful to get a bit of general information about
the card. To sort out problems it sometimes helps to get an idea what
card type and ICCID pySim-shell has in memory.

Change-Id: If31ed17102dc0108e27a5eb0344aabaaf19b19f9
2023-03-27 10:37:28 +02:00
Harald Welte cab26c728c pySim-shell: Use definitions to print decoded proactive cmds
Register a ProactiveHandler with pySim.transport and call the decoder
from to print a decoded version:

Example usage (exact data only works on my specific card due to the
encrpyted payload):

pySIM-shell (MF/ADF.USIM)> envelope_sms 400881214365877ff6227052000000000302700000201506393535b000118dd46f4ad6b015922f62292350d60af4af191adcbbc35cf4
FETCH: d0378103011300820281838b2c410008812143658700f621027100001c12b000119660ebdb81be189b5e4389e9e7ab2bc0954f963ad869ed7c
SendShortMessage(CommandDetails({'command_number': 1, 'type_of_command': 19, 'command_qualifier': 0}),DeviceIdentities({'source_dev_id': 'uicc', 'dest_dev_id': 'network'}),SMS_TPDU({'tpdu': '410008812143658700f621027100001c12b000119660ebdb81be189b5e4389e9e7ab2bc0954f963ad869ed7c'}))
SW: 9000, data: d0378103011300820281838b2c410008812143658700f621027100001c12b000119660ebdb81be189b5e4389e9e7ab2bc0954f963ad869ed7c

Change-Id: Ia4cdf06a44f46184d0da318bdf67077bc8ac9a1a
2022-08-06 18:56:42 +02:00
Harald Welte fc31548c11 pySim-shell: Add a "version" command to print the pySim package version
It may be interesting to know which pySim-shell version a user is running.

Change-Id: Ib9a1fbff71aa8a2cfbaca9e23efcf7c68bf5af1a
Closes: OS#5459
2022-07-23 12:49:14 +02:00
Harald Welte b2e4b4a300 introduce fully_qualified_path_str() method
Reduce all the copy+pasted '/'.join(path_list) constructs with
a method returning the formatted path string.

Change-Id: I5e9bfb425c3a3fade13ca4ccd2b891a0c21ed56d
2022-07-20 19:35:58 +02:00
Harald Welte a6c0f880da filesystem: Introduce the basic notion of 'logical channels'
cards can have multiple logical channels; each logical channel
has its own state of what is the current selected file + application.

Let's split the RuntimeState class into the global RuntimeState and the
per-lchan-specific RuntimeLchan class.

This code doesn't actually introduce any code that uses lchans other
than the basic logical channel (0), but just modifies the data model
to accomodate those in the future.

Change-Id: I7aa994b625467d4e46a2edd8123240b930305360
2022-07-17 21:55:15 +02:00
Harald Welte 1e52b0d3b7 pySim-shell: Remove unused imports
Those might have been used some time ago, but they are not.

Change-Id: I00f096fc8049c0aebc1127f9a1725638d973af0e
2022-07-16 11:53:21 +02:00
Vadim Yanitskiy 0d9f088853 remove unused imports of 'bg' from 'cmd2'
Change-Id: Ic2a73a98f322be391e54215bc5fc3358776da0ae
2022-07-14 19:11:25 +07:00