examples.md

Practical examples

The REST API is complex interface that is difficult to operate out of the box without any prior familiarization. To give a system integrator a good starting point, the contrib directory contains "tryme-scripts" that serve as examples and an easy way try out the REST API.

Scripts

There is a tryme script to create downloads (tryme_download.sh) and one tryme script per PSMO/eCO. The scripts are called with a one letter parameter that refers to a profile that is pre-configured in tryme.cfg (see below). To get an overview which profiles are available/preconfigured, a "tryme_*.sh" script may be called without parameters.

It should be noted that the tryme_*.sh scripts are really just simple examples that were created to simplify testing during development.

restop.py

The python-script "restop.py" is called by the tryme "tryme_*.sh" scripts. This script can be used as a stand-alone tool to operate the REST API. The intended usecase of "restop.py" is to offer an easy access to the REST API for testing and development. It should be noted that this tool can not replace a proper eUICC management backend. A REST API user must keep track of the REST resources he created, monitor them, check for errors, delete REST resources, resubmit REST resources in case an order has failed, etc.

tryme.cfg

This is just a simple shellscript that sets some initial variables. Some sample values are already present. It is recommended to edit tryme.cfg and to replace the sample values with some useful values. This is in particular the $EID variable at the top of the file.

The file also defines some sample profiles along with their activation codes ($AC) and ICCIDs ($ICCID). The ICCID is usually not known in advance. It becomes known after the eUICC has decrypted and installed the profile package. It should also be noted that the ICCID parameter is always issued in its raw format (digits swapped, padded with 'F' at the end).

In tryme.cfg one will also find a profile X, this profile is a placeholder in case the user decides not to edit tryme.cfg and to pass all parameters from the commandline instead.

Downloading And Enabling A Profile

In the following we will discuss how a profile download is triggered and how the results should look like. In the following example we will pass all parameters directly from the commandline. It is assumed that the REST API of onomondo-eim is available at 127.0.0.1:8080.

In the first step we will issue a download order using the tryme_download.sh. The parameter X tells tryme.cfg to use the placeholder profile. The second parameter is the EID (not to be confused with ICCID) of the eUICC. The third parameter serves as a placeholder for the ICCID, which we do not know or need yet. The last parameter is the activationCode.

./tryme_download.sh X 12345678900000000000000000001234 NOT_NEEDED '1$rsp.example.com$EXAMPLE'

When the script is executed, it will create the related REST resource and then lookup the REST resource periodically. As soon as the IPAd fetches the eIM package with the ProfileDownloadTriggerRequest we should see the status change from new to work and when the download is done, the status should change again to done.

When the profile download was successful, the JSON output should look like this:

{"status": "done", "timestamp": "1718710695", "resource": {"eidValue": "12345678900000000000000000001234", "order": {"download": {"activationCode": "1$rsp.example.com$EXAMPLE"}}}, "outcome": [{"profileInstallationResult": {"finalResult": "successResult", "iccid": "12324567899999911191"}}], "debuginfo": "1234...ABCD..."}

The profile download was successful in case the outcome shows a successResult along with the iccid value. This then means that the profile is successfully installed and that we may abort the tryme_download.sh script now. (to keep the rest table clean one should delete the rest resource now as described above)

However, the profile is not enabled yet. In order to use it, we must issue an enable PSMO first. To do that we may run tryme_enable.sh. The parameter X tells tryme.cfg to use the placeholder profile again. The second parameter is the EID and the third parameter is the ICCID that we have just taken from the JSON output above.

./tryme_enable.sh X 12345678900000000000000000001234 12324567899999911191

We now must wait again until the IPAd fetches the related eIM package with the eUICC package that contains the enable PSMO. When the status reaches done, we should see the following JSON output:

{"status": "done", "timestamp": "1718710734", "resource": {"eidValue": "12345678900000000000000000001234", "order": {"psmo": [{"enable": {"iccid": "12324567899999911191", "rollback": false}}]}}, "outcome": [{"enableResult": "ok"}], "debuginfo": "1234...ABCD..."}

The enableResult in the outcome shows ok. This means that everything went well and the profile is now enabled.

Getting a List with Installed Profiles

