Commit Graph

355 Commits

Author SHA1 Message Date
Harald Welte 9813dc958b Introduce setuptools support
Add a pyproject.toml and setup.py for using setuptools to install
pySim and its upstream dependencies.

Change-Id: I5698f3b29184340db69a156f985aa3c78d9b5674
2021-04-04 10:54:46 +02:00
Harald Welte 4f2c546613 transport: Pass status word interpreter to exception handler
Prior to this patch, any SwMatchError raised within the 'transport'
would not be interpreted.

EXCEPTION of type 'SwMatchError' occurred with message: 'SW match failed! Expected 9000 and got 6982.'

vs (now)

EXCEPTION of type 'SwMatchError' occurred with message: 'SW match failed! Expected 9000 and got 6982: Command not allowed - Security status not satisfied'

Change-Id: I08b7f2b6bd422f7f2f36094bc8a29b187ff882a6
2021-04-04 10:54:46 +02:00
Harald Welte be9516f157 docs: Initial documentation for pySim-shell
Many bits and pieces are still missing, but it's better than nothing...

Change-Id: I19fd56aed251d064f3e5d37ffad39c1e3e39989e
2021-04-04 10:54:46 +02:00
Harald Welte 31d2cf0642 shell: Move dir,tree,export from ISO7816 to pySim commands
pySim has the notion of command categories.  The ISO7816 category
should only contain commands such as SELECT or CHV management
which really is ISO7816.  Custom commands like 'tree' or 'export'
are pySim specific and hence go into a different category.

Change-Id: Id38c8190c6279d037fe266c586065f1507a02932
2021-04-04 10:54:46 +02:00
Harald Welte 522555710b utils.py: Add more type annotations
Change-Id: I50a0a07132890af0817f4ff0ce9fec53b7512522
2021-04-04 10:53:36 +02:00
Harald Welte 6e0458dda6 Move init_reader() from utils.py to transport/__init__.py
This avoids a circular dependency when introducing type annotations.

Change-Id: I168597ac14497fb188a15cb632f32452128bc1c6
2021-04-04 10:53:36 +02:00
Harald Welte 9d0f1f0cd5 card_key_provider: Documentation with sphinx / autodoc
* move existing docs to sphinx / autodoc
* add more api documentation
* improve wording on some exception strings

Change-Id: Ia41e14d643d452d92fc8d3c2fb9c4ac9021402e9
2021-04-04 10:52:34 +02:00
Harald Welte 4442b3d1c0 rename card_data to card_key_provider.
"data" is an awfully generic term.  Anything stored on a card is data.

This specific code deals with resolving key/pin material from an
external source.

Change-Id: I4c8e1be3e766f7c0565c07b39d48abf8adc375af
2021-04-04 10:36:00 +02:00
Harald Welte 90d3b970af Add type annotations and more documentation to card_data.py
Change-Id: Ia09b3ecaa582d62a97c3adac2650686dc19d5ec1
2021-04-04 10:35:18 +02:00
Harald Welte 2d4a64b43d filesystem.py: Fix type annotation of read_binary_dec()
Change-Id: I781fc0c564a318a6f9b2ec8dccf9f8865bff0e48
2021-04-03 20:34:37 +00:00
Harald Welte 236a65f02f cosmetic: fix typo in comment
Change-Id: Iac8b310a470b3ad8dee5f61342fd5acedbbd6e5d
2021-04-03 20:33:31 +00:00
Harald Welte b29df886fc docs: Update copyright statement
* list supreeth for his many contributions
* update copyright years

Change-Id: I431e54000e6d260d8173424496d11904599171d8
2021-04-03 20:14:43 +00:00
Harald Welte 5da7a72c99 jenkins.sh: Build documentation as part of build verification
Change-Id: Iea7547c81fcd3e4268da23c18ad56d841aaf7535
2021-04-03 19:58:43 +00:00
Harald Welte 86fbd39738 filesystem: Fix interpret_sw() fall-through
if an application-specific interpret_sw() fails, fall back to the
profile interpret_sw().

