laforge has uploaded this change for review. ( https://gerrit.osmocom.org/c/pysim/+/38939?usp=email )

Change subject: docs: Add documentation about contrib/sim-reset-{server,client} ......................................................................

docs: Add documentation about contrib/sim-reset-{server,client}

Those programs have been around since 2021 but we never had any documentation here. Let's fix that.

Change-Id: I7c471cac9500db063a0c8f5c5eb7b6861b3234ed --- M docs/index.rst A docs/sim-rest.rst 2 files changed, 119 insertions(+), 0 deletions(-)

git pull ssh://gerrit.osmocom.org:29418/pysim refs/changes/39/38939/1

diff --git a/docs/index.rst b/docs/index.rst index bcbc7f0..228fb79 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -43,6 +43,7 @@ legacy library osmo-smdpp + sim-rest

Indices and tables diff --git a/docs/sim-rest.rst b/docs/sim-rest.rst new file mode 100644 index 0000000..41a6d1d --- /dev/null +++ b/docs/sim-rest.rst @@ -0,0 +1,118 @@ +sim-rest-server +=============== + +Sometimes there are use cases where a [remote] application will need +access to a USIM for authentication purposes. This is, for example, in +case an IMS test client needs to perform USIM based authentication +against an IMS core. + +The pysim repository contains two programs: `sim-rest-server.py` and +`sim-rest-client.py` that implement a simple approach to achieve the +above: + +`sim-rest-server.py` speaks to a [usually local] USIM via the PC/SC +API and provides a high-level REST API towards [local or remote] +applications that wish to perform UMTS AKA using the USIM. + +`sim-rest-client.py` implements a small example client program to +illustrate how the REST API provided by `sim-rest-server.py` can be +used. + +REST API Calls +-------------- + +POST /sim-auth-api/v1/slot/SLOT_NR +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +where SLOT_NR is the integer-encoded slot number (corresponds to PC/SC +reader number). When using a single sysmoOCTSIM board, this is in the range of 0..7 + +Example: `/sim-auth-api/v1/slot/0` for the first slot. + +Request Body +############ + +The request body is a JSON document, comprising of + 1. the RAND and AUTN parameters as hex-encoded string + 2. the application against which to authenticate (USIM, ISIM) + +Example: +:: + + { + "rand": "bb685a4b2fc4d697b9d6a129dd09a091", + "autn": "eea7906f8210000004faf4a7df279b56" + } + +HTTP Status Codes +################# + +HTTP status codes are used to represent errors within the REST server +and the SIM reader hardware. They are not used to communicate protocol +level errors reported by the SIM Card. An unsuccessful authentication +will hence have a `200 OK` HTTP Status code and then encode the SIM +specific error information in the Response Body. + +====== =========== ================================ +Status Code Description +------ ----------- -------------------------------- +200 OK Successful execution +400 Bad Request Request body is malformed +404 Not Found Specified SIM Slot doesn't exist +410 Gone No SIM card inserted in slot +====== =========== ================================ + +Response Body +############# + +The response body is a JSON document, either + +#. a successful outcome; encoding RES, CK, IK as hex-encoded string +#. a sync failure; encoding AUTS as hex-encoded string +#. errors + #. authentication error (incorrect MAC) + #. authentication error (security context not supported) + #. key freshness failure + #. unspecified card error + +Example (succcess): +:: + + { + "successful_3g_authentication": { + "res": "b15379540ec93985", + "ck": "713fde72c28cbd282a4cd4565f3d6381", + "ik": "2e641727c95781f1020d319a0594f31a", + "kc": "771a2c995172ac42" + } + } + +Example (re-sync case): +:: + + { + "synchronisation_failure": { + "auts": "dc2a591fe072c92d7c46ecfe97e5" + } + } + +Concrete example using the included sysmoISIM-SJA2 +-------------------------------------------------- + +This was tested using SIMs ending in IMSI numbers 45890...45899 + +The following command were executed successfully: + +Slot 0 +:: + + $ /usr/local/src/pysim/contrib/sim-rest-client.py -c 1 -n 0 -k 841EAD87BC9D974ECA1C167409357601 -o 3211CACDD64F51C3FD3013ECD9A582A0 + -> {'rand': 'fb195c7873b20affa278887920b9dd57', 'autn': 'd420895a6aa2000089cd016f8d8ae67c'} + <- {'successful_3g_authentication': {'res': '131004db2ff1ce8e', 'ck': 'd42eb5aa085307903271b2422b698bad', 'ik': '485f81e6fd957fe3cad374adf12fe1ca', 'kc': '64d3f2a32f801214'}} + +Slot 1 +:: + + $ /usr/local/src/pysim/contrib/sim-rest-client.py -c 1 -n 1 -k 5C2CE9633FF9B502B519A4EACD16D9DF -o 9834D619E71A02CD76F00CC7AA34FB32 + -> {'rand': '433dc5553db95588f1d8b93870930b66', 'autn': '126bafdcbe9e00000026a208da61075d'} + <- {'successful_3g_authentication': {'res': '026d7ac42d379207', 'ck': '83a90ba331f47a95c27a550b174c4a1f', 'ik': '31e1d10329ffaf0ca1684a1bf0b0a14a', 'kc': 'd15ac5b0fff73ecc'}}