The PSMO listProfileInfo (see also GSMA SGP.32, section 5.13.4) allows the REST API user to get a list of all currently installed profiles, including their ICCIDs. This info is in particular valuable in case the API user must synchronize its local records with the actual situation on the eUICC.

To send a listProfileInfo run:

./tryme_listProfileInfo.sh X 12345678900000000000000000001234

As soon as the IPAd has fetched and executed the related eUICC package, the JSON output should look like this:

{"status": "done", "timestamp": "1721306238", "resource": {"eidValue": "12345678900000000000000000001234", "order": {"psmo": [{"listProfileInfo": {}}]}}, "outcome": [{"listProfileInfoResult": {"finalResult": "successResult", "profileInfoList": [{"iccid": "989444999999990920F3", "isdpAid": "A0000005591010FFFFFFFF8900001000", "profileState": "enabled", "serviceProviderName": "OsmocomSPN", "profileName": "TS48V1-A-UNIQUE", "profileClass": "operational"}, {"iccid": "989444999999990930F1", "isdpAid": "A0000005591010FFFFFFFF8900001100", "profileState": "disabled", "serviceProviderName": "OsmocomSPN", "profileName": "TS48V1-B-UNIQUE-nojavacard-nocsim", "profileClass": "operational"}]}}], "debuginfo": "1234...ABCD..."}

We can see that there are two profile installed 989444999999990920F3 and 989444999999990930F1. We also can see that 989444999999990920F3 is currently enabled.

Performing an eUICC Data Request

The eUICC data Request is a special operation, that allows the eIM to request some important master data from the eUICC. (see also GSMA SGP.32, section 2.11.1.2) This includes the EUM and the eUICC certificate that is required to authenticate eCO and PSMO responses. The order takes a tagList as input, which describes what kind of data to request. The exact meaning of the tags can be found in the aforementioned spec reference.

To perform an eUICC data request, execute the following script like so:

./tryme_euiccDataRequest.sh X 12345678900000000000000000001234

There should be response like this:

{"status": "done", "timestamp": "1721307295", "resource": {"eidValue": "12345678900000000000000000001234", "order": {"edr": {"tagList": "80BF20BF228384A5A688A9BF2B"}}}, "outcome": [{"euiccDataResult": {"edrResult": "ok", "euiccData": {"euiccInfo1": "BF20618203020500A92C0414F54172BDF98A95D65CBEB88A38A1C11D800A85C30414C0BC70BA36929D43B467FF57570530E57AB8FCD8AA2C0414F54172BDF98A95D65CBEB88A38A1C11D800A85C30414C0BC70BA36929D43B467FF57570530E57AB8FCD8", "associationToken": 1, "eumCertificate": "308202783082021FA003020102020412345678300A06082A8648CE3D04030230443110300E06035504030C07546573742043493111300F060355040B0C0854455354434552543110300E060355040A0C0752535054455354310B30090603550406130249543020170D3230303430313039323833375A180F32303534303332343039323833375A3037310B300906035504061302455331153013060355040A0C0C52535020546573742045554D3111300F06035504030C0845554D20546573743059301306072A8648CE3D020106082A8648CE3D030107034200041330D59256AC0CB50BD928D0F4C68007C485FE3F42988AD3EE3875AE33F4983AB23B4DD4C31340D676DD8E11F9C5CBA1B11EB694EED0994DB529285E632C8906A382010830820104301F0603551D23041830168014F54172BDF98A95D65CBEB88A38A1C11D800A85C3301D0603551D0E04160414DD3DA24D350C1CC5D0AF0965F40EC34C5EE409F1300E0603551D0F0101FF04040302020430170603551D200101FF040D300B3009060767811201020102300E0603551D1104073005880388370530120603551D130101FF040830060101FF02010030350603551D1F042E302C302AA028A0268624687474703A2F2F63692E746573742E6578616D706C652E636F6D2F43524C2D422E63726C303E0603551D1E0101FF04343032A030302EA42C302A31153013060355040A0C0C52535020546573742045554D3111300F060355040513083839303439303332300A06082A8648CE3D040302034700304402200C567BF01E45244863AD7A4613F7572EEF3439F698B4711AA397AEEFC5445CE702206E993AA0A505F260B0EEF62CC30A2BBE453B0E8248218FD53304EF7F9074EE10", "euiccCertificate": "30820217308201BDA0030201020209020000000000000001300A06082A8648CE3D0403023037310B300906035504061302455331153013060355040A0C0C52535020546573742045554D3111300F06035504030C0845554D20546573743020170D3234303530313133313733305A180F37353030303232333133313733305A307C310B3009060355040613024445311E301C060355040A0C157379736D6F636F6D2052535020546573742045554D312930270603550405132038393034343034353131383432373438343830303030303030303031313632383122302006035504030C197379736D6F45554943432D49325420546573742065554943433059301306072A8648CE3D020106082A8648CE3D03010703420004BD2C55B28B4E801CA0B14F195788FD86C7FF49764C88A2934C69594A26FF647549F3F16060BD9C8D793D95D0126FA429C94966FE7842967263795A73C498F1DBA36B3069301D0603551D0E04160414E24191C0ECCEA8FC45926196EF1A2E53D5E6CD06301F0603551D23041830168014DD3DA24D350C1CC5D0AF0965F40EC34C5EE409F1300E0603551D0F0101FF04040302078030170603551D200101FF040D300B3009060767811201020101300A06082A8648CE3D0403020348003045022100E3BF7BAF5106E51656E315B7FED1D6F8360CA0F4D70ECB8D5AD38E159DE4A9C702203C3B11B748EC4788D8C62A6D75C13B0959CB56A8C2D68DD9C7C66C0615AACE73", "ipaCapabilities": "300B8005000001000181020001", "deviceInfo": "3008800412345678A100", "notificationsList": "A0819CBF378198BF27528010E0F1356728A44720B219A3B70C9DF57EBF2F2E800102810207800C1974657374736D6470706C7573312E6578616D706C652E636F6D5A0A989444999999990930F1060388370AA208A1068001028101095F37407FA95E72677338D953EE62395D7BCDC365BF217DFE6DAF315A98503F9DEF97103EAFBA7EDB5E16621BA14061354A75390FF0E8332B26AC31C8E2C9FAA6C07358"}}}], "debuginfo": "1234...ABCD..."}