Change-Id: I326c6002c75e2f906848784b7831ea169134dbe4
2021-04-02 21:08:30 +00:00
Harald Welte ec7d0daf6e 51.011: Define some more files within DF_TELECOM
Add some more minimal definitions for various DF_TELECOM files

Change-Id: I155729b4d62969cde2af00fc9fb9901299fe5c25
2021-04-02 22:05:28 +02:00
Harald Welte 89e5954773 fix various file definitions
As we can notice during 'export': Some files had been defined
as LinFixed but are Transparent - and vice versa.  Let's fix those
an bring our definitions in sync with the specs.

Change-Id: I365ece7b82a1c79b3af87a79ff964d7989362789
2021-04-02 22:05:28 +02:00
Harald Welte aae7c2768e pySim-shell: Remove UsimCommands
Those are a leftover of a very early attempt at pySim-shell, it has
long been superseded by all of the filesystem.py infrastructure.

Change-Id: I6b84ce205f46a1efd19087d332920982f17ca9cc
2021-04-02 21:25:23 +02:00
Harald Welte 5ce3524f5f Fix various mistakes around the CardADF <-> CardApplication dualism
When the CardFile hierarchy talks about 'application' it means CardADF.

When the RuntimeState and CardProfile talk about 'application' they mean
a CardApplication.

Let's clarify this in the file names, and make CardADF have an optional
reference to the CardApplication, so that application specific status
word interpretation really works.

Change-Id: Ibc80a41d79dca547f14d5d84f447742e6b46d7ca
2021-04-02 21:09:42 +02:00
Harald Welte 1e45657e0f filesystem: fix various issues found by mypy
Change-Id: Ib4de80451614712bdf5377a3a5b86156008e2c42
2021-04-02 21:09:40 +02:00
Harald Welte 5a4fd52986 filesystem: Avoid GPL header showing up in sphinx autodoc
Change-Id: I1d963ae3d1511ef40d1ebcb36b0f67c40cbd6309
2021-04-02 21:09:02 +02:00
Harald Welte 94e8735bd3 Use sphinx for generating documentation
This adds sphinx based documentation generation.  For now,
this manily renders some introduction and the autodoc-genreated
class/method reference from the source code for our libraries.

Actual user-level documentation for pySim-{prog,shell,read} remains
to be added separately

Change-Id: I52603e93c2c129a9e79687da6c534fa56a40a649
2021-04-02 21:08:51 +02:00
Harald Welte ee3501fc62 Add more documentation to the classes/methods
* add type annotations in-line with PEP484
* convert existing documentation to follow the
  "Google Python Style Guide" format understood by
  the sphinx.ext.napoleon' extension
* add much more documentation all over the code base

Change-Id: I6ac88e0662cf3c56ae32d86d50b18a8b4150571a
2021-04-02 21:08:35 +02:00
Harald Welte 082d4e0956 ts_31_102: Fix decode_select_response() for DF.5GS
In Change-Id I848a766e6d00be497c7db905475e0681cce197ac we added a CardDF
instance for DF_5GS.  That DF should not have provided a
decode_select_response() method, and instead fall back to that of the
base class, which calls the method of the parent directory (ADF_USIM).

The difference is illustrated below

pySIM-shell (MF/ADF.USIM/EF.IMSI)> select DF.5GS
"622e8202782183025fc0a509800171830400018d088a01058c056611111111c60f90017083010183018183010a83010b"

vs. (with this patch):

pySIM-shell (MF/ADF.USIM)> select DF.5GS
{
    "file_descriptor": {
        "shareable": true,
        "file_type": "df",
        "structure": "no_info_given"
    },
    "file_identifier": "5FC0",
    "proprietary_info": {
        "uicc_characteristics": "71",
        "available_memory": 101640
    },
    "life_cycle_status_int": "operational_activated",
    "security_attrib_compact": "6611111111",
    "pin_status_template_do": "90017083010183018183010A83010B"
}

Change-Id: I80612711bbc8c47285a828a0759b20beea6619f1
2021-04-02 21:01:39 +02:00
Philipp Maier ac34dcc149 pySim-shell: fix and improve file system exporter
The file system exporter function export() selects the exported EF from
inside a try block. It also selects the parent DF again when leaving the
try block. If an exception ocurrs during select this is fine, but if it
happens during read it leaves the EF selected which makes messes up the
recursive filesystem walk.

There are also minor inconsistancies with the exception strings and the
path displayed in the execption strings

Related: OS#4963
Change-Id: Ie9b1712b37e5b39e9016497185510a2a45c4ca6c
2021-04-02 16:32:53 +02:00
Philipp Maier b152a9e0ed pySim-shell: prevent inconsitancy when walking through the FS tree
When using the method walk() to walk through the filesystem tree, then
the action() callback must not change the currently selected file.
Unfortunately this can easily happen and result in unpredictable
behavior. Lets add a check + an exeception for this to make debugging
easier.

Change-Id: I6778faa87bdf5552da74659206bf7a6fc0348d0c
Related: OS#4963
2021-04-02 16:32:53 +02:00
Philipp Maier 46f09af11d pySim-shell: complete CHV/PIN management tools
At the moment we only have a basic version of a verify_chv commnad, but
in order to handle any CHV/PIN related situation we also need commands
to enable, disable, change and unblock CHV.

- fix verify_chv commnad: more distinct parameter names, better help
  strings, correct pin code encoding and add external source lookup
- Add unblock_chv, change_chv, enable_chv and disable_chv commands
- add/fix related functions in commands.py

Change-Id: Ic89446e6bd2021095e579fb6b20458df48ba6413
Related: OS#4963
2021-04-02 16:32:53 +02:00
Philipp Maier b63766b96b pySim-shell: be more specific when finding no ADM-PIN
When no ADM pin is found in the external data source, then print an
error message that tells the user that this is the case.

Change-Id: If8f88b43f283fbe459be1b30db35d984022840ac
Related: OS#4963
2021-04-02 16:21:14 +02:00
Philipp Maier 38c74f6d41 commands: conserve write cycles
When a record or a binary file is written the card goes throth a full
flash/eeprom write cycle at this location, even when the data does not
change. This can be optimized by reading before writing in order to
compere if the data we are about to write is actually different.

Change-Id: Ifd1b80d3ede15a7caa29077a37ac7cf58c9053f1
Related: OS#4963
2021-04-02 16:21:14 +02:00
Philipp Maier 2b11c32e20 pySim-shell: automatic ADM pin from CSV-File
It can be hard to manage ADM pins when working with different cards at
the same time. To make this easier, add an automatic way to determine
the ADM pin for each card from a CSV file.

- add a CardData clas model that can be extended to to get the data from
  various different sources. For now use CSV-Files. Also add a way how
  multiple CardData classes can be registered so that one global get
  function can query all registered CardData classes at once.

- automatically check for CSV-File in home directory and use it as
  default CardData source unless the user specifies a CSV file via
  commandline argument.

- extend the verify_adm command so that it automatically queries the
  ADM pin if no argument is given. Also do not try to authenticate if
  no ADM pin could be determined.

Change-Id: I51835ccb16bcbce35e7f3765e8927a4451509e77
Related: OS#4963
2021-04-02 16:21:14 +02:00
Philipp Maier cba6dbce9a fileystem: fix ADF selection
When the ADF is selected, then this is done by the AID. At the moment
only the first 7 bytes of the AID are used to select the ADF.
sysmo-isim-sja2 tolerates this, but sysmo-usim-sjs1 does not. The Cards
class already has methods to deal with this problem. The method
select_adf_by_aid takes an ADF name and completes the AID from an
internal list. This can be extended to support partial hexadecimal AIDs
as well.

Change-Id: If99b143ae5ff42a889c52e8023084692e709e1b1
Related: OS#4963
2021-04-02 16:21:14 +02:00
Philipp Maier ad073e834a ts_31_102: do not add empty ShellCommands class.
The class ShellCommands defined in ADF_USIM overloads useful CommandSet
classes defined in the superclass, making their commands inaccessible.
Also ts_31_102 does not have such a class definition in the ADF_ISIM
class, so lets remove this class.