Since we used the tagList "80BF20BF228384A5A688A9BF2B", which includes all possible tags to request, we get a lot of information back. The returned data fields are in their ASN.1 encoded representation unless the requested tag consists of a single primitive type (e.g. associationToken).

Setting a Parameters in the euicc Table

Even though the euicc table is populated automatically, it may still be that the REST API user wants to adjust certain parameters. Let's assume that we have a setup that mostly uses consumer eUICCs in an IoT emulation mode. Now we want to add a native IoT eUICC. Let's say the card uses a root CI that we do not have configured in sys.config yet, but we have the public key. Also the card has been used for experiments with PSMOs already, so the counterValue is somewhere in the upper three digits range and not at 1 as it would be for a virgin eUICC.

In this case we would craft an order like this:

{ "eidValue" : "'$EID'", "order" : { "euicc": [ { "counterValue" : 1000 }, { "consumerEuicc" : false }, { "signAlgo" : "prime256v1" }, { "signPubKey" : "04BD2C55B28B4E801CA0B14F195788FD86C7FF49764C88A2934C69594A26FF647549F3F16060BD9C8D793D95D0126FA429C94966FE7842967263795A73C498F1DB" } ] } }'

We would edit the order into tryme_set_euicc_param.sh and run the script:

./tryme_set_euicc_param.sh X 12345678900000000000000000001234

The order will execute as an internal process. This means that no IPAd interaction is involved. However, on the REST API the behavior will not be any different, except that the status will change from new to done directly. When all changes to the euicc table are made accordingly, we should get a result like this:

{"status": "done", "timestamp": "1721309044", "resource": {"eidValue": "12345678900000000000000000001234", "order": {"euicc": [{"counterValue": 1000}, {"consumerEuicc": false}, {"signAlgo": "prime256v1"}, {"signPubKey": "04BD2C55B28B4E801CA0B14F195788FD86C7FF49764C88A2934C69594A26FF647549F3F16060BD9C8D793D95D0126FA429C94966FE7842967263795A73C498F1DB"}]}}, "outcome": [{"euiccUpdateResult": "ok"}], "debuginfo": "836400046E6F6E65"}

Now the eIM will treat the eUICC as a native IoT eUICC, a proper public key set and the counter value is high enough so that we can sign new eUICC packages correctly.