Change-Id: I0e67c570fc4f17641d990a9cd239632ecf622de3
Related: OS#4963
2021-04-02 16:21:14 +02:00
Philipp Maier 63f572df42 filesystem: allow selection of arbitrary files
Some cards may have additional propritary EF files which pySim-shell
does not support. If the user knows the exact FID the file can still be
selected and it is possible to read the file type and memory model from
the select response. This info can be used to create a new file object
at runtime that will work like any other EF/DF.

Change-Id: Iafff97443130f8bb8c5bc68f51d2fe1d93fff07c
Related: OS#4963
2021-04-02 16:21:11 +02:00
Merlin Chlosta 05ca36b3f3 Add decoder/encoder for EF.SUCI_Calc_Info
Change-Id: I848a766e6d00be497c7db905475e0681cce197ac
2021-04-02 14:10:10 +02:00
Philipp Maier dd2091a3e0 ts_102_221: use keywords to avoid conflicts with positional args
The Change I83d718ff9c3ff6aef47930f38d7f50424f9b880f removes the
keyword arguments from the CardProfile class constructor. This requires
us to use the keywords during instantiation since we can not rely on
the position anymore.

Change-Id: Ia62597c59287848662dbbedcc38ba90f183c4aca
2021-03-31 17:33:04 +02:00
Philipp Maier 228c98e4c6 pySim-shell: use -a / -A commandline option to authenticate
pySim-shell defines, just like the other pySim programs commandline
arguments that take an ADM pin to authenticate at the card as admin. The
arguments are defined, but not used. Add the missing authentication
part.

Change-Id: I6bed14eb8f4124e28d593cf0816dbe58e7271322
Related: OS#4963
2021-03-30 11:58:39 +02:00
Philipp Maier e6bc4f9032 filesystem: avoid outputting empty lines when there is no data
The do_update_... functions do always print the returned data. However,
there may be no data. If this is the case than an empty line is printed.
This may cause ugly log output, especially when working with scripts.

Change-Id: Ia9715d46ec957544cfbeea98d2fe15eb74f5b884
Related: OS#4963
2021-03-30 11:58:39 +02:00
Philipp Maier 2558aa6999 pySim-shell: add command to show file description
All all files (CardFile) have a human readable description but there is
no command to display that description yet

Change-Id: If716cf3c6b09d53dca652b588671487d5343cf58
Related: OS#4963
2021-03-27 18:37:39 +00:00
Vadim Yanitskiy 98f872bed1 pySim/filesystem: fix mutable default list/dict arguments
Having lists and dictionaries as default argument values is a bad
idea, because the same instance of list/dict will be used by all
objects instantiated using such constructor:

  def appendItem(itemName, itemList=[]):
      itemList.append(itemName)
      return itemList

  print(appendItem('notebook'))
  print(appendItem('pencil'))
  print(appendItem('eraser'))

Output:

  ['notebook']
  ['notebook', 'pencil']
  ['notebook', 'pencil', 'eraser']

Change-Id: I83d718ff9c3ff6aef47930f38d7f50424f9b880f
2021-03-27 18:28:43 +00:00
Philipp Maier 24f7bd3ab5 pySim-shell: add filesystem exporter
add a new command "export" that can either export indidividual files or
a whole directory tree. The command will generate a script that contains
update_binary and update_record commands along with the file contents.
This script can later be used to restore multiple files at once.

Change-Id: I82f3ce92cd91a5ed3c4884d62f6b22e9589c8a49
Related: OS#4963
2021-03-26 22:11:40 +01:00
Philipp Maier f62866f4d3 pySim-shell: output currently selected file using select command
When the select command is entered with no parameters it fails with an
exception. Lets just output the currently selected file and exit
instead.

Change-Id: I541bd5ed14f240cd1c2bd63647c830f669d26130
Related: OS#4963
2021-03-26 22:11:40 +01:00
Philipp Maier 681bc7ba72 pySim-shell: add option to execute script on startup
Add a commondline option so that the user can supply pySim-shell with a
script file name. This script then runs automatically on startup. (to
avoid ending up at the shell prompt a quit command at the end can be
used to exit after script execution)

Change-Id: I69f5224087023650340fbfee74668e1850345f54
Related: OS#4963
2021-03-26 22:11:40 +01:00
Philipp Maier 1e896f3d8c pySim-shell: add ADF.ISIM / ADF.USIM dynamically
currently ADF.ISIM and ADF.USIM are always added regardless if there is
a matching application on the card or not. Lets check what applications
are actually installed and add ADF.ISIM and ADF.USIM dynamically.

Change-Id: I42ee23375f98e6322708c1c4db6d65e1425feecd
Related: OS#4963
2021-03-26 22:11:40 +01:00
Philipp Maier eb72fa461d filesystem: fix typo in method call app()->append()
In the method add_application() the method name should be append()
instead of add().

Change-Id: Ic8ad62567968e09786eac86f219b56a3d3200511
Related: OS#4963
2021-03-26 22:05:04 +01:00
Philipp Maier 9c1a4ece3d pysim-shell: select MF on startup to make commands accessible
On the cration of the PysimApp object only the basic commands in
pySim-shell.py are registered, since the MF is only created but not
selected, the file specific commands of the MF are not available. To
make them available, select the MF once on startup before entering the
cmdloop.

Change-Id: Ib63191f44e7c8ae07b0128a9affba40b44957adc
Related: OS#4963
2021-03-23 15:45:22 +01:00
Philipp Maier 78e32f2b36 utils: fix sw_match()
The SW_match function takes a given status word and compares it against
a pattern that may contain wildcards (x or ?). This works by creating a
masked version of the SW using a pattern first (each hex digit is
replaced by a wildcard charafter if the pattern has a wildcard in the
same position). Once this is done, the resulting masked version is
compared at the pattern. However, the current implementation can not
work, since it compares the input SW against the pattern to decide
wihich chrafters should be masked. The input SW never contains wildcard
charafters.

Change-Id: I805ad32160fcfcb8628bf919b64f7eee0fe03c7e
Related: OS#4963
2021-03-23 12:17:23 +00:00
Philipp Maier 05f42ee929 cards: remove unnecessary execptions.
The _scc.veryif_adm() method already does status word checking
internally and also raises an execption should the authentication be
unsuccessful, so we do not have to put an additional status word check +
execition when we use the method from cards.

Change-Id: I785d27e4d49a9cda1a771b56ce5ac9c1f1d1e79a
Related: OS#4963
2021-03-23 11:54:47 +00:00
Philipp Maier a31e9a9a68 commands: better exception string for authentication failures
At the moment we use the send_apdu_checksw() method to send the APDU for
ADM authentication. This method only checks if the command returns with
sw = 9000. If not it raises an exception that the sw is not as expected.
The user may think that this is a problem with thr reader, pcscd or
pySim in the first place and may try multiple times until the card is
permanently locked. A better execption string that also displays the
tries which are left may be helpful.

Change-Id: Icf428831094f8c1045eefaa8cb2b92e6a36b0c13
Related: OS#4963
2021-03-23 11:54:47 +00:00
Philipp Maier 3aec871978 filesystem: be more strict in method add_file()
The file identifier of a file is strictly defined as a two digit
hexadecimal number. Do not allow adding child files that violate this
constraint.

Change-Id: I096907285b742e611d221b03ba067ea2522e7e52
Related: OS#4963
2021-03-22 22:29:49 +01:00
Philipp Maier d51d8b5575 filesystem: drop __main__ from filesystem.py
The __main__ function in filesystem.py seems to be some experimental
testcode from the very beginning of pySim-shell. Lets drop it.

Change-Id: I34f459469dfc45711ad0928c83184d7f99e0f5e3
Related: OS#4963
2021-03-19 17:48:49 +01:00
Philipp Maier 660615800c filesystem: add comment to inform about checks in add_file()
The method add_file of class CardDF does some constraint checking
to the basic file parameters (e.g. fid). Since one might also expect
those checks in the superclass CardFile lets leave a comment to make
the code better understandable.

Change-Id: Iebae28909fe6aade3bd4024112a222819572d735
Related: OS#4963
2021-03-19 17:48:49 +01